操作参考

此文件提供有关 Alembic 迁移指令的文档。

此处的指令在用户定义的迁移文件中使用，在 upgrade() 和 downgrade() 函数中，以及这些函数进一步调用的任何函数中。

所有指令都作为名为 Operations 的类的成员方法存在。当迁移脚本运行时，此对象通过 alembic.op 数据成员向脚本提供，该数据成员是 Operations 的实际实例的代理。目前，alembic.op 是一个真正的 Python 模块，其中填充了 Operations 上每个方法的单独代理，因此可以安全地从 alembic.op 命名空间导入符号。

Operations 系统也是完全可扩展的。有关此内容的详细信息，请参阅 操作插件。

对 操作指令 方法的一个关键设计理念是，它们在最大程度上内部生成适当的 SQLAlchemy 元数据，通常涉及 Table 和 Constraint 对象。这样迁移指令就可以仅用涉及的字符串名称和/或标志来给出。此规则的例外包括 add_column() 和 create_table() 指令，它们需要完整的 Column 对象，尽管表元数据仍然在此生成。

此处的函数都需要在 env.py 脚本中首先配置 MigrationContext，通常通过 EnvironmentContext.configure()。在正常情况下，它们会从实际迁移脚本调用，而该脚本本身会由 EnvironmentContext.run_migrations() 方法调用。

类 alembic.operations.AbstractOperations(migration_context: MigrationContext, impl: BatchOperationsImpl | None = None)

Operations 和 BatchOperations 的基类。

在版本 1.11.0 中添加。

构造一个新的 Operations

参数:

migration_context – 一个 MigrationContext 实例。

batch_alter_table(table_name: str, schema: str | None = None, recreate: Literal['auto', 'always', 'never'] = 'auto', partial_reordering: Tuple[Any, ...] | None = None, copy_from: Table | None = None, table_args: Tuple[Any, ...] = (), table_kwargs: Mapping[str, Any] = {}, reflect_args: Tuple[Any, ...] = (), reflect_kwargs: Mapping[str, Any] = {}, naming_convention: Dict[str, str] | None = None) → Iterator[BatchOperations]

批量调用一系列针对每个表的迁移。

批量模式允许将针对特定表的系列操作从语法上组合在一起，并允许使用其他表的迁移模式，尤其是 SQLite 所需的“重新创建”迁移样式。

“重新创建”样式如下

1. 使用临时名称，根据批量中的迁移指令创建具有新规范的新表。

2. 将数据从现有表复制到新表。

3. 删除现有表。

4. 将新表重命名为现有表名。

该指令默认仅在 SQLite 后端使用“重新创建”样式，并且仅在存在需要此格式的指令时才使用，例如除 add_column() 之外的任何内容。其他后端的批量操作将使用标准的 ALTER TABLE 操作进行。

该方法用作上下文管理器，它返回 BatchOperations 的一个实例；此对象与 Operations 相同，只是省略了表名和架构名。例如

with op.batch_alter_table("some_table") as batch_op:
    batch_op.add_column(Column("foo", Integer))
    batch_op.drop_column("bar")

当上下文结束时，将立即调用上下文管理器中的操作。当针对 SQLite 运行时，如果迁移包括 SQLite 的 ALTER TABLE 不支持的操作，则整个表将被复制到一个具有新规范的新表中，同时也会移动所有数据。

默认情况下，复制操作使用反射来检索表的当前结构，因此 batch_alter_table() 在此模式中要求以“在线”模式运行迁移。copy_from 参数可以传递，它引用现有的 Table 对象，这将绕过此反射步骤。

注意

表复制操作当前不会复制 CHECK 约束，并且可能不会复制未命名的 UNIQUE 约束，就像在 SQLite 中可能发生的那样。有关解决方法，请参阅 处理约束 一节。

参数:

• table_name – 表名

• schema – 可选架构名称。

• recreate – 在什么情况下应重新创建表。在默认值 "auto" 中，如果存在 add_column()、create_index() 或 drop_index() 以外的任何操作，SQLite 方言将重新创建表。其他选项包括 "always" 和 "never"。

• copy_from –

  可选 Table 对象，它将充当正在复制的表的结构。如果省略，则使用表反射来检索表的结构。

  另请参阅

  在离线模式下工作

  reflect_args

  reflect_kwargs

• reflect_args – 将应用于正在反映/复制的表结构的一系列附加位置参数；这可用于将列和约束覆盖传递给将被反映的表，而不是使用 copy_from 传递整个 Table。

• reflect_kwargs – 将应用于正在复制的表结构的一系列附加关键字参数；这可用于将附加表和反映选项传递给将被反映的表，而不是使用 copy_from 传递整个 Table。

• table_args – 除了从源表复制的参数外，将应用于创建的新 Table 的一系列附加位置参数。这可用于提供附加约束，例如可能无法反映的 CHECK 约束。

• table_kwargs – 除了从源表复制的参数外，将应用于创建的新 Table 的一系列附加关键字参数。这可用于提供可能无法反映的附加表选项。

• naming_convention –

  在 命名约定的集成到操作中，自动生成 中描述的形式的命名约定字典，它将应用于 MetaData 在反映过程中。如果要删除 SQLite 约束，则通常需要这样做，因为在该后端反映这些约束时，这些约束将没有名称。需要 SQLAlchemy 0.9.4 或更高版本。

  另请参阅

  删除未命名或命名的外键约束

