Alembic迁移系统初始化实战教程

下面是一份结构清晰、步骤明确的 基于 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 Optional


class Settings(BaseSettings):
    DB_HOST: str
    DB_PORT: str
    DB_USER: str
    DB_PASSWORD: str
    DB_NAME: str

    DATABASE_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 sys

sys.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_config

config.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	升级到指定版本
alembic downgrade	降级到指定版本
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、时间戳等方式标识。

---