从Django Migrations切换至FastAPI Alembic：数据库拆分最佳实践

一、数据库拆分最佳实践 #

1. 全量备份原数据库 #

先对原Django数据库做完整备份，避免数据丢失：

# PostgreSQL示例
pg_dump -U your_username original_django_db > original_db_backup.sql

# MySQL示例
mysqldump -u your_username -p original_django_db > original_db_backup.sql

2. 导出目标表的结构与数据 #

单独导出User应用的两张表，减少冗余：

# PostgreSQL示例，导出指定表
pg_dump -U your_username -t app_user_table1 -t app_user_table2 original_django_db > user_tables_dump.sql

# MySQL示例，导出指定表
mysqldump -u your_username -p original_django_db app_user_table1 app_user_table2 > user_tables_dump.sql

3. 初始化新数据库并导入数据 #

• 创建空的目标数据库：

# PostgreSQL示例
createdb -U your_username new_user_service_db

# MySQL示例
mysql -u your_username -p -e "CREATE DATABASE new_user_service_db;"

• 将导出的表导入新数据库：

# PostgreSQL示例
psql -U your_username new_user_service_db < user_tables_dump.sql

# MySQL示例
mysql -u your_username -p new_user_service_db < user_tables_dump.sql

导入完成后，手动验证表结构、数据量、索引约束是否与原表完全一致。

4. 切换FastAPI项目的数据库连接 #

修改FastAPI项目的数据库配置（比如settings.py），将连接字符串指向新数据库，启动服务后测试所有User相关API的读写功能，确保无依赖原Django数据库的其他表（若有跨表依赖需提前通过接口调用重构）。

5. 逐步切换业务流量 #

不要一次性全量切换，先通过配置开关、负载均衡等方式让小部分请求走新数据库，持续监控稳定性、数据一致性。确认无问题后，再逐步扩大流量占比，最终完成全量切换。

6. 清理原Django项目 #

• 删除User应用的模型、迁移文件及相关代码
• 更新原Django项目的数据库配置，确保其不再操作已拆分的User表
• 若原Django项目仍需访问用户数据，修改为调用FastAPI的接口，而非直接操作数据库

二、从Django迁移切换至Alembic #

1. 初始化Alembic #

在FastAPI项目根目录执行：

alembic init alembic

执行后会生成alembic目录和alembic.ini配置文件。

2. 配置Alembic连接与模型元数据 #

• 修改alembic.ini中的sqlalchemy.url为新数据库的连接字符串，或更推荐在alembic/env.py中复用FastAPI项目的数据库配置：

# 在alembic/env.py中替换target_metadata
from your_fastapi_app.models import Base  # 导入FastAPI模型的Base类
target_metadata = Base.metadata

3. 生成基线迁移（适配已有表结构） #

因为新数据库已经存在User表，直接自动生成迁移会重复创建表，需生成基线迁移记录当前状态：

alembic revision --autogenerate -m "Initial baseline: match existing Django User tables"

打开生成的迁移文件，检查upgrade函数，若包含create_table操作，需手动修改为无实际执行的代码（比如只留注释），确保Alembic识别当前数据库状态为最新版本。

4. 验证迁移状态 #

执行以下命令确认Alembic与数据库状态同步：

alembic current  # 查看当前数据库的迁移版本
alembic heads    # 查看可用的最新迁移版本

两者版本应一致。

5. 测试新迁移流程 #

修改FastAPI的User模型（比如新增一个last_login_ip字段），执行：

alembic revision --autogenerate -m "Add last_login_ip field to User table"
alembic upgrade head

登录数据库验证字段是否正确添加，确认Alembic能正常管理后续的 schema 变更。

6. 彻底停用Django迁移 #

确保原Django项目不再对已拆分的User表执行任何迁移操作，删除相关迁移文件及模型代码，避免误操作导致数据不一致。

关键注意事项 #

• 数据一致性：切换期间若原Django项目仍在写User表，需在低峰期操作，或通过事务、消息队列保证数据同步，避免丢失。
• 模型兼容性：FastAPI的模型字段类型、约束、索引必须与原Django模型完全一致，否则导入数据或API调用会出错。
• 回滚预案：提前准备回滚步骤，若切换失败，可快速将流量切回原数据库，恢复业务。

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