使用 SQLAlchemy 和 Alembic 处理 FastAPI 中的模型变更
使用 SQLAlchemy 和 Alembic 处理 FastAPI 中的模型变更，是一种成熟且可靠的数据库版本管理方案。以下是具体实现方法及两者的优势：
一、使用 SQLAlchemy + Alembic 实现 FastAPI 模型变更的步骤
- 环境准备
安装依赖：
bash
pip install fastapi sqlalchemy alembic pymysql # 以 MySQL 为例，其他数据库需替换对应驱动 - 初始化 SQLAlchemy 模型
在 FastAPI 项目中定义数据模型（以 User 表为例）：
python
运行
app/models.py
from sqlalchemy import Column, Integer, String, DateTime
from sqlalchemy.ext.declarative import declarative_base
from datetime import datetime
Base = declarative_base()
class User(Base):
tablename = “users”
id = Column(Integer, primary_key=True, index=True)
username = Column(String(50), unique=True, index=True)
email = Column(String(100), unique=True) # 初始字段
# 后续可在此处添加/修改字段
- 初始化 Alembic
在项目根目录执行以下命令，生成 Alembic 配置文件：
bash
alembic init alembic
修改 alembic.ini 配置数据库连接（以 MySQL 为例）：
ini
sqlalchemy.url = mysql+pymysql://用户名:密码@localhost:3306/数据库名
修改 alembic/env.py，指定 SQLAlchemy 模型的 Base：
python
运行
alembic/env.py
from logging.config import fileConfig
from sqlalchemy import engine_from_config, pool
from alembic import context
from app.models import Base # 导入模型的 Base
目标元数据（指向模型的 Base.metadata）
target_metadata = Base.metadata
… 保持其他默认配置不变
- 生成迁移脚本（处理模型变更）
当模型发生变更（如新增字段、修改字段类型等）时，执行以下命令生成迁移脚本：
bash
alembic revision --autogenerate -m “描述变更内容，如：add age field to user”
示例：若在 User 模型中新增 age 字段：
python
运行
修改后的 User 模型
class User(Base):
# … 原有字段
age = Column(Integer, nullable=True) # 新增字段
执行上述命令后，Alembic 会在 alembic/versions 目录下生成一个包含变更逻辑的 Python 脚本。
5. 执行迁移（应用到数据库）
生成脚本后，通过以下命令将变更应用到数据库：
bash
alembic upgrade head # “head” 表示应用所有未执行的迁移
如需回滚最近一次迁移，可执行：
bash
alembic downgrade -1
二、SQLAlchemy 和 Alembic 的优势
- SQLAlchemy 的优势
ORM 抽象：通过 Python 类定义模型，无需直接编写 SQL，降低数据库操作的复杂度，尤其适合 FastAPI 等 Python 后端框架。
跨数据库兼容：支持 MySQL、PostgreSQL、SQLite 等多种数据库，切换数据库时无需大幅修改代码。
灵活的查询能力：提供丰富的查询 API，支持复杂的联合查询、过滤、排序等操作，同时保留原生 SQL 接口。
事务支持：内置事务管理，确保数据库操作的原子性，避免数据不一致。
与 FastAPI 适配：可结合 Pydantic 模型实现数据验证，无缝集成到 FastAPI 的接口开发中。 - Alembic 的优势
版本化管理：将数据库变更记录为一系列迁移脚本，便于追踪每一次 schema 变更（如谁改了什么、何时改的）。
自动化迁移：通过 --autogenerate 自动生成迁移脚本，减少手动编写 SQL 的工作量（但需检查脚本正确性）。
环境隔离：开发、测试、生产环境可通过同一套迁移脚本同步数据库结构，避免环境差异导致的问题。
可回滚：支持灵活的版本回滚，当新变更引入问题时，可快速恢复到之前的稳定版本。
团队协作友好：迁移脚本可纳入 Git 等版本控制工具，多人协作时能清晰同步数据库变更。
总结
模型变更流程：修改 SQLAlchemy 模型 → 用 Alembic 生成迁移脚本 → 执行迁移应用到数据库。
核心价值：SQLAlchemy 简化了数据库操作，Alembic 解决了 schema 版本管理问题，两者结合为 FastAPI 项目提供了可靠、可追溯的数据库开发流程，尤其适合团队协作和生产环境。