下面是一份结构清晰、步骤明确的 基于 Alembic + Pydantic + SQLAlchemy 的数据库迁移系统初始化教程，非常适合初次搭建项目或团队规范流程参考。
🚀 Alembic + SQLAlchemy + Pydantic 项目数据库迁移初始化教程
本教程将指导你如何从零初始化 Alembic 迁移系统，并结合 .env 配置、安全地管理数据库连接。
✅ 一、前置依赖
确保安装了必要库：
pip install alembic sqlalchemy psycopg2-binary pydantic python-dotenv
✅ 二、初始化 Alembic
在项目根目录执行：
alembic init alembic
这将创建：
alembic.ini（配置文件）alembic/目录（含 env.py 和 migrations）
✅ 三、配置数据库连接
1️⃣ 创建 .env 文件（根目录）
DB_HOST=aws-0-ap-southeast-1.pooler.supabase.com
DB_PORT=6543
DB_USER=postgres.gvxpxxvhwswnbxbsdqsb
DB_PASSWORD=password
DB_NAME=postgres
2️⃣ 创建 app/config.py：配置加载模块
# app/config.py
from pydantic import BaseSettings, validator
from typing import Optionalclass Settings(BaseSettings):DB_HOST: strDB_PORT: strDB_USER: strDB_PASSWORD: strDB_NAME: strDATABASE_URL: Optional[str] = None@validator("DATABASE_URL", pre=True)def assemble_db_url(cls, v, values):return (f"postgresql+psycopg2://{values['DB_USER']}:{values['DB_PASSWORD']}@"f"{values['DB_HOST']}:{values['DB_PORT']}/{values['DB_NAME']}")class Config:env_file = ".env"settings = Settings()
✅ 四、修改 Alembic 的 env.py
1️⃣ 设置模型元数据
假设你有 Base 定义在 app/models/base.py：
# env.py
import os
import syssys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
from app.models.base import Base
target_metadata = Base.metadata
2️⃣ 加载 DATABASE_URL 到 Alembic：
# env.py
import app.config as ems_configconfig.set_main_option('sqlalchemy.url', ems_config.settings.DATABASE_URL)
✅ 五、生成迁移脚本
初始化版本文件（可跳过）
alembic revision -m "initial empty revision"
根据模型自动生成迁移文件
alembic revision --autogenerate -m "create user table with created_at field"
自动识别模型和数据库之间的差异，生成 SQL 语句。
✅ 六、执行数据库迁移命令
alembic upgrade head # 升级到最新版本
常用命令：
| 命令 | 说明 |
|---|---|
alembic upgrade head | 升级数据库到最新版本 |
alembic downgrade base | 降级到最初版本 |
alembic upgrade <revision> | 升级到指定版本 |
alembic downgrade <revision> | 降级到指定版本 |
alembic upgrade +2 | 升级两个版本 |
alembic downgrade -1 | 降级一个版本 |
✅ 七、生成离线 SQL 文件（可用于审计或运维部署）
alembic upgrade head --sql > upgrade.sql
alembic downgrade base --sql > downgrade.sql
这些 SQL 文件不会执行，只是输出脚本。
✅ 八、总结目录结构参考
project-root/
│
├── alembic.ini
├── .env
├── alembic/
│ ├── env.py
│ └── versions/
├── app/
│ ├── config.py
│ ├── models/
│ │ └── base.py
│ └── ...
✅ 九、附：.env 配置回顾
DB_HOST=aws-0-ap-southeast-1.pooler.supabase.com
DB_PORT=6543
DB_USER=postgres.gvxpxxvhwswnbxbsdqsb
DB_PASSWORD=xiaodianchi
DB_NAME=postgres
📌 最佳实践建议
- 每次模型变动后运行
alembic revision --autogenerate并确认生成的 SQL。 - 使用
alembic upgrade head --sql > script.sql审核后执行，特别是在生产环境。 - 版本号建议使用 Git commit SHA、时间戳等方式标识。
