命令

命令#

注意

本节讨论了Alembic 的内部 API，涉及它的命令调用系统。本节仅对希望扩展 Alembic 功能的开发人员有用。有关使用 Alembic 命令的文档，请参阅 教程。

Alembic 命令在 Commands 包中均由函数表示。它们都接受相同的用法样式，将 Config 对象作为第一个参数发送。

命令可以通过编程方式运行，首先构造一个 Config 对象，如下所示

from alembic.config import Config
from alembic import command
alembic_cfg = Config("/path/to/yourapp/alembic.ini")
command.upgrade(alembic_cfg, "head")

在很多情况下，而且可能在大多数情况下，应用程序希望调用一系列 Alembic 命令和/或其他功能。如果可行，通常建议将多个命令链接到单个连接和事务。这可以通过使用 Config.attributes 字典来实现，以便共享连接

with engine.begin() as connection:
    alembic_cfg.attributes['connection'] = connection
    command.upgrade(alembic_cfg, "head")

此食谱要求 env.py 使用此连接参数；有关详细信息，请参阅 在一条或多条编程迁移命令中共享连接 中的示例。

要编写直接使用数据库和脚本目录信息的小型 API 函数，而不是仅仅运行其中一个内置命令，请直接使用 ScriptDirectory 和 MigrationContext 类。

alembic.command.branches(config: Config, verbose: bool = False) → None#

显示当前分支点。

参数:

  • config – Config 实例。

  • verbose – 以详细模式输出。

alembic.command.check(config: Config) → None#

检查带有自动生成的修订命令是否具有待升级操作。

参数:

config – 一个 Config 对象。

在 1.9.0 版本中添加。

alembic.command.current(config: Config, verbose: bool = False) → None#

显示数据库的当前修订版本。

参数:

  • config – Config 实例。

  • verbose – 以详细模式输出。

alembic.command.downgrade(config: Config, revision: str, sql: bool = False, tag: str | None = None) → None#

还原到以前版本。

参数:

  • config – Config 实例。

  • revision – 字符串修订目标或 –sql 模式的范围。可以是 "base" 以将第一个修订目标作为目标。

  • sql – 如果为 True，则使用 --sql 模式。

  • tag – 任意“标签”，可以通过自定义 env.py 脚本通过 EnvironmentContext.get_tag_argument() 方法拦截。

alembic.command.edit(config: Config, rev: str) → None#

使用 $EDITOR 编辑修订脚本。

参数:

  • config – Config 实例。

  • rev – 目标修订。

alembic.command.ensure_version(config: Config, sql: bool = False) → None#

如果 alembic 版本表不存在，则创建该表。

参数:

  • config – Config 实例。

  • sql –

    使用 --sql 模式。

    在版本 1.7.6 中添加。

alembic.command.heads(config: Config, verbose: bool = False, resolve_dependencies: bool = False) → None#

显示脚本目录中当前可用的头。

参数:

  • config – Config 实例。

  • verbose – 以详细模式输出。

  • resolve_dependencies – 将依赖项版本视为下修订版。

alembic.command.history(config: Config, rev_range: str | None = None, verbose: bool = False, indicate_current: bool = False) → None#

按时间顺序列出变更集脚本。

参数:

  • config – 一个 Config 实例。

  • rev_range – 字符串修订范围。

  • verbose – 以详细模式输出。

  • indicate_current – 指示当前修订。

alembic.command.init(config: Config, directory: str, template: str = 'generic', package: bool = False) → None#

初始化一个新的脚本目录。

参数:

  • config – 一个 Config 对象。

  • directory – 目标目录的字符串路径。

  • template – 要使用的迁移环境模板的字符串名称。

  • package – 为 True 时，将 __init__.py 文件写入环境位置以及版本/位置。

alembic.command.list_templates(config: Config) → None#

列出可用模板。

参数:

config – Config 对象。

alembic.command.merge(config: Config, revisions: _RevIdType, message: str | None = None, branch_label: _RevIdType | None = None, rev_id: str | None = None) → Script | None#

合并两个修订。创建新的迁移文件。

参数:

  • config – Config 实例

  • revisions – 要合并的修订。

  • message – 应用于修订的字符串消息。

  • branch_label – 应用于新修订的字符串标签名称。

  • rev_id – 硬编码修订标识符，而不是生成一个新的。

另请参见

使用分支

alembic.command.revision(config: Config, message: str | None = None, autogenerate: bool = False, sql: bool = False, head: str = 'head', splice: bool = False, branch_label: _RevIdType | None = None, version_path: str | None = None, rev_id: str | None = None, depends_on: str | None = None, process_revision_directives: ProcessRevisionDirectiveFn | None = None) → Script | None | List[Script | None]#

创建新的修订文件。

参数:

  • config – 一个 Config 对象。

  • message – 应用于修订的字符串消息；这是 -m 选项，用于 alembic revision。

  • autogenerate – 是否从数据库自动生成脚本；这是 --autogenerate 选项，用于 alembic revision。

  • sql – 是否将脚本转储为 SQL 字符串；指定后，脚本将转储到 stdout。这是 --sql 选项，用于 alembic revision。

  • head – 作为父项构建新修订的头修订；这是 --head 选项，用于 alembic revision。

  • splice – 新修订是否应成为其自身的新头；当给定的 head 本身不是头时，这是必需的。这是 --splice 选项，用于 alembic revision。

  • branch_label – 应用于分支的字符串标签；这是 --branch-label 选项，用于 alembic revision。

  • version_path – 标识配置中特定版本路径的字符串符号；这是 --version-path 选项，用于 alembic revision。

  • rev_id – 可选的修订标识符，用于代替生成一个标识符；这是 --rev-id 选项，用于 alembic revision。

  • depends_on – 可选的“依赖于”标识符列表；这是 --depends-on 选项，用于 alembic revision。

  • process_revision_directives – 这是一个可调用的函数，它采用与 EnvironmentContext.configure.process_revision_directives 中描述的可调用的函数相同形式；将应用于由修订过程生成的结构，在其中可以通过编程方式对其进行更改。请注意，与所有其他参数不同，此选项仅可通过以编程方式使用 command.revision() 获得。

alembic.command.show(config: Config, rev: str) → None#

显示由给定符号表示的修订。

参数:

  • config – 一个 Config 实例。

  • rev – 字符串修订目标。可能是 "current" 以显示当前在数据库中应用的修订。

alembic.command.stamp(config: Config, revision: _RevIdType, sql: bool = False, tag: str | None = None, purge: bool = False) → None#

使用给定的版本“标记”版本表；不运行任何迁移。

参数:

  • config – 一个 Config 实例。

  • revision –

    目标版本或版本列表。可以是列表，以指示标记多个分支头；可以是 "base" 以从表中删除所有版本，也可以是 "heads" 以标记最新版本。

    注意

    此参数在命令行界面中称为“revisions”。

  • sql – 使用 --sql 模式

  • tag – 一个任意“标记”，可以通过自定义 env.py 脚本通过 EnvironmentContext.get_tag_argument 方法进行拦截。

  • purge – 在标记之前删除版本表中的所有条目。

alembic.command.upgrade(config: Config, revision: str, sql: bool = False, tag: str | None = None) → None#

升级到较新版本。

参数:

  • config – Config 实例。

  • revision – 字符串修订目标或 –sql 模式的范围。可能是 "heads" 以定位最新修订。

  • sql – 如果为 True，则使用 --sql 模式。

  • tag – 任意“标签”，可以通过自定义 env.py 脚本通过 EnvironmentContext.get_tag_argument() 方法进行拦截。

目录