运行时对象

Alembic 的“运行时”涉及 EnvironmentContext 和 MigrationContext 对象。这些对象在命令加载 env.py 脚本并继续进行迁移操作时发挥作用。

环境上下文

EnvironmentContext 类提供了 env.py 脚本中使用的大部分 API。在 env.py 中，实例化的 EnvironmentContext 通过名为 alembic.context 的特殊代理模块提供。也就是说，你可以像导入常规 Python 模块一样导入 alembic.context，你调用它的每个名称最终都会路由到当前正在使用的 EnvironmentContext。

具体来说，env.py 中使用的关键方法是 EnvironmentContext.configure()，它确定有关如何访问数据库的所有详细信息。

class alembic.runtime.environment.EnvironmentContext(config: Config, script: ScriptDirectory, **kw: Any)

env.py 脚本中提供的配置外观。

EnvironmentContext 充当 MigrationContext 的更基础对象的外观，以及 Config 的某些方面，在大多数 Alembic 命令调用的 env.py 脚本的上下文中。

EnvironmentContext 通常在 alembic.command 中的命令运行时实例化。然后它在 alembic.context 模块中使其在命令的范围内可用。在 env.py 脚本中，可以通过导入此模块获得当前 EnvironmentContext。

EnvironmentContext 还支持以编程方式使用。在此级别，它充当 Python 上下文管理器，也就是说，旨在使用 with: 语句使用。EnvironmentContext 的典型用法

from alembic.config import Config
from alembic.script import ScriptDirectory

config = Config()
config.set_main_option("script_location", "myapp:migrations")
script = ScriptDirectory.from_config(config)


def my_function(rev, context):
    '''do something with revision "rev", which
    will be the current database revision,
    and "context", which is the MigrationContext
    that the env.py will create'''


with EnvironmentContext(
    config,
    script,
    fn=my_function,
    as_sql=False,
    starting_rev="base",
    destination_rev="head",
    tag="sometag",
):
    script.run_env()

上述脚本将在迁移环境中调用 env.py 脚本。如果且当 env.py 调用 MigrationContext.run_migrations() 时，MigrationContext 将调用上述 my_function() 函数，同时将自身上下文以及数据库中的当前修订版作为参数提供给该函数。

注意

对于除完全调用迁移脚本之外的大多数 API 用法，MigrationContext 和 ScriptDirectory 对象可以创建并直接使用。仅当您需要实际调用迁移环境中存在的 env.py 模块时，才仅需要 EnvironmentContext 对象。

构造一个新的 EnvironmentContext。

参数:

• config – 一个 Config 实例。

• script – 一个 ScriptDirectory 实例。

• **kw – 关键字选项，当调用 EnvironmentContext.configure() 时，这些选项最终将传递给 MigrationContext。

begin_transaction() → _ProxyTransaction | ContextManager[None]

返回一个上下文管理器，它将一个操作包含在一个“事务”中，该事务由环境的离线和事务性 DDL 设置定义。

例如：

with context.begin_transaction():
    context.run_migrations()

begin_transaction() 旨在“做正确的事情”，而不管调用上下文如何

• 如果 is_transactional_ddl() 为 False，则返回一个“不执行任何操作”的上下文管理器，否则不会产生任何事务状态或指令。

• 如果 is_offline_mode() 为 True，则返回一个上下文管理器，该管理器将调用 DefaultImpl.emit_begin() 和 DefaultImpl.emit_commit() 方法，这些方法将在输出流上生成字符串指令 BEGIN 和 COMMIT，由目标后端呈现（例如，SQL Server 将发出 BEGIN TRANSACTION）。

• 否则，调用 sqlalchemy.engine.Connection.begin() 在当前在线连接上，它返回一个 sqlalchemy.engine.Transaction 对象。此对象划定一个真实的事务，并且本身是一个上下文管理器，如果引发异常，它将回滚。

请注意，一个具有更具体事务需求的自定义 env.py 脚本当然可以直接操作 Connection 以在“在线”模式下生成事务状态。

