一句话#

create_all() 只会“缺表就建表”，不会可靠地帮你“改已有表结构”。

生活类比#

create_all() 像新房装修队：

1
没有房子 -> 帮你盖
2
已经有房子 -> 基本不动

Alembic 像装修施工记录：

1
第1次：建 users 表
2
第2次：给 users 加 email 字段
3
第3次：给 documents 加 source 索引
4
每一步都能查、能执行、能回滚

你的项目现在的情况#

models.py 里现在有：

1
Base.metadata.create_all(bind=engine)

学习早期它很好用，因为你只想快速看到表被建出来。

但真实项目会遇到：

1
已经有 users 表了，现在想加 email 字段
2
已经有 documents 表了，现在想改字段长度
3
已经有 document_chunks 表了，现在想加索引

这时候只靠 create_all() 不够。你需要 Alembic 记录每次结构变化。

边界#

Alembic 负责：

• 建表；
• 加字段；
• 删字段；
• 改字段；
• 建索引；
• 回滚结构；
• 记录数据库当前版本。

Alembic 不负责：

• 写业务 CRUD；
• 替你设计表结构；
• 自动保证每次 autogenerate 都完美；
• 管理 ChromaDB 向量库结构。

✅ 检查点#

• create_all() 为什么适合学习早期，但不适合长期项目？
• Alembic 管的是“数据内容”还是“数据库结构”？

一句话#

模型文件是“理想结构”，数据库是“现实结构”，迁移文件是“从现实走到理想的步骤”。

三层关系#

1
models.py
2
  ↓ 描述理想表结构
3
Base.metadata
4
  ↓ Alembic 对比用
