AcidMap/migrations

数据库迁移指南

本项目使用 Alembic 进行数据库版本控制和迁移管理。

使用 db_migrate.py 脚本

本项目提供了 db_migrate.py 辅助脚本，简化了数据库迁移操作。推荐使用此脚本而不是直接使用 alembic 命令。

创建新迁移

自动生成迁移脚本（根据模型变更）：

python db_migrate.py create "描述迁移内容"

手动创建空白迁移脚本：

python db_migrate.py create "描述迁移内容" --manual

执行迁移

升级到最新版本：

python db_migrate.py upgrade

升级指定版本：

python db_migrate.py upgrade <版本号>

降级迁移

降级到上一版本：

python db_migrate.py downgrade

降级到指定版本：

python db_migrate.py downgrade <版本号>

标记数据库版本

将数据库标记为指定版本（不执行实际迁移）：

python db_migrate.py stamp head

这在从SQL备份恢复数据库后特别有用，可以避免重复执行迁移。

查看迁移信息

查看当前版本：

python db_migrate.py current

查看迁移历史：

python db_migrate.py history

执行SQL语句

直接执行SQL语句：

python db_migrate.py sql "SQL语句"

原始 Alembic 命令参考

以下是直接使用 Alembic 的命令，仅供参考。建议优先使用上述 db_migrate.py 脚本。

创建新迁移

自动生成迁移脚本（根据模型变更）：

alembic revision --autogenerate -m "描述迁移内容"

手动创建空白迁移脚本：

alembic revision -m "描述迁移内容"

执行迁移

升级到最新版本：

alembic upgrade head

升级指定版本：

alembic upgrade <版本号>

升级指定步数：

alembic upgrade +<步数>

降级迁移

降级到上一版本：

alembic downgrade -1

降级到指定版本：

alembic downgrade <版本号>

降级指定步数：

alembic downgrade -<步数>

查看迁移信息

查看当前版本：

alembic current

查看迁移历史：

alembic history

查看特定迁移的SQL：

alembic upgrade <版本号>:head --sql

迁移工作流

1. 修改 SQLAlchemy 模型
2. 生成迁移脚本 python db_migrate.py create "描述变更"
3. 检查生成的脚本是否正确
4. 应用迁移 python db_migrate.py upgrade
5. 提交迁移脚本到版本控制系统