config: Config = None

表示配置文件内容以及其中以编程方式设置的其他变量的 Config 实例。

configure(connection: Connection | None = None, url: str | URL | None = None, dialect_name: str | None = None, dialect_opts: Dict[str, Any] | None = None, transactional_ddl: bool | None = None, transaction_per_migration: bool = False, output_buffer: TextIO | None = None, starting_rev: str | None = None, tag: str | None = None, template_args: Dict[str, Any] | None = None, render_as_batch: bool = False, target_metadata: MetaData | Sequence[MetaData] | None = None, include_name: IncludeNameFn | None = None, include_object: IncludeObjectFn | None = None, include_schemas: bool = False, process_revision_directives: ProcessRevisionDirectiveFn | None = None, compare_type: bool | CompareType = True, compare_server_default: bool | CompareServerDefault = False, render_item: RenderItemFn | None = None, literal_binds: bool = False, upgrade_token: str = 'upgrades', downgrade_token: str = 'downgrades', alembic_module_prefix: str = 'op.', sqlalchemy_module_prefix: str = 'sa.', user_module_prefix: str | None = None, on_version_apply: OnVersionApplyFn | None = None, **kw: Any) → None

在此 EnvironmentContext 中配置 MigrationContext，它将为一系列迁移脚本提供数据库连接和其他配置。

EnvironmentContext 上的许多方法要求在调用此方法后才能发挥作用，因为它们最终需要具有数据库访问权限或至少访问正在使用的方言。这样做的内容已记录在案。

configure() 所需的重要内容是确定正在使用哪种数据库方言。仅当 MigrationContext 在“在线”模式下使用时，才需要与该数据库的实际连接。

如果 is_offline_mode() 函数返回 True，则此处不需要连接。否则，connection 参数应作为 sqlalchemy.engine.Connection 的实例出现。

此函数通常在迁移环境中的 env.py 脚本中调用。对一次调用可以多次调用它。最近一次调用它的 Connection 将在下次调用 run_migrations() 时操作。

常规参数

参数:

• connection – 在“联机”模式下用于 SQL 执行的 Connection。如果存在，还用于确定所用方言的类型。

• url – 字符串数据库 URL 或 sqlalchemy.engine.url.URL 对象。如果未传递 connection，则将从中派生所用方言的类型。

• dialect_name – 方言的字符串名称，如“postgresql”、“mssql”等。如果未传递 connection 和 url，则将从中派生所用方言的类型。

• dialect_opts – 传递给方言构造函数的选项字典。

• transactional_ddl – 强制使用“事务性”DDL 或关闭；否则，这将默认为正在使用的方言是否支持它。

• transaction_per_migration – 如果为 True，将每个迁移脚本嵌套在一个事务中，而不是运行整个迁移系列。

• output_buffer – 当 --sql 选项用于生成 SQL 脚本时，将用于文本输出的文件状对象。如果没有在此处传递，并且 Config 对象上也没有，则默认为 sys.stdout。此处的值将覆盖 Config 对象的值。

• output_encoding – 当使用 --sql 生成 SQL 脚本时，将此编码应用于字符串输出。

• literal_binds –

  当使用 --sql 生成 SQL 脚本时，将 literal_binds 标志传递给编译器，以便将通常作为绑定参数的任何文字值转换为普通字符串。

  警告

  方言通常只能处理字符串和数字等简单数据类型以进行自动文字生成。日期、区间和其他数据类型可能仍需要手动格式化，通常使用 Operations.inline_literal()。

  注意

  在不支持此功能的 0.8 之前的 SQLAlchemy 版本中，将忽略 literal_binds 标志。

  另请参阅

  Operations.inline_literal()

• starting_rev – 使用 --sql 模式时覆盖“起始修订”参数。

• tag – 供自定义 env.py 脚本使用的字符串标记。通过 --tag 选项设置，可在此处覆盖。