• partial_reordering –

  元组列表，每个元组都建议在新建表中对两列或多列进行排序。需要将 batch_alter_table.recreate 设置为 "always"。示例，给定一个包含“a”、“b”、“c”和“d”列的表

  指定所有列的顺序

  with op.batch_alter_table(
      "some_table",
      recreate="always",
      partial_reordering=[("c", "d", "a", "b")],
  ) as batch_op:
      pass
  

  确保“d”出现在“c”之前，“b”出现在“a”之前

  with op.batch_alter_table(
      "some_table",
      recreate="always",
      partial_reordering=[("d", "c"), ("b", "a")],
  ) as batch_op:
      pass
  

  未包含在 partial_reordering 集合中的列的顺序是未定义的。因此，最好指定所有列的完整顺序以获得最佳结果。

注意

批量模式需要 SQLAlchemy 0.8 或更高版本。

另请参阅

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

f(name: str) → conv

指示已应用命名约定的字符串名称。

此功能与 SQLAlchemy naming_convention 功能相结合，以消除歧义，这些约束名称已应用命名约定，而另一些则没有。如果 "%(constraint_name)s" 令牌在命名约定中使用，则有必要这样做，以便可以识别此特定名称应保持固定。

如果 Operations.f() 用于约束，则命名约定不会生效

op.add_column("t", "x", Boolean(name=op.f("ck_bool_t_x")))

在上面，生成的 CHECK 约束将具有名称 ck_bool_t_x，无论是否使用命名约定。

或者，如果正在使用命名约定，并且未使用“f”，则名称将根据约定进行转换。如果 target_metadata 包含命名约定 {"ck": "ck_bool_%(table_name)s_%(constraint_name)s"}，则以下内容的输出

op.add_column(“t”, “x”, Boolean(name=”x”))

将为

CONSTRAINT ck_bool_t_x CHECK (x in (1, 0)))

当特定约束名称已转换时，该函数将在自动生成器的输出中呈现。

get_bind() → Connection

返回当前“bind”。

在正常情况下，这是 Connection 当前用于向数据库发出 SQL。

在 SQL 脚本上下文中，此值为 None。[TODO：验证这一点]

get_context() → MigrationContext

返回当前正在使用的 MigrationContext 对象。

classmethod implementation_for(op_cls: Any) → Callable[[_C], _C]

为给定的 MigrateOperation 注册一个实现。

这是操作扩展 API 的一部分。

另请参阅

操作插件 - 使用示例

inline_literal(value: str | int, type_: TypeEngine[Any] | None = None) → _literal_bindparam

生成一个“内联文字”表达式，适用于在 INSERT、UPDATE 或 DELETE 语句中使用。

在“离线”模式下使用 Alembic 时，CRUD 操作与 SQLAlchemy 围绕文字值（即它们被转换为绑定值并单独传递到 DBAPI 游标的 execute() 方法）的默认行为不兼容。离线 SQL 脚本需要将这些内容内联呈现。虽然应始终注意，内联文字值是处理不受信任输入的应用程序中的一个巨大的安全漏洞，但模式迁移不会在此上下文中运行，因此内联呈现文字是安全的，但高级类型（如日期）可能不会直接受 SQLAlchemy 支持。

请参阅 Operations.execute() 以了解 Operations.inline_literal() 的示例用法。

还可以将环境配置为尝试自动内联呈现“文字”值，适用于方言支持的那些简单类型；有关此最近添加的功能，请参阅 EnvironmentContext.configure.literal_binds。

参数:

• value – 要呈现的值。应支持字符串、整数和简单数字。布尔值、日期等其他类型可能尚未得到各种后端的支持。

• type_ – 可选 - 一个 sqlalchemy.types.TypeEngine 子类，用于声明此值类型。在 SQLAlchemy 表达式中，这通常会根据值本身的 Python 类型以及值的使用上下文自动派生。

另请参阅

EnvironmentContext.configure.literal_binds

invoke(operation: CreateTableOp) → Table

invoke(operation: AddConstraintOp | DropConstraintOp | CreateIndexOp | DropIndexOp | AddColumnOp | AlterColumnOp | AlterTableOp | CreateTableCommentOp | DropTableCommentOp | DropColumnOp | BulkInsertOp | DropTableOp | ExecuteSQLOp) → None

invoke(operation: MigrateOperation) → Any

给定一个 MigrateOperation，根据此 Operations 实例调用它。

类方法 register_operation(name: str, sourcename: str | None = None) → Callable[[Type[_T]], Type[_T]]

为该类注册一个新操作。

此方法通常用于向 Operations 类添加新操作，也可能向 BatchOperations 类添加新操作。所有 Alembic 迁移操作都是通过此系统实现的，但该系统也可作为公共 API 使用，以方便添加自定义操作。

另请参阅

操作插件

run_async(async_function: Callable[[...], Awaitable[_T]], *args: Any, **kw_args: Any) → _T

调用给定的异步可调用对象，将异步 AsyncConnection 作为第一个参数传递。

此方法允许从同步 upgrade() 或 downgrade() alembic 迁移方法中调用异步函数。

传递给可调用对象的异步连接与在迁移上下文中运行的连接共享相同的事务。

传递给此函数的任何其他 arg 或 kw_arg 都将传递给提供的异步函数。