5
迁移文件 versions/*.py
6
  ↓ 真正执行 SQL
7
SQLite 数据库 my_database.db

Git 类比#

你可以把每个迁移文件理解成：

1
数据库结构的一次 commit

✅ 检查点#

• models.py 和真实数据库可能不一致吗？
• poetry run alembic upgrade head 的 head 是什么意思？

一句话#

先让 Alembic 生成自己的配置目录，再把它接到你的 SQLAlchemy 模型上。

安装检查#

你的项目使用 Poetry，所以不要直接执行 alembic 或 pip install alembic。 Alembic 装在 Poetry 的虚拟环境里，外部终端默认找不到它。

如果 pyproject.toml 里还没有 Alembic，先装：

1
poetry add alembic

如果已经安装，只需要确认 Poetry 环境里能找到它：

1
poetry run alembic --version

也可以先进 Poetry shell：

1
poetry shell
2
alembic --version

本教程后面统一使用推荐写法：poetry run alembic ...。

初始化#

在项目根目录执行：

1
poetry run alembic init alembic

它会生成：

1
alembic.ini
2
alembic/
3
  env.py
4
  script.py.mako
5
  versions/

每个文件干什么#

✅ 检查点#

• poetry run alembic init alembic 是每次迁移都要跑吗？
• 迁移文件最终放在哪个目录？

一句话#

Alembic 要能看到 models.Base.metadata，才知道你的理想表结构是什么。

当前项目结构#

你的 database.py：

1
import os
2

3
from dotenv import load_dotenv
4
from sqlalchemy import create_engine
5
from sqlalchemy.orm import sessionmaker
6

7
load_dotenv()
8

9
DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./my_database.db")
10
connect_args = {"check_same_thread": False} if DATABASE_URL.startswith("sqlite") else {}
11
engine = create_engine(DATABASE_URL, connect_args=connect_args)
12
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

你的 models.py：

1
Base = declarative_base()

Alembic 需要拿到：

1
Base.metadata

修改 alembic/env.py#

找到：

1
target_metadata = None

改成：

1
from database import DATABASE_URL
2
from models import Base
3

4
target_metadata = Base.metadata

然后把配置里的 URL 改成项目的 URL：

1
config.set_main_option("sqlalchemy.url", DATABASE_URL)

最小 env.py 关键片段#

1
from alembic import context
2
from sqlalchemy import engine_from_config, pool
3

4
from database import DATABASE_URL
5
from models import Base
6

7
config = context.config
8
config.set_main_option("sqlalchemy.url", DATABASE_URL)
9
target_metadata = Base.metadata

⚠️ 重要坑：models.py 里的 create_all#

迁移阶段最好不要让导入 models.py 时自动建表。

你现在的：

1
Base.metadata.create_all(bind=engine)

适合学习早期，但引入 Alembic 后建议挪到临时初始化脚本，或者删除，让迁移文件负责建表。

推荐过渡做法：

1
先保留，理解 Alembic 流程；
2
真正切换迁移管理时，再移除 create_all。

不要一边让 create_all() 偷偷建表，一边又让 Alembic 管结构，否则你会分不清表到底是谁建的。

✅ 检查点#

• target_metadata = Base.metadata 是为了让 Alembic 看见什么？
  • target_metadata = Base.metadata 是为了让 Alembic 看见你代码里声明的“目标数据库表结构”。
• 为什么引入 Alembic 后，不建议长期保留 create_all()？
  • 引入 Alembic 后，不建议长期保留 create_all()，是因为你不应该让两个工具同时偷偷管理数据库结构。

一句话#

先让 Alembic 比对模型和数据库，再生成一份“迁移草稿”。

命令#

1
poetry run alembic revision --autogenerate -m "init tables"

会生成类似：

1
alembic/versions/20260616_xxxxx_init_tables.py

里面有两个函数：

1
def upgrade():
2
    ...
3

4
def downgrade():
5
    ...

upgrade() 和 downgrade()#

1
def upgrade():
2
    # 往前走：建表、加字段、加索引
3

4
def downgrade():
5
    # 往后退：删字段、删表、撤销索引

一定要检查迁移文件#

--autogenerate 不是最终答案，它只是草稿。

检查三件事：

1. 有没有漏表；
2. 有没有误删表；
3. downgrade() 是否能回滚。

SQLite 特别注意#

SQLite 对改字段类型、删字段、改约束支持比较弱。Alembic 有时会用批处理模式，或者需要你手动调整迁移。

学习阶段先练：

1
新增字段
2
新增表
3
新增索引

✅ 检查点#

• --autogenerate 生成的是最终真理还是草稿？
• 为什么执行 upgrade 前必须打开迁移文件看一眼？

一句话#

生成迁移文件只是写好了施工方案，upgrade 才是真正施工。

升级到最新#

1
poetry run alembic upgrade head

含义：

1
把数据库结构升级到最新迁移版本

回滚一步#

1
poetry run alembic downgrade -1

含义：

1
撤销最近一次迁移

查看当前版本#

1
poetry run alembic current

查看历史#

1
poetry run alembic history

数据库里会多一张表#

Alembic 会自动创建：

1
alembic_version

它记录：

1
当前数据库已经升级到哪个 revision

✅ 检查点#

• poetry run alembic revision 和 poetry run alembic upgrade 有什么区别？
• alembic_version 表是干什么的？

一句话#

练迁移最好的方式：只改一个字段，完整走一遍模型 → 迁移 → 升级 → 回滚。

第一步：改模型#

在 models.py 的 User 里新增：

1
email = Column(String(100), unique=True, index=True, nullable=True)

第二步：生成迁移#

1
poetry run alembic revision --autogenerate -m "add user email"

第三步：打开迁移文件检查#

你应该看到类似：

1
def upgrade():
2
    op.add_column("users", sa.Column("email", sa.String(length=100), nullable=True))
3
    op.create_index(op.f("ix_users_email"), "users", ["email"], unique=True)
4

5
def downgrade():
6
    op.drop_index(op.f("ix_users_email"), table_name="users")
7
    op.drop_column("users", "email")

第四步：执行升级#

1
poetry run alembic upgrade head

第五步：确认字段存在#

SQLite 可以这样看：

1
sqlite3 my_database.db ".schema users"

第六步：练习回滚#

1
poetry run alembic downgrade -1

再查看：

1
sqlite3 my_database.db ".schema users"

确认 email 字段消失。

✅ 检查点#

• 为什么新增字段最好先设 nullable=True？
• upgrade() 和 downgrade() 是否应该互相反向？