SuperAPI AI 工具集

alembic-migrations

部署与运维

查看项目

更新于 10-16 02:33

技能介绍

用途:为使用 SQLAlchemy 2.0 异步(asyncpg)的 Python 应用提供 Alembic 数据库迁移实践,用于建表改列、自动生成迁移、实现零停机模式变更、回滚及迁移历史管理、在大表上添加索引。

主要能力:初始化异步模板(alembic init -t async migrations);在 env.py 中配置异步引擎;自动生成迁移(alembic revision --autogenerate -m "...")、应用与回滚(alembic upgrade head、alembic downgrade -1)、查看版本与历史(alembic current、alembic history --verbose);生成 SQL 供审查(alembic upgrade head --sql > migration.sql);大表使用 CREATE INDEX CONCURRENTLY 避免锁表;NOT NULL 列采用两阶段(先可空、回填、再改约束);列重命名用四阶段 expand/contract。

使用方式:按文档模板配置 env.py 与迁移脚本,运行上述命令;生产环境建议先生成 SQL 审查后再应用,不在生产自动执行迁移。CONCURRENTLY 不能在事务块内运行,需相应关闭 transaction_per_migration。Alembic 的 upgrade/downgrade 不能是 async 函数,可用 sqlalchemy.util.await_only 在 greenlet 上下文中执行异步操作;与 FastAPI lifespan 冲突时推荐在应用启动前运行迁移。

适用场景:异步 PostgreSQL 应用的 schema 版本管理、大表索引、数据回填与列格式转换。

限制:文档未提供具体收费、平台与效果数据;自动生成可能遗漏自定义约束,必须人工审查;禁止在部署后修改已有迁移,属反模式。