注意

仅当使用异步方言调用 alembic 时才能调用此方法。

类 alembic.operations.Operations(migration_context: MigrationContext, impl: BatchOperationsImpl | None = None)

定义高级迁移操作。

每个操作对应于针对特定 MigrationContext 执行的某个模式迁移操作，而 MigrationContext 反过来表示与数据库或文件输出流的连接。

虽然 Operations 通常被配置为 EnvironmentContext.run_migrations() 方法的一部分，该方法从 env.py 脚本调用，但可以通过传入 MigrationContext 来创建独立的 Operations 实例，以用于常规 Alembic 迁移之外的用例。

from alembic.migration import MigrationContext
from alembic.operations import Operations

conn = myengine.connect()
ctx = MigrationContext.configure(conn)
op = Operations(ctx)

op.alter_column("t", "c", nullable=True)

请注意，从 0.8 开始，此类上的大多数方法都是使用 Operations.register_operation() 方法动态生成的。

构造一个新的 Operations

参数:

migration_context – MigrationContext 实例。

add_column(table_name: str, column: Column[Any], *, schema: str | None = None) → None

使用当前迁移上下文发出“添加列”指令。

例如：

from alembic import op
from sqlalchemy import Column, String

op.add_column("organization", Column("name", String()))

Operations.add_column() 方法通常对应于 SQL 命令“ALTER TABLE… ADD COLUMN”。在此命令的范围内，可以指示列的名称、数据类型、可空性和可选的服务器生成默认值。

注意

除了 NOT NULL 约束或单列 FOREIGN KEY 约束之外，其他类型的约束（如 PRIMARY KEY、UNIQUE 或 CHECK 约束）无法使用此方法生成；对于这些约束，请参阅 Operations.create_primary_key() 和 Operations.create_check_constraint() 等操作。特别是，以下 Column 参数被忽略

• primary_key - SQL 数据库通常不支持 ALTER 操作，该操作可以一次向现有的主键约束添加单个列，因此使用 Operations.create_primary_key() 方法会更加明确，该方法假设不存在现有的主键约束。

• unique - 使用 Operations.create_unique_constraint() 方法

• index - 使用 Operations.create_index() 方法

提供的 Column 对象可能包括 ForeignKey 约束指令，引用远程表名称。对于此特定类型的约束，Alembic 将自动发出第二个 ALTER 语句，以便单独添加单列 FOREIGN KEY 约束

from alembic import op
from sqlalchemy import Column, INTEGER, ForeignKey

op.add_column(
    "organization",
    Column("account_id", INTEGER, ForeignKey("accounts.id")),
)

传递给 Operations.add_column() 的 column 参数是 Column 构造，其使用方式与在 SQLAlchemy 中使用的方式相同。特别是，使用 server_default 参数指定值或函数以指示在数据库端生成列的默认值，而不是仅指定 Python 端默认值的 default

from alembic import op
from sqlalchemy import Column, TIMESTAMP, func

# specify "DEFAULT NOW" along with the column add
op.add_column(
    "account",
    Column("timestamp", TIMESTAMP, server_default=func.now()),
)

参数:

• table_name – 父表的字符串名称。

• column – 表示新列的 sqlalchemy.schema.Column 对象。

• schema – 在其中操作的可选架构名称。若要控制架构在默认行为之外的引用，请使用 SQLAlchemy 构造 quoted_name。

alter_column(table_name: str, column_name: str, *, nullable: bool | None = None, comment: str | Literal[False] | None = False, server_default: Any = False, new_column_name: str | None = None, type_: TypeEngine[Any] | Type[TypeEngine[Any]] | None = None, existing_type: TypeEngine[Any] | Type[TypeEngine[Any]] | None = None, existing_server_default: str | bool | Identity | Computed | None = False, existing_nullable: bool | None = None, existing_comment: str | None = None, schema: str | None = None, **kw: Any) → None

使用当前迁移上下文发出“alter column”指令。

通常，仅需要指定正在更改的列的方面，即名称、类型、可空性、默认值。还可以同时指定多个更改，后端应“执行正确操作”，单独或同时发出每个更改，具体取决于后端允许的情况。

MySQL 在这里有特殊要求，因为 MySQL 无法在没有完整规范的情况下 ALTER 列。在生成与 MySQL 兼容的迁移文件时，建议在不进行更改的情况下，提供 existing_type、existing_server_default 和 existing_nullable 参数。

与 SQLAlchemy “架构”类型 Boolean 和 Enum 相悖的类型更改也可能添加或删除在不支持它们的后台上伴随这些类型的约束。在这种情况下，existing_type 参数用于识别和移除绑定到类型对象的先前约束。

参数:

• table_name – 目标表的字符串名称。

• column_name – 目标列的字符串名称，即在操作开始前存在的名称。

• nullable – 可选；指定 True 或 False 以更改列的可空性。

• server_default – 可选；指定字符串 SQL 表达式、text() 或 DefaultClause 以指示对列的默认值进行更改。设置为 None 以移除默认值。

• comment – 要添加到列的新注释的可选字符串文本。

• new_column_name – 可选；在列重命名操作中指定字符串名称以表示新名称。

• type_ – 可选；TypeEngine 类型对象，用于指定对列类型的更改。对于同时表示约束的 SQLAlchemy 类型（即 Boolean、Enum），也会生成约束。