• template_args – 运行“修订”命令时将添加到模板参数环境中的模板参数字典。请注意，仅当使用 –autogenerate 选项或 alembic.ini 文件中存在“revision_environment=true”选项时，脚本环境才会在“修订”命令中运行。

• version_table – Alembic 版本表的名称。默认值为 'alembic_version'。

• version_table_schema – 可选模式，用于放置版本表。

• version_table_pk – 布尔值，表示 Alembic 版本表是否应使用“value”列的主键约束；仅在首次创建表时生效。默认为 True；设置为 False 不应是必需的，并且出于向后兼容性的原因而存在。

• on_version_apply –

  一个可调用对象或可调用对象的集合，用于针对每个迁移步骤运行。这些可调用对象将按给定的顺序运行，针对每个迁移步骤运行一次，在应用相应操作后但在其事务最终确定之前运行。每个可调用对象不接受位置参数，并接受以下关键字参数

  • ctx：运行迁移的 MigrationContext，

  • step：表示当前正在应用的步骤的 MigrationInfo，

  • heads：表示当前头的版本字符串集合，

  • run_args：传递给 run_migrations() 的 **kwargs。

当使用 --autogenerate 功能运行 alembic revision 时，特定于自动生成功能的参数

参数:

• target_metadata – sqlalchemy.schema.MetaData 对象或 MetaData 对象序列，将在自动生成期间进行咨询。每个 MetaData 中存在的表将与目标 Connection 上本地可用的表进行比较，以生成升级/降级操作的候选对象。

• compare_type –

  指示自动生成操作期间的类型比较行为。默认为 True，开启类型比较，这在大多数后端上具有良好的准确性。有关示例以及其他类型比较选项的信息，请参见 比较类型。设置为 False，这将禁用类型比较。还可以传递一个可调用对象来提供自定义类型比较，有关更多详细信息，请参见 比较类型。

  在版本 1.12.0 中更改：EnvironmentContext.configure.compare_type 的默认值已更改为 True。

  另请参阅

  比较类型

  EnvironmentContext.configure.compare_server_default

• compare_server_default –

  指示自动生成操作期间的服务器默认比较行为。默认为 False，这会禁用服务器默认比较。设置为 True 以启用服务器默认比较，其准确性因后端而异。

  要自定义服务器默认比较行为，可以指定一个可调用项，该可调用项可以在自动生成操作期间过滤服务器默认比较。自动生成操作期间的默认值。此可调用项的格式为

  def my_compare_server_default(context, inspected_column,
              metadata_column, inspected_default, metadata_default,
              rendered_metadata_default):
      # return True if the defaults are different,
      # False if not, or None to allow the default implementation
      # to compare these defaults
      return None
  
  context.configure(
      # ...
      compare_server_default = my_compare_server_default
  )
  

  inspected_column 是 sqlalchemy.engine.reflection.Inspector.get_columns() 返回的字典结构，而 metadata_column 是来自本地模型环境的 sqlalchemy.schema.Column。

  None 的返回值表示允许默认服务器默认比较继续进行。请注意，某些后端（例如 Postgresql）实际上会在数据库端执行两个默认值以比较相等性。

  另请参阅

  EnvironmentContext.configure.compare_type

• include_name –

  一个可调用函数，它有机会根据其名称为任何数据库反射对象返回 True 或 False，包括在 EnvironmentContext.configure.include_schemas 标志设置为 True 时数据库架构名称。

  该函数接受以下位置参数

  • 名称：对象的名称，例如模式名称或表名称。当指示数据库连接的默认模式名称时，将为 None。

  • 类型：描述对象类型的字符串；当前为 "模式"、"表"、"列"、"索引"、"唯一约束" 或 "外键约束"

  • 父名称：相对于给定名称的“父”对象名称的字典。此字典中的键可能包括："模式名称"、"表名称" 或 "模式限定表名称"。

  例如

  def include_name(name, type_, parent_names):
      if type_ == "schema":
          return name in ["schema_one", "schema_two"]
      else:
          return True
  
  context.configure(
      # ...
      include_schemas = True,
      include_name = include_name
  )
  

  另请参阅

  控制要自动生成的内容

  EnvironmentContext.configure.include_object

  EnvironmentContext.configure.include_schemas

