如何通过SQLAlchemy+Alembic自动生成SQL脚本格式的迁移文件？

Alembic默认生成Python格式的迁移文件，但确实可以通过自定义模板实现自动生成SQL脚本格式的迁移文件，同时保留revision --autogenerate的版本跟踪能力，以下是具体方案：

方案一：自定义纯SQL迁移模板 #

1. 创建SQL模板文件 #

在你的项目中新建模板目录，比如alembic/templates/sql_revisions，在该目录下创建script.sql.mako文件，内容如下：

-- Revision ID: ${rev_id}
-- Revises: ${down_revision | comma,n}
-- Create Date: ${create_date}

-- ${message}

-- ### auto-generated upgrade commands ###
${upgrades if upgrades else '-- No upgrade operations'}
-- ### end Alembic commands ###

-- ### auto-generated downgrade commands ###
${downgrades if downgrades else '-- No downgrade operations'}
-- ### end Alembic commands ###

这个模板会将Alembic自动生成的升级/降级操作渲染成SQL语句，同时保留版本跟踪所需的revision信息。

2. 配置Alembic使用自定义模板 #

修改alembic/env.py中的迁移配置，指定模板目录、SQL文件名规则和revision ID生成方式：

from alembic.script import ScriptDirectory
import uuid

def run_migrations_online():
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            # 启用自定义模板
            template_directory="alembic/templates/sql_revisions",
            # 生成.sql后缀的迁移文件
            script_filename=lambda rev_id: f"{rev_id}.sql",
            # 自动生成唯一revision ID
            rev_id_generator=lambda: uuid.uuid4().hex
        )

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

def run_migrations_offline():
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
        # 离线模式同样使用自定义模板
        template_directory="alembic/templates/sql_revisions",
        script_filename=lambda rev_id: f"{rev_id}.sql"
    )

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

3. 生成SQL迁移文件 #

现在直接执行常规的autogenerate命令即可生成SQL格式的迁移文件：

alembic revision --autogenerate -m "add users table with email column"

生成的.sql文件会被Alembic正常跟踪，后续执行alembic upgrade head时会自动执行这些SQL脚本。

方案二：使用自带的sqlalchemy_format模板（折中方案） #

如果你不想完全切换到纯SQL文件，Alembic自带的sqlalchemy_format模板可以生成包含原生SQL的Python迁移文件，既保留版本跟踪，又能直接编辑SQL内容：

alembic revision --autogenerate -m "create posts table" --template sqlalchemy_format

生成的文件示例：

from alembic import op
import sqlalchemy as sa
from sqlalchemy.sql import text

revision = 'a1b2c3d4e5f6'
down_revision = 'previous_rev_id'
branch_labels = None
depends_on = None

def upgrade():
    op.execute(text("""
        CREATE TABLE posts (
            id SERIAL PRIMARY KEY,
            title VARCHAR(255) NOT NULL,
            content TEXT,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )
    """))

def downgrade():
    op.execute(text("""
        DROP TABLE posts
    """))

这种方式不需要修改太多配置，上手更快，同时满足你对SQL脚本的编辑需求。

内容的提问来源于stack exchange，提问作者deepdive