• autoincrement – 设置列的 AUTO_INCREMENT 标志；目前 MySQL 方言可以理解。

• existing_type – 可选；TypeEngine 类型对象，用于指定之前的类型。对于所有未另行指定新类型的 MySQL 列更改操作，以及在 SQL Server 列上更改可空性时，都需要此参数。如果类型是所谓的 SQLAlchemy “模式”类型，它可能会定义约束（即 Boolean、Enum），则也会使用此参数，以便可以删除约束。

• existing_server_default – 可选；列的现有默认值。如果未更改现有默认值，则在 MySQL 中需要此参数；否则，MySQL 会删除默认值。

• existing_nullable – 可选；列的现有可空性。如果现有可空性未发生更改，则 MySQL 中需要此项；否则，MySQL 会将其设置为 NULL。

• existing_autoincrement – 可选；列的现有自动增量。用于 MySQL 的用于更改指定 AUTO_INCREMENT 的列的系统。

• existing_comment – 要维护的列上现有注释的字符串文本。如果列上的现有注释未发生更改，则 MySQL 中需要此项。

• schema – 可选模式名称以在其中操作。若要控制默认行为之外的模式引用，请使用 SQLAlchemy 构造 quoted_name。

• postgresql_using – 字符串参数，它将指示在 ALTER COLUMN 中的特定于 Postgresql 的 USING 子句中呈现的 SQL 表达式。此字符串直接作为原始 SQL 接受，其中必须明确包含表达式中令牌的任何必要引用或转义。

bulk_insert(table: Table | TableClause, rows: List[Dict[str, Any]], *, multiinsert: bool = True) → None

使用当前迁移上下文发出“批量插入”操作。

这提供了一种表示多行 INSERT 的方法，该方法在执行实时连接以及生成 SQL 脚本的上下文中同样适用。对于 SQL 脚本，这些值将内联呈现到语句中。

例如：

from alembic import op
from datetime import date
from sqlalchemy.sql import table, column
from sqlalchemy import String, Integer, Date

# Create an ad-hoc table to use for the insert statement.
accounts_table = table(
    "account",
    column("id", Integer),
    column("name", String),
    column("create_date", Date),
)

op.bulk_insert(
    accounts_table,
    [
        {
            "id": 1,
            "name": "John Smith",
            "create_date": date(2010, 10, 5),
        },
        {
            "id": 2,
            "name": "Ed Williams",
            "create_date": date(2007, 5, 27),
        },
        {
            "id": 3,
            "name": "Wendy Jones",
            "create_date": date(2008, 8, 15),
        },
    ],
)

在使用 –sql 模式时，某些数据类型可能无法自动内联呈现，例如日期和其他特殊类型。当出现此问题时，可以使用 Operations.inline_literal()

op.bulk_insert(
    accounts_table,
    [
        {
            "id": 1,
            "name": "John Smith",
            "create_date": op.inline_literal("2010-10-05"),
        },
        {
            "id": 2,
            "name": "Ed Williams",
            "create_date": op.inline_literal("2007-05-27"),
        },
        {
            "id": 3,
            "name": "Wendy Jones",
            "create_date": op.inline_literal("2008-08-15"),
        },
    ],
    multiinsert=False,
)

在将 Operations.inline_literal() 与 Operations.bulk_insert() 结合使用时，为了使该语句在“在线”（例如非 –sql）模式下工作，应将 multiinsert 标志设置为 False，这将导致向数据库发出各个 INSERT 语句，每个语句都有一个不同的 VALUES 子句，以便仍然可以呈现“内联”值，而不是尝试将这些值作为绑定参数传递。

参数:

• table – 表示 INSERT 目标的表对象。

• rows – 表示行的字典列表。

• multiinsert – 当其默认值为 True 且未启用 –sql 模式时，INSERT 语句将使用“executemany()”样式执行，其中字典列表中的所有元素都作为单个列表中的绑定参数传递。将其设置为 False 会导致针对每个参数集发出单独的 INSERT 语句，并且在参数集中存在非字面值时需要这样做。

create_check_constraint(constraint_name: str | None, table_name: str, condition: str | ColumnElement[bool] | TextClause, *, schema: str | None = None, **kw: Any) → None

使用当前迁移上下文发出“create check constraint”指令。

例如：

from alembic import op
from sqlalchemy.sql import column, func

op.create_check_constraint(
    "ck_user_name_len",
    "user",
    func.len(column("name")) > 5,
)

CHECK 约束通常针对 SQL 表达式，因此通常需要临时表元数据。该函数会将给定的参数转换为 sqlalchemy.schema.CheckConstraint，该约束绑定到匿名表以发出 CREATE 语句。

参数:

• name – 检查约束的名称。该名称是必要的，以便可以发出 ALTER 语句。对于使用自动化命名方案的设置，例如 配置约束命名约定 中所述的设置，此处的 name 可以是 None，因为事件侦听器会在将约束对象与表关联时将名称应用于该对象。

• table_name – 源表的字符串名称。

• condition – 约束条件的 SQL 表达式。可以是字符串或 SQLAlchemy 表达式语言结构。

• deferrable – 可选布尔值。如果设置，在为该约束发布 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。

• initially – 可选字符串。如果设置，在为该约束发布 DDL 时发出 INITIALLY <value>。