• include_object –

  一个可调用函数，它有机会为任何对象返回 True 或 False，指示给定对象是否应在自动生成扫描中考虑。

  该函数接受以下位置参数

  • 对象：SchemaItem 对象，例如 Table、Column、Index UniqueConstraint 或 ForeignKeyConstraint 对象

  • 名称：对象的名称。这通常可以通过 object.name 获得。

  • 类型：描述对象类型的字符串；当前为 "table"、"column"、"index"、"unique_constraint" 或 "foreign_key_constraint"

  • 反射：如果给定的对象是基于表反射产生的，则为 True，如果它来自本地 MetaData 对象，则为 False。

  • 比较对象：要比较的对象（如果可用），否则为 None。

  例如

  def include_object(object, name, type_, reflected, compare_to):
      if (type_ == "column" and
          not reflected and
          object.info.get("skip_autogenerate", False)):
          return False
      else:
          return True
  
  context.configure(
      # ...
      include_object = include_object
  )
  

  对于在 EnvironmentContext.configure.include_schemas 设置为 True 时从目标数据库中省略特定架构的用例，可以检查传递给钩子的每个 schema 属性 Table 对象，但是使用 EnvironmentContext.configure.include_name 钩子在对象反射发生之前对架构进行筛选要有效得多。

  另请参阅

  控制要自动生成的内容

  EnvironmentContext.configure.include_name

  EnvironmentContext.configure.include_schemas

• render_as_batch –

  如果为 True，则将更改表中元素的命令放在 with batch_alter_table(): 指令下，以便进行批处理迁移。

  另请参阅

  为 SQLite 和其他数据库运行“批处理”迁移

• include_schemas –

  如果为 True，autogenerate 将扫描 SQLAlchemy get_schema_names() 方法找到的所有模式，并包括在所有这些模式中找到的表中的所有差异。使用此选项时，您可能还需要使用 EnvironmentContext.configure.include_name 参数来指定一个可用于筛选要包括的表/模式的可调用对象。

  另请参阅

  控制要自动生成的内容

  EnvironmentContext.configure.include_name

  EnvironmentContext.configure.include_object

• render_item –

  可用于覆盖如何为 autogenerate 呈现任何模式项（即列、约束、类型等）的可调用对象。可调用对象接收一个描述对象类型的字符串、对象和自动生成上下文。如果它返回 False，将使用默认呈现方法。如果它返回 None，该项将不会在 Table 构造的上下文中呈现，即，可用于跳过 op.create_table() 中的列或约束

  def my_render_column(type_, col, autogen_context):
      if type_ == "column" and isinstance(col, MySpecialCol):
          return repr(col)
      else:
          return False
  
  context.configure(
      # ...
      render_item = my_render_column
  )
  

  类型字符串的可用值包括："column"、"primary_key"、"foreign_key"、"unique"、"check"、"type"、"server_default"。

  另请参阅

  影响类型本身的呈现

• upgrade_token – 当 autogenerate 完成时，在呈现 script.py.mako 时，候选升级操作的文本将出现在此模板变量中。默认为 upgrades。

• downgrade_token – 当 autogenerate 完成时，在呈现 script.py.mako 时，候选降级操作的文本将出现在此模板变量中。默认为 downgrades。

• alembic_module_prefix – 当 autogenerate 指的是 Alembic alembic.operations 构造时，将使用此前缀（即 op.create_table）。默认为“op.”。可以是 None 来表示没有前缀。

• sqlalchemy_module_prefix – 当 autogenerate 指的是 SQLAlchemy Column 或类型类时，将使用此前缀（即 sa.Column("somename", sa.Integer)）。默认为“sa.”。可以是 None 来表示没有前缀。请注意，当呈现特定于方言的类型时，autogenerate 将使用方言模块名称来呈现它们，即 mssql.BIT()、postgresql.UUID()。

