[toc]

Alembic数据库迁移工具

Alembic 是一个轻量级的数据库迁移工具，专为 Python 项目设计，主要用于管理数据库模式的变更。

Alembic 是SQLAlchemy的官方迁移工具，相当于Django的migrations系统。

它由 SQLAlchemy 的作者开发，与 SQLAlchemy 深度集成，能够高效地处理数据库结构的演进。通过 Alembic，开发者可以轻松地记录、追踪和应用数据库的升级与降级操作。

什么是数据库迁移？

数据库迁移是指在应用程序运行过程中，对数据库结构进行变更的操作。这些变更可能包括添加、删除、修改数据库表、字段或索引等。

数据库迁移工具的作用：

• 跟踪数据库结构的所有变更
• 在团队间同步数据库架构
• 安全地升级和回滚数据库版本
• 自动化部署过程

总之，数据库迁移工具能够帮助开发者管理数据库结构的变更，确保数据库与应用程序的模型保持一致。

Alembic 核心功能

• 数据库迁移脚本生成：Alembic 可以根据数据库模型的变更自动生成迁移脚本，简化数据库结构的更新过程。
• 数据库版本控制：Alembic 可以记录数据库的变更历史，并支持对数据库进行版本控制，方便开发者回溯到之前的数据库状态。
• 数据库迁移应用：Alembic 可以将生成的迁移脚本应用到数据库中，实现数据库结构的变更。
• 它支持事务操作，在支持事务的数据库（如 PostgreSQL）中，迁移失败时会自动回滚。Alembic 还可以生成 SQL 脚本，供生产环境部署或 DBA 审核。

安装 Alembic 库

# 核心依赖
pip install fastapi sqlalchemy alembic

# 数据库驱动（根据需要选择）
pip install aiomysql PyMySQL          # MySQL
pip install asyncpg psycopg2-binary   # PostgreSQL  
pip install aiosqlite                 # SQLite

初始化 Alembic

在当前python项目的根目录运行以下命令。

# 初始化Alembic目录

# 语法格式
alembic init <alembic目录>

# 在当前目录中创建一个 migrations 目录，用于存放 Alembic 相关文件
alembic init migrations

文件目录结构如下所示

├── migrations              # 迁移目录
│   ├── env.py              # 环境配置
│   ├── README           # 迁移目录说明
│   ├── script.py.mako   # 迁移模板
│   └── versions         # 具体的迁移版本文件
└── alembic.ini  # Alembic配置文件

开始使用

修改alembic.ini

在 alembic.ini 文件中配置数据库连接信息

# 数据库连接格式
sqlalchemy.url = driver://user:pass@localhost/dbname

# 例如mysql的连接信息
sqlalchemy.url = mysql+pymysql://root:123456@localhost/my_db

修改migrations/env.py 环境配置文件

在该文件中主要修改以下内容：

• 导入我们的数据库模型基类和所有模型
• 设置target_metadata为我们的数据库模型基类的metadata属性

# 导入数据库引擎
from config.database_config import myEngine

# 导入模型基类
from module_exam.model.base_model import myBaseModel

# 导入所有需要迁移的模型（确保所有模型都被导入，否则Alembic无法检测到）
from module_exam.model import (
    mp_exam_model,
    mp_option_model,
    mp_question_model,
    mp_user_model,
)

# 设置目标元数据为我们的数据库模型基类的metadata属性
target_metadata = myBaseModel.metadata

# 修改run_migrations_offline函数中的url
# 将默认的url=None改为使用我们的数据库URL
url = config.get_main_option("sqlalchemy.url")

创建初始迁移

运行以下命令，会在 migrations/versions 目录下创建一个初始迁移文件。

# 自动检测模型变更并生成迁移文件
alembic revision --autogenerate -m "Initial migration"

务必检查迁移文件：

• SQL语句是否正确
• 是否遗漏了字段或索引
• 数据迁移逻辑是否安全

配置远程Mysql数据库连接

1. 修改项目中的数据库配置文件，将数据库连接URL更改为远程的Mysql数据库连接URL。、

# 远程MySQL数据库的连接URL
MYSQL_DATABASE_URL = "mysql+pymysql://username:password@remote_host:3306/database_name"

2. 也需要更新alembic.ini文件中的连接URL为远程MySQL数据库连接URL。

# 远程MySQL数据库的连接URL
sqlalchemy.url = mysql+pymysql://username:password@remote_host:3306/database_name

开始执行数据库迁移

确保远程MySQL服务已启动，并且数据库存在，然后执行以下命令进行迁移

运行以下命令，会将数据库迁移脚本应用到远程MySQL数据库中。即在远程数据库中去执行迁移脚本。

# 升级到最新版本
alembic upgrade head

这会把迁移脚本中定义的数据库变更操作应用到远程MySQL数据库中。

常用Alembic命令

• alembic revision --autogenerate -m "迁移描述"：创建新的迁移脚本，会根据模型变更自动生成。
• alembic history：显示数据库迁移历史记录。
• alembic upgrade head：将数据库迁移到最新版本。
• alembic upgrade <版本号>：将数据库迁移到特定版本。
• alembic downgrade base：将数据库迁移到初始状态。
• alembic downgrade -1：将数据库迁移到上一个版本。
• alembic show <版本号>：显示指定版本的迁移脚本内容。
• alembic history：显示数据库迁移历史记录。

注意事项

1. 确保所有模型都在alembic/env.py中被导入，否则Alembic无法检测到这些模型。
2. 在执行迁移前，确保远程MySQL数据库已经创建
3. 迁移过程中可能会遇到权限问题，请确保数据库用户具有足够的权限
4. 建议在迁移前备份数据库，以防意外发生。
5. 谨慎使用数据库迁移工具，避免对生产环境数据库进行随意操作。
6. 建议在开发环境中先测试数据库迁移脚本，确保其在生产环境中能够正常运行。