• schema – 在其中操作的可选架构名称。若要控制架构在默认行为之外的引用，请使用 SQLAlchemy 构造 quoted_name。

create_exclude_constraint(constraint_name: str, table_name: str, *elements: Any, **kw: Any) → Table | None

发出一个 alter 以使用当前迁移上下文创建 EXCLUDE 约束。

注意

此方法是 Postgresql 特定的，此外至少需要 SQLAlchemy 1.0。

例如：

from alembic import op

op.create_exclude_constraint(
    "user_excl",
    "user",
    ("period", "&&"),
    ("group", "="),
    where=("group != 'some group'"),
)

请注意，这些表达式的工作方式与 ExcludeConstraint 对象本身的工作方式相同；如果传递纯字符串，则必须手动应用引用规则。

参数:

• name – 约束的名称。

• table_name – 源表的字符串名称。

• elements – 排除条件。

• where – 带有可选 WHERE 子句的 SQL 表达式或 SQL 字符串。

• deferrable – 可选布尔值。如果设置，在为该约束发布 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。

• initially – 可选字符串。如果设置，在为该约束发布 DDL 时发出 INITIALLY <value>。

• schema – 可选模式名称，用于在其中操作。

create_foreign_key(constraint_name: str | None, source_table: str, referent_table: str, local_cols: List[str], remote_cols: List[str], *, onupdate: str | None = None, ondelete: str | None = None, deferrable: bool | None = None, initially: str | None = None, match: str | None = None, source_schema: str | None = None, referent_schema: str | None = None, **dialect_kw: Any) → None

使用当前迁移上下文发出“创建外键”指令。

例如：

from alembic import op

op.create_foreign_key(
    "fk_user_address",
    "address",
    "user",
    ["user_id"],
    ["id"],
)

这在内部生成一个 Table 对象，其中包含必要的列，然后生成一个新的 ForeignKeyConstraint 对象，然后将其与 Table 相关联。与该操作关联的任何事件侦听器都将正常触发。 AddConstraint 构造最终用于生成 ALTER 语句。

参数:

• constraint_name – 外键约束的名称。该名称是必需的，以便可以发出 ALTER 语句。对于使用自动化命名方案的设置，例如在 配置约束命名约定 中所述，此处 name 可以是 None，因为事件侦听器会在将约束对象与表关联时将名称应用于该对象。

• source_table – 源表的字符串名称。

• referent_table – 目标表的字符串名称。

• local_cols – 源表中字符串列名称的列表。

• remote_cols – 远程表中字符串列名称的列表。

• onupdate – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON UPDATE <value>。典型值包括 CASCADE、DELETE 和 RESTRICT。

• ondelete – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON DELETE <value>。典型值包括 CASCADE、DELETE 和 RESTRICT。

• deferrable – 可选布尔值。如果设置，在为此约束发布 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。

• source_schema – 源表的可选架构名称。

• referent_schema – 目标表的可选架构名称。

create_index(index_name: str | None, table_name: str, columns: Sequence[str | TextClause | Function[Any]], *, schema: str | None = None, unique: bool = False, if_not_exists: bool | None = None, **kw: Any) → None

使用当前迁移上下文发布“创建索引”指令。

例如：

from alembic import op

op.create_index("ik_test", "t1", ["foo", "bar"])

可以使用 sqlalchemy.sql.expression.text() 构造生成函数索引

from alembic import op
from sqlalchemy import text

op.create_index("ik_test", "t1", [text("lower(foo)")])

参数:

• index_name – 索引的名称。

• table_name – 所有者表的名称。

• columns – 由字符串列名称和/或 text() 构造组成的列表。

• schema – 在其中进行操作的可选架构名称。若要控制默认行为之外的架构引用，请使用 SQLAlchemy 构造 quoted_name。

• unique – 如果为 True，则创建一个唯一索引。

• quote – 强制启用或禁用此列名称的引用，对应于 True 或 False。当保留其默认值 None 时，将根据名称是否区分大小写（至少包含一个大写字符的标识符被视为区分大小写）或是否是保留字来引用列标识符。此标志仅在需要强制引用 SQLAlchemy 方言未知的保留字时才需要。

• if_not_exists –

  如果为 True，则在创建新索引时添加 IF NOT EXISTS 运算符。

  在 1.12.0 版本中添加。

• **kw – 上述未提及的其他关键字参数是特定于方言的，并以 <dialectname>_<argname> 形式传递。有关已记录参数的详细信息，请参阅 方言 中有关各个方言的文档。

create_primary_key(constraint_name: str | None, table_name: str, columns: List[str], *, schema: str | None = None) → None

使用当前迁移上下文发出“创建主键”指令。

例如：

from alembic import op

op.create_primary_key("pk_my_table", "my_table", ["id", "version"])

这会在内部生成一个 Table 对象，其中包含必要的列，然后生成一个新的 PrimaryKeyConstraint 对象，然后将其与 Table 关联起来。与该操作关联的任何事件侦听器都将正常触发。AddConstraint 构造最终用于生成 ALTER 语句。

参数:

• constraint_name – 主键约束的名称。名称是必需的，以便可以发出 ALTER 语句。对于使用自动化命名方案的设置，例如 配置约束命名约定 中所述的，此处 name 可以是 None，因为事件侦听器会在将约束对象与表关联时将名称应用于该对象。