• user_module_prefix –

  当 autogenerate 指的是 SQLAlchemy 类型（例如 TypeEngine）时，其中模块名称不在 sqlalchemy 命名空间下，此前缀将在 autogenerate 中使用。如果保留其默认值 None，则类型的 __module__ 属性用于呈现导入模块。最好设置此属性，并让所有自定义类型都可从固定的模块空间中获得，以便针对模块中的重组对迁移文件进行未来验证。

  另请参阅

  控制模块前缀

• process_revision_directives –

  一个可调用函数，它将传递一个表示自动生成或普通“修订”操作的最终结果的结构，该结构可以被操作以影响alembic revision命令最终如何输出新的修订脚本。可调用的结构是

  def process_revision_directives(context, revision, directives):
      pass
  

  directives参数是一个包含单个MigrationScript指令的 Python 列表，该指令表示要生成的修订文件。此列表及其内容可以自由修改以生成任何一组命令。自定义修订生成部分显示了一个执行此操作的示例。context参数是在使用的MigrationContext，并且revision是表示数据库当前修订的修订标识符元组。

  在将--autogenerate选项传递给alembic revision时，始终调用可调用项。如果未传递--autogenerate，则仅当在 Alembic 配置中将revision_environment变量设置为 True 时才调用可调用项，在这种情况下，给定的directives集合将包含空的UpgradeOps和DowngradeOps集合，用于.upgrade_ops和.downgrade_ops。--autogenerate选项本身可以通过检查context.config.cmd_opts.autogenerate来推断。

  可调用函数可以选择是 Rewriter 对象的实例。这是一个帮助对象，用于生成自动生成流重写器函数。

  另请参阅

  自定义修订版生成

  使用重写器进行细粒度自动生成

  command.revision.process_revision_directives

特定于各个后端的参数

参数:

• mssql_batch_separator – 生成脱机 SQL Server 迁移时，放置在每个语句之间的“批处理分隔符”。默认为 GO。请注意，这除了每个语句末尾的惯用分号 ; 之外；SQL Server 认为“批处理分隔符”表示单个语句执行的结束，并且不能在一个步骤中对某些相关操作进行分组。

• oracle_batch_separator – 生成脱机 Oracle 迁移时，放置在每个语句之间的“批处理分隔符”。默认为 /。Oracle 不会像大多数其他后端那样在语句之间添加分号。

execute(sql: Executable | str, execution_options: Dict[str, Any] | None = None) → None

使用当前更改上下文执行给定的 SQL。

execute() 的行为与 Operations.execute() 的行为相同。请参阅该函数的文档以获取包括注意事项和限制在内的完整详细信息。

此函数要求 MigrationContext 已通过 configure() 首次提供。

get_bind() → Connection

返回当前“绑定”。

在“联机”模式下，这是 sqlalchemy.engine.Connection 当前用于向数据库发出 SQL。

此函数要求 MigrationContext 已通过 configure() 首次提供。

get_context() → MigrationContext

返回当前 MigrationContext 对象。

如果尚未调用 EnvironmentContext.configure()，则引发异常。

get_head_revision() → str | Tuple[str, ...] | None

返回“头部”脚本修订的十六进制标识符。

如果脚本目录有多个头部，此方法将引发 CommandError；应优先使用 EnvironmentContext.get_head_revisions()。

此函数不要求已配置 MigrationContext。

另请参阅

EnvironmentContext.get_head_revisions()

get_head_revisions() → str | Tuple[str, ...] | None

返回“heads”脚本修订版的十六进制标识符。

这会返回一个元组，其中包含脚本目录中所有 heads 的版本号。

此函数不要求已配置 MigrationContext。

get_revision_argument() → str | Tuple[str, ...] | None

获取“目标”修订版参数。

这通常是传递给 upgrade 或 downgrade 命令的参数。

如果指定为 head，则返回实际版本号；如果指定为 base，则返回 None。

