Prompts-MCP 686 skills · ai / design / design-pattern / framework / fundamentals / habit / lang / tech-selection
/mcp/sse
lang lang/sql/ddl/alembic-migration-template.md medium

sql-alembic-migration-template

Alembic 迁移文件标准模板（含 upgrade/downgrade 对称）。Use when 写 Python 后端代码 / 评审涉及 `alembic-migration-template` 的 PR。

alembicmigrationupgradedowngrade迁移文件移文件标文件标准
paths
  • **/migrations/**/*.py
  • backend/alembic/versions/**/*.py

SQL · Alembic 迁移模板

工具栈

本文以 Tortoise ORM 的官方迁移工具 Aerich 为例（兼容 Tortoise 语义）。Alembic 项目可参照同样的对称结构。

命名约定

migrations/models/
├── 0_init_articles.py
├── 1_init_themes.py
├── 2_init_documents.py
├── 3_init_files.py
├── 4_init_tasks.py
├── 5_init_request_logs.py
├── 6_init_tenants.py
├── 7_init_orders.py
└── 8_init_events.py

序号 + init_<语义>.py 或 <seq>_alter_<table>_<field>.py。

迁移文件骨架

# migrations/models/8_init_events.py
from tortoise import BaseDBAsyncClient

async def upgrade(db: BaseDBAsyncClient) -> str:
    return """
        CREATE TABLE IF NOT EXISTS `events` (
            `id` CHAR(36) NOT NULL PRIMARY KEY,
            `actor_tenant_id` CHAR(36) NOT NULL,
            `target_tenant_id` CHAR(36) NOT NULL UNIQUE,
            `invite_code` VARCHAR(16) NOT NULL,
            `created_at` DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
            INDEX `idx_actor` (`actor_tenant_id`),
            INDEX `idx_code` (`invite_code`)
        ) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

        ALTER TABLE `tenants`
            ADD COLUMN `invite_code` VARCHAR(16) NULL,
            ADD COLUMN `invited_by_code` VARCHAR(16) NULL,
            ADD COLUMN `bonus_credits` INT NOT NULL DEFAULT 0,
            ADD COLUMN `bonus_credits_lifetime` INT NOT NULL DEFAULT 0;
    """

async def downgrade(db: BaseDBAsyncClient) -> str:
    return """
        DROP TABLE IF EXISTS `events`;
        ALTER TABLE `tenants`
            DROP COLUMN `invite_code`,
            DROP COLUMN `invited_by_code`,
            DROP COLUMN `bonus_credits`,
            DROP COLUMN `bonus_credits_lifetime`;
    """

规范

规则 说明
upgrade / downgrade 对称 每条 upgrade 必有可回滚的 downgrade
字段添加加 default 避免 NOT NULL 加字段卡在已有数据
索引命名 idx_<col> uk_<col> 唯一索引
字符集 utf8mb4 必须
主键 CHAR(36) UUID 或 BIGINT AUTO 按业务选择，建议 UUID

操作命令

# 初始化
aerich init -t main.TORTOISE_ORM

# 生成迁移文件（基于 model 变化自动 diff）
aerich migrate --name "init_events"

# 执行迁移
aerich upgrade

# 回滚一步
aerich downgrade -v 1

自检

  • [ ] upgrade / downgrade 对称？
  • [ ] 新增 NOT NULL 字段有 DEFAULT 或两步迁移（先 NULL 再回填再改 NOT NULL）？
  • [ ] 索引命名规范 idx_* / uk_*？
  • [ ] 大表 DDL 在低峰期跑（pt-online-schema-change 或维护窗口）？

相关