• table_name – 目标表的字符串名称。

• columns – 要应用于主键约束的字符串列名称列表。

• schema – 在其内部操作的可选架构名称。若要控制默认行为之外的架构引用，请使用 SQLAlchemy 构造 quoted_name。

create_table(table_name: str, *columns: SchemaItem, **kw: Any) → Table

使用当前迁移上下文发出“创建表”指令。

此指令接收与传统 sqlalchemy.schema.Table 构造类似的参数列表，但没有元数据

from sqlalchemy import INTEGER, VARCHAR, NVARCHAR, Column
from alembic import op

op.create_table(
    "account",
    Column("id", INTEGER, primary_key=True),
    Column("name", VARCHAR(50), nullable=False),
    Column("description", NVARCHAR(200)),
    Column("timestamp", TIMESTAMP, server_default=func.now()),
)

请注意，create_table() 接受 Column 从 SQLAlchemy 库直接构建。特别是，在数据库端创建的默认值使用 server_default 参数指定，而不是仅指定 Python 端默认值的 default

from alembic import op
from sqlalchemy import Column, TIMESTAMP, func

# specify "DEFAULT NOW" along with the "timestamp" column
op.create_table(
    "account",
    Column("id", INTEGER, primary_key=True),
    Column("timestamp", TIMESTAMP, server_default=func.now()),
)

该函数还返回一个新创建的 Table 对象，它对应于给定的表规范，适用于立即 SQL 操作，特别是 Operations.bulk_insert()

from sqlalchemy import INTEGER, VARCHAR, NVARCHAR, Column
from alembic import op

account_table = op.create_table(
    "account",
    Column("id", INTEGER, primary_key=True),
    Column("name", VARCHAR(50), nullable=False),
    Column("description", NVARCHAR(200)),
    Column("timestamp", TIMESTAMP, server_default=func.now()),
)

op.bulk_insert(
    account_table,
    [
        {"name": "A1", "description": "account 1"},
        {"name": "A2", "description": "account 2"},
    ],
)

参数:

• table_name – 表的名称

• *columns – 表中的 Column 对象的集合，以及可选的 Constraint 对象和 Index 对象。

• schema – 在其中操作的可选架构名称。若要控制默认行为之外的架构引用，请使用 SQLAlchemy 构造 quoted_name。

• **kw – 其他关键字参数传递给为该命令创建的基础 sqlalchemy.schema.Table 对象。

返回:

对应于给定参数的 Table 对象。

create_table_comment(table_name: str, comment: str | None, *, existing_comment: str | None = None, schema: str | None = None) → None

发出 COMMENT ON 操作以设置表的注释。

参数:

• table_name – 目标表的字符串名称。

• comment – 在指定表中注册的注释的字符串值。

• existing_comment – 已在指定表中注册的注释的字符串值，在自动生成中使用，以便该操作可逆，但直接使用时不需要。

另请参阅

Operations.drop_table_comment()

Operations.alter_column.comment

create_unique_constraint(constraint_name: str | None, table_name: str, columns: Sequence[str], *, schema: str | None = None, **kw: Any) → Any

使用当前迁移上下文发出“创建唯一约束”指令。

例如：

from alembic import op
op.create_unique_constraint("uq_user_name", "user", ["name"])

这在内部生成一个 Table 对象，其中包含必要的列，然后生成一个新的 UniqueConstraint 对象，然后将其与 Table 关联。与该操作关联的任何事件侦听器都将正常触发。AddConstraint 构造最终用于生成 ALTER 语句。

参数:

• name – 唯一约束的名称。名称是必需的，以便可以发出 ALTER 语句。对于使用自动化命名方案的设置，例如 配置约束命名约定 中所述，此处的 name 可以是 None，因为事件侦听器会在将约束对象与表关联时将名称应用于该对象。

• table_name – 源表的字符串名称。

• columns – 源表中字符串列名称的列表。

• deferrable – 可选布尔值。如果设置，则在为该约束发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。

• initially – 可选字符串。如果设置，则在为该约束发出 DDL 时发出 INITIALLY <value>。

• schema – 在其中操作的可选架构名称。要控制默认行为之外的架构引用，请使用 SQLAlchemy 构造 quoted_name。

drop_column(table_name: str, column_name: str, *, schema: str | None = None, **kw: Any) → None

使用当前迁移上下文发出“删除列”指令。

例如：

drop_column("organization", "account_id")

参数:

• table_name – 表名称

• column_name – 列名称

• schema – 要在其中操作的可选架构名称。若要控制默认行为之外的架构引用，请使用 SQLAlchemy 构造 quoted_name。

• mssql_drop_check – 可选布尔值。当 True 时，仅在 Microsoft SQL Server 上，首先使用与 SQL 脚本兼容的块（从 sys.check_constraints 中选择到 @variable）删除列上的 CHECK 约束，然后为该约束执行单独的 DROP CONSTRAINT。

• mssql_drop_default – 可选布尔值。当 True 时，仅在 Microsoft SQL Server 上，首先使用与 SQL 脚本兼容的块（从 sys.default_constraints 中选择到 @variable）删除列上的 DEFAULT 约束，然后为该默认值执行单独的 DROP CONSTRAINT。