此函数不要求已配置 MigrationContext。

get_starting_revision_argument() → str | Tuple[str, ...] | None

如果使用 start:end 传递修订版，则返回“起始修订版”参数。

这仅在“离线”模式下有意义。如果没有可用值或未配置值，则返回 None。

此函数不要求已配置 MigrationContext。

get_tag_argument() → str | None

如果存在，返回为 --tag 参数传递的值。

--tag 参数不被 Alembic 直接使用，但可用于希望使用它的自定义 env.py 配置；特别是对于希望生成标记文件名脱机生成脚本。

此函数不要求已配置 MigrationContext。

另请参阅

EnvironmentContext.get_x_argument() - 一种更新、更开放的系统，可通过命令行扩展 env.py 脚本。

get_x_argument(as_dictionary: Literal[False]) → List[str]

get_x_argument(as_dictionary: Literal[True]) → Dict[str, str]

get_x_argument(as_dictionary: bool = False) → List[str] | Dict[str, str]

返回为 -x 参数传递的值（如果有）。

-x 参数是一个开放式标志，允许在命令行中传递任何用户定义的值，然后可在此处供自定义 env.py 脚本使用。

返回值是一个列表，直接从 argparse 结构返回。如果传递了 as_dictionary=True，则使用 key=value 格式将 x 参数解析到字典中，然后返回该字典。如果参数中没有 =，则值为一个空字符串。

在 1.13.1 版本中更改：当在没有 = 符号的情况下传递参数时，支持 as_dictionary=True。

例如，要支持在命令行中传递数据库 URL，可以像这样修改标准 env.py 脚本

cmd_line_url = context.get_x_argument(
    as_dictionary=True).get('dbname')
if cmd_line_url:
    engine = create_engine(cmd_line_url)
else:
    engine = engine_from_config(
            config.get_section(config.config_ini_section),
            prefix='sqlalchemy.',
            poolclass=pool.NullPool)

然后通过将 alembic 脚本作为运行

alembic -x dbname=postgresql://user:pass@host/dbname upgrade head

此函数不要求已配置 MigrationContext。

另请参阅

EnvironmentContext.get_tag_argument()

Config.cmd_opts

is_offline_mode() → bool

如果当前迁移环境在“离线模式”下运行，则返回 True。

这取决于传递的 --sql 标志，为 True 或 False。

此函数不要求已配置 MigrationContext。

is_transactional_ddl() → bool

如果上下文配置为期望事务性 DDL 兼容后端，则返回 True。

这默认为所用数据库的类型，并且可以被 transactional_ddl 参数覆盖，该参数用于 configure()

此函数要求 MigrationContext 已通过 configure() 首次提供。

run_migrations(**kw: Any) → None

根据当前命令行配置以及当前数据库连接中存在（或不存在）的版本信息运行迁移（如果存在）。

该函数接受可选 **kw 参数。如果传递这些参数，则它们将直接发送到每个目标修订文件中的 upgrade() 和 downgrade() 函数。通过修改 script.py.mako 文件，以便 upgrade() 和 downgrade() 函数接受参数，可以在这里传递参数，以便可以从自定义 env.py 脚本将上下文信息（通常是用于标识正在使用的特定数据库的信息）传递到迁移函数。

此函数要求 MigrationContext 已通过 configure() 首次提供。

script: ScriptDirectory = None

ScriptDirectory 的一个实例，它提供对 versions/ 目录中版本文件的编程访问。

static_output(text: str) → None

直接向“离线”SQL流发出文本。

通常，这是为了发出以 – 开头的注释。该语句不会被视为 SQL 执行，不会添加 ; 或批处理分隔符等。

迁移上下文

MigrationContext 处理针对数据库后端执行的实际工作，因为迁移操作正在进行。它通常不会向最终用户公开，除非使用 on_version_apply 回调挂钩。

类 alembic.runtime.migration.MigrationContext(方言: 方言, 连接: 连接 | 无, 选项: 字典[字符串, 任意], 环境上下文: 环境上下文 | 无 = 无)

