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 脚本。

执行迁移（应用到数据库）

生成脚本后，通过以下命令将变更应用到数据库：

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 项目提供了可靠、可追溯的数据库开发流程，尤其适合团队协作和生产环境。