• mssql_drop_foreign_key – 可选布尔值。当 True 时，仅在 Microsoft SQL Server 上，首先使用与 SQL 脚本兼容的块（从 sys.foreign_keys/sys.foreign_key_columns 中选择到 @variable）删除列上的单个 FOREIGN KEY 约束，然后为该默认值执行单独的 DROP CONSTRAINT。目前仅在列具有引用它的一个 FK 约束时有效。

drop_constraint(constraint_name: str, table_name: str, type_: str | None = None, *, schema: str | None = None) → None

通过 DROP CONSTRAINT 删除给定名称的约束。

参数:

• constraint_name – 约束名称。

• table_name – 表名称。

• type_ – 可选，MySQL 中必需。可以为“foreignkey”、“primary”、“unique”或“check”。

• schema – 在其中进行操作的可选架构名称。若要控制默认行为之外的架构引用，请使用 SQLAlchemy 构造 quoted_name。

drop_index(index_name: str, table_name: str | None = None, *, schema: str | None = None, if_exists: bool | None = None, **kw: Any) → None

使用当前迁移上下文发出“drop index”指令。

例如：

drop_index("accounts")

参数:

• index_name – 索引名称。

• table_name – 拥有表的名称。某些后端（例如 Microsoft SQL Server）需要此名称。

• schema – 在其中操作的可选架构名称。若要控制默认行为之外的架构引用，请使用 SQLAlchemy 构造 quoted_name。

• if_exists –

  如果为 True，则在删除索引时添加 IF EXISTS 运算符。

  在 1.12.0 版本中添加。

• **kw – 上面未提及的其他关键字参数是特定于方言的，并以 <dialectname>_<argname> 形式传递。请参阅 方言 中有关各个方言的文档，了解已记录参数的详细信息。

drop_table(table_name: str, *, schema: str | None = None, **kw: Any) → None

使用当前迁移上下文发出“drop table”指令。

例如：

drop_table("accounts")

参数:

• table_name – 表格名称

• schema – 要在其中操作的可选架构名称。要控制默认行为之外架构的引用，请使用 SQLAlchemy 构造 quoted_name。

• **kw – 其他关键字参数传递给为该命令创建的基础 sqlalchemy.schema.Table 对象。

drop_table_comment(table_name: str, *, existing_comment: str | None = None, schema: str | None = None) → None

发出“drop table comment”操作以删除在表上设置的现有注释。

参数:

• table_name – 目标表的字符串名称。

• existing_comment – 已在指定表上注册的注释的可选字符串值。

另请参阅

Operations.create_table_comment()

Operations.alter_column.comment

execute(sqltext: Executable | str, *, execution_options: dict[str, Any] | None = None) → None

使用当前迁移上下文执行给定的 SQL。

给定的 SQL 可以是纯字符串，例如：

op.execute("INSERT INTO table (foo) VALUES ('some value')")

或者它可以是任何类型的 Core SQL 表达式构造，如下所示，我们使用更新构造：

from sqlalchemy.sql import table, column
from sqlalchemy import String
from alembic import op

account = table("account", column("name", String))
op.execute(
    account.update()
    .where(account.c.name == op.inline_literal("account 1"))
    .values({"name": op.inline_literal("account 2")})
)

上面，我们利用了 SQLAlchemy sqlalchemy.sql.expression.table() 和 sqlalchemy.sql.expression.column() 构造，专门为我们的 UPDATE 语句创建了一个简短的临时表构造。当然，一个完整的 Table 构造也完全可以正常工作，但请注意，至少确保表定义包含在迁移脚本中，而不是从可能与旧迁移不兼容的模块中导入，这是一个推荐的做法。

在 SQL 脚本上下文中，语句直接发送到输出流。然而，没有返回结果，因为此函数面向于生成可以在“离线”模式下运行的更改脚本。此外，这里不鼓励使用参数化语句，因为它们在离线模式下不起作用。上面，我们在要使用参数的地方使用了 inline_literal()。

要与可以正常使用参数的已连接数据库进行完全交互，请使用上下文中提供的“绑定”

from alembic import op

connection = op.get_bind()

connection.execute(
    account.update()
    .where(account.c.name == "account 1")
    .values({"name": "account 2"})
)

此外，当以纯字符串传递语句时，它首先被强制转换为 sqlalchemy.sql.expression.text() 构造，然后再传递。在不太可能出现的情况中，如果字面 SQL 字符串包含冒号，则必须用反斜杠转义，如下所示

op.execute(r"INSERT INTO table (foo) VALUES ('\:colon_value')")

参数:

sqltext – 任何合法的 SQLAlchemy 表达式，包括

• 一个字符串

• 一个 sqlalchemy.sql.expression.text() 构造。

• 一个 sqlalchemy.sql.expression.insert() 构造。

• 一个 sqlalchemy.sql.expression.update() 构造。

• 一个 sqlalchemy.sql.expression.delete() 构造。

• SQLAlchemy Core 文档中描述的任何“可执行”内容，请注意不会返回结果集。

注意

在传递纯字符串时，该语句将被强制转换为 sqlalchemy.sql.expression.text() 构造。此构造考虑带有冒号的符号，例如 :foo 是绑定参数。为避免这种情况，请确保转义冒号符号，例如 \:foo。

参数:

execution_options – 可选的执行选项字典，将传递给 sqlalchemy.engine.Connection.execution_options()。

rename_table(old_table_name: str, new_table_name: str, *, schema: str | None = None) → None