表示提供给迁移脚本的数据库状态。

MigrationContext 是从 Alembic 角度来看，实际数据库连接的前端，或者给定特定数据库方言的字符串输出流。

在 env.py 脚本内部时，MigrationContext 可通过 EnvironmentContext.get_context() 方法获得，该方法在 alembic.context 中提供

# from within env.py script
from alembic import context

migration_context = context.get_context()

对于在 env.py 脚本之外使用，例如对于想要在数据库中检查当前版本的实用程序例程，MigrationContext.configure() 方法用于创建新的 MigrationContext 对象。例如，要使用 MigrationContext.get_current_revision() 获取数据库中的当前修订版

# in any application, outside of an env.py script
from alembic.migration import MigrationContext
from sqlalchemy import create_engine

engine = create_engine("postgresql://mydatabase")
conn = engine.connect()

context = MigrationContext.configure(conn)
current_rev = context.get_current_revision()

上述上下文还可用于使用 Operations 实例生成 Alembic 迁移操作

# in any application, outside of the normal Alembic environment
from alembic.operations import Operations

op = Operations(context)
op.alter_column("mytable", "somecolumn", nullable=True)

autocommit_block() → Iterator[None]

为支持 AUTOCOMMIT 隔离级别的数据库输入一个“自动提交”块。

此特殊指令旨在支持偶尔的数据库 DDL 或系统操作，该操作必须明确在任何类型的交易块之外运行。PostgreSQL 数据库平台是此类操作最常见的目标，因为其许多 DDL 操作必须在交易块之外运行，即使数据库整体支持事务 DDL。

此方法在迁移脚本中用作上下文管理器，通过调用 Operations.get_context() 来检索 MigrationContext，然后使用 with: 语句调用 MigrationContext.autocommit_block()

def upgrade():
    with op.get_context().autocommit_block():
        op.execute("ALTER TYPE mood ADD VALUE 'soso'")

在上面，发出了一个 PostgreSQL “ALTER TYPE..ADD VALUE”指令，该指令必须在数据库级别的交易块之外运行。MigrationContext.autocommit_block() 方法利用 SQLAlchemy AUTOCOMMIT 隔离级别设置，该设置对于 psycogp2 DBAPI 对应于 connection.autocommit 设置，以确保数据库驱动程序不在 DBAPI 级别交易块内。

警告

根据需要，在该块之前进行数据库事务无条件提交。这意味着在整个迁移操作完成之前，在该操作之前的迁移运行将被提交。

建议当应用程序包含带有“自动提交”块的迁移时，使用 EnvironmentContext.transaction_per_migration，以便调用环境调整为预期每个文件进行短暂的迁移，无论其中是否有一个自动提交块。

begin_transaction(_per_migration: bool = False) → _ProxyTransaction | ContextManager[None]

开始迁移操作的逻辑事务。

此方法在 env.py 脚本中用于界定一系列迁移的外部“事务”开始的位置。示例

def run_migrations_online():
    connectable = create_engine(...)

    with connectable.connect() as connection:
        context.configure(
            connection=connection, target_metadata=target_metadata
        )

        with context.begin_transaction():
            context.run_migrations()

上面，MigrationContext.begin_transaction() 用于界定 MigrationContext.run_migrations() 操作周围的外部逻辑事务发生的位置。

“逻辑”事务意味着该操作可能对应于实际数据库事务，也可能不对应。如果目标数据库支持事务性 DDL（或 EnvironmentContext.configure.transactional_ddl 为真），EnvironmentContext.configure.transaction_per_migration 标志未设置，并且迁移针对的是实际数据库连接（而不是使用“脱机” --sql 模式），则将启动实际事务。如果 --sql 模式生效，则该操作将对应于向字符串输出中发出的“BEGIN”等字符串。

返回的对象是 Python 上下文管理器，它仅应在 with: 语句的上下文中使用，如上所示。该对象没有其他保证的 API 特性。

另请参阅

MigrationContext.autocommit_block()

property bind: Connection | None

返回当前“绑定”。

在联机模式下，这是 sqlalchemy.engine.Connection 的一个实例，并且适用于执行 SQLAlchemy Core 文档中描述的任何类型的临时用法，以及与 sqlalchemy.schema.Table.create() 和 sqlalchemy.schema.MetaData.create_all() 方法一起使用 Table、MetaData。

请注意，当启用“标准输出”模式时，此绑定将是一个“模拟”连接处理程序，它无法返回结果，并且仅适用于非常有限的命令子集。

property config: Config | None

返回当前环境（如果有）使用的 Config。

classmethod configure(connection: Connection | None = None, url: str | URL | None = None, dialect_name: str | None = None, dialect: Dialect | None = None, environment_context: EnvironmentContext | None = None, dialect_opts: Dict[str, str] | None = None, opts: Any | None = None) → MigrationContext

创建一个新的 MigrationContext。

这是一个通常由 EnvironmentContext.configure() 调用的工厂方法。

参数:

• connection – 一个 Connection，用于在“联机”模式下执行 SQL。如果存在，还用于确定正在使用的方言类型。

• url – 一个字符串数据库 URL，或 sqlalchemy.engine.url.URL 对象。如果未传递 connection，将从此处派生要使用的方言类型。

• dialect_name – 方言的字符串名称，例如“postgresql”、“mssql”等。如果未传递 connection 和 url，将从此处派生要使用的方言类型。

• opts – 选项字典。EnvironmentContext.configure() 接受的大多数其他选项都通过此字典传递。

execute(sql: Executable | str, execution_options: Dict[str, Any] | None = None) → None

执行 SQL 构造或字符串语句。

使用底层执行机制，即如果这是“离线模式”，则 SQL 会写入输出缓冲区，否则 SQL 会在当前 SQLAlchemy 连接上发出。

get_current_heads() → Tuple[str, ...]

返回目标数据库中表示的当前“头版本”元组。

对于没有分支的迁移流，这将是一个单一值，与 MigrationContext.get_current_revision() 的值同义。但是，当目标数据库中存在多个未合并的分支时，返回的元组将包含每个头的值。

如果这个 MigrationContext 在“离线”模式下配置，即使用 as_sql=True，那么 starting_rev 参数将在一个长度的元组中返回。

如果没有版本表，或者没有修订版，则返回一个空元组。

get_current_revision() → str | None

返回当前修订版，通常是数据库中 alembic_version 表中存在的修订版。

此方法仅用于不包含目标数据库中未合并分支的迁移流；如果存在多个分支，则会引发异常。为了与分支迁移支持兼容，以后应该优先使用 MigrationContext.get_current_heads() 而不是此方法。

如果这个 MigrationContext 在“离线”模式下配置，即使用 as_sql=True，则会返回 starting_rev 参数（如果存在）。

run_migrations(**kw: Any) → None

运行为此 MigrationContext 建立的迁移脚本（如果存在）。

alembic.command 中的命令会设置一个函数，该函数最终会作为 fn 参数传递给 MigrationContext。此函数表示在调用 MigrationContext.run_migrations()（通常在迁移环境的 env.py 脚本中调用）时将完成的“工作”。然后，“工作函数”提供一个可迭代的版本可调用项和其他版本信息，在 upgrade 或 downgrade 命令的情况下，它们是要调用的版本脚本的列表。其他命令不产生任何结果，如果某个命令希望对数据库运行其他操作（例如 current 或 stamp 命令）。

参数:

**kw – 此处的关键字参数将传递给每个迁移可调用项，即修订脚本中的 upgrade() 或 downgrade() 方法。

stamp(script_directory: ScriptDirectory, revision: str) → None

使用特定修订版标记版本表。

此方法计算给定修订版可应用到的分支，并更新这些分支，就好像它们已迁移到该修订版（向上或向下）。如果没有当前分支包含该修订版，则将其添加为新分支头。