发出 ALTER TABLE 以重命名表。

参数:

• old_table_name – 旧名称。

• new_table_name – 新名称。

• schema – 可选模式名称，用于在其中进行操作。若要控制默认行为之外模式的引用，请使用 SQLAlchemy 构造 quoted_name。

class alembic.operations.BatchOperations(migration_context: MigrationContext, impl: BatchOperationsImpl | None = None)

修改批处理模式的接口 Operations。

这基本上会从关联的方法中省略 table_name 和 schema 参数，因为在批处理模式下运行时，这些参数是已知的。

另请参阅

Operations.batch_alter_table()

请注意，从 0.8 开始，此类上的大多数方法都是使用 Operations.register_operation() 方法动态生成的。

构造一个新的 Operations

参数:

migration_context – MigrationContext 实例。

add_column(column: Column[Any], *, insert_before: str | None = None, insert_after: str | None = None) → None

使用当前批迁移上下文发布“添加列”指令。

另请参阅

Operations.add_column()

alter_column(column_name: str, *, nullable: bool | None = None, comment: str | Literal[False] | None = False, server_default: Any = False, new_column_name: str | None = None, type_: TypeEngine[Any] | Type[TypeEngine[Any]] | None = None, existing_type: TypeEngine[Any] | Type[TypeEngine[Any]] | None = None, existing_server_default: str | bool | Identity | Computed | None = False, existing_nullable: bool | None = None, existing_comment: str | None = None, insert_before: str | None = None, insert_after: str | None = None, **kw: Any) → None

使用当前批迁移上下文发布“更改列”指令。

参数与 Operations.alter_column() 的参数相同，以及以下选项

参数:

• insert_before – 创建新表时，此列应置于其前的现有列的字符串名称。

• insert_after – 创建新表时，此列应置于其后的现有列的字符串名称。如果同时省略 BatchOperations.alter_column.insert_before 和 BatchOperations.alter_column.insert_after，则该列将插入表中最后一个现有列之后。

另请参阅

Operations.alter_column()

create_check_constraint(constraint_name: str, condition: str | ColumnElement[bool] | TextClause, **kw: Any) → None

使用当前批处理迁移上下文发出“创建检查约束”指令。

此调用的批处理形式从调用中省略了 source 和 schema 参数。

另请参阅

Operations.create_check_constraint()

create_exclude_constraint(constraint_name: str, *elements: Any, **kw: Any) → Table | None

使用当前批处理迁移上下文发布“创建排除约束”指令。

注意

此方法是 Postgresql 特定的，此外至少需要 SQLAlchemy 1.0。

另请参阅

Operations.create_exclude_constraint()

create_foreign_key(constraint_name: str | None, referent_table: str, local_cols: List[str], remote_cols: List[str], *, referent_schema: str | None = None, onupdate: str | None = None, ondelete: str | None = None, deferrable: bool | None = None, initially: str | None = None, match: str | None = None, **dialect_kw: Any) → None

使用当前批处理迁移上下文发布“创建外键”指令。

此调用的批处理形式从调用中省略 source 和 source_schema 参数。

例如：

with batch_alter_table("address") as batch_op:
    batch_op.create_foreign_key(
        "fk_user_address",
        "user",
        ["user_id"],
        ["id"],
    )

另请参阅

Operations.create_foreign_key()

create_index(index_name: str, columns: List[str], **kw: Any) → None

使用当前批处理迁移上下文发布“创建索引”指令。

另请参阅

Operations.create_index()

create_primary_key(constraint_name: str | None, columns: List[str]) → None

使用当前批处理迁移上下文发布“创建主键”指令。

此调用的批处理形式从调用中省略 table_name 和 schema 参数。

另请参阅

Operations.create_primary_key()

create_table_comment(comment: str | None, *, existing_comment: str | None = None) → None

使用当前批迁移上下文发出 COMMENT ON 操作以设置表的注释。

参数:

• comment – 已针对指定表注册的注释的字符串值。

• existing_comment – 已在指定表上注册的注释的字符串值，在自动生成中使用，以便操作可逆，但直接使用时不需要。

create_unique_constraint(constraint_name: str, columns: Sequence[str], **kw: Any) → Any

使用当前批迁移上下文发出“创建唯一约束”指令。

此调用的批处理形式从调用中省略了 source 和 schema 参数。

另请参阅

Operations.create_unique_constraint()

drop_column(column_name: str, **kw: Any) → None

使用当前批迁移上下文发出“删除列”指令。

另请参阅

Operations.drop_column()

drop_constraint(constraint_name: str, type_: str | None = None) → None

使用当前批迁移上下文发出“删除约束”指令。

此调用的批处理形式从调用中省略 table_name 和 schema 参数。

另请参阅

Operations.drop_constraint()

drop_index(index_name: str, **kw: Any) → None

使用当前批迁移上下文发出“删除索引”指令。

另请参阅

Operations.drop_index()

drop_table_comment(*, existing_comment: str | None = None) → None

发出一个“drop table comment”操作来使用当前批操作上下文移除已在表上设置的现有注释。

参数:

existing_comment – 已在指定表上注册的注释的可选字符串值。

执行(sqltext: 可执行 | str, *, 执行选项: dict[str, 任意] | 无 = 无) → 无

使用当前迁移上下文执行给定的 SQL。

另请参阅

Operations.execute()