Alembic 是啥 ?
Alembic 是一個專為 SQLAlchemy 設計的資料庫遷移（migrations）工具。它主要用來：
管理資料庫 schema 的版本變更（如新增欄位、建立表格、刪除欄位等）
追蹤每次變更的歷史
提供升級與降級資料庫 schema 的功能
簡單來說，Alembic 就像是 Git 對應資料庫 schema 的版本控制工具。
為什麼要用 Alembic？
當你開發一個使用資料庫的應用程式時，資料庫結構（schema）會隨著需求演進：
一開始只需要一個 users 表格；
過一陣子你可能需要 posts 表格；
然後你發現 users 表格需要一個 last_login 欄位…
手動改變資料庫 schema 不僅麻煩，也容易出錯。而 Alembic 幫你：
自動產生變更腳本（migration script）
安全地在不同環境中執行 schema 升級或降級
與 SQLAlchemy 整合良好，搭配 ORM 使用非常方便
步驟總覽
- 安裝 Alembic
- 初始化 Alembic
- 設定連線資料庫 URL
- 連接你的 SQLAlchemy Base
- 新增欄位到 Model
- 自動生成 migration 檔
- 套用 migration 到資料庫
Step 1
1
alembic init alembic
安裝完後，會新增一些檔案及資料夾
讓 alembic 可以找到你的資料庫，因此設定資料庫 URL
打開 alembic.ini，找到這一行：
sqlalchemy.url = postgresql://user:password@localhost/dbname
修改 alembic/env.py，接入你的 SQLAlchemy Base 打開 alembic/env.py，找到這段：
1
2
from myapp import mymodel # ❌ 這是範例，要改掉
target_metadata = mymodel.Base.metadata
那就修改 env.py：
1
2
3
4
5
6
7
8
9
import sys
import os
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
from app.models import Base # ✅ 修改這裡
from models import user_models ### 一定要，這樣 model 在修改的時候，alembic才可以看到。
target_metadata = Base.metadata
1
alembic revision --autogenerate -m "first commit"
會產生一個 migration 檔案
套用 migration 到資料庫
1
alembic upgrade head
常用指令
| 指令 | 說明 |
|---|---|
| alembic init alembic | 初始化 Alembic 設定 |
| alembic revision -m “新增 user 表格” | 建立一個新的 migration script |
| alembic revision –autogenerate -m “自動偵測變更” | 根據 SQLAlchemy model 自動產生變更 |
| alembic upgrade head | 將資料庫升級到最新版本 |
| alembic downgrade -1 | 回退上一個版本 |
| alembic current | 顯示目前資料庫的 migration 版本 |
注意事項
新增或修改欄位時，主要三個步驟：
- 給 db 的 model 必須要改
- 與前端的 pydantic 要改
- 使用 alembic 將 schemas 的修改記錄下來，並修改 table
地雷別踩
如果你在 Alembic 管理的 schema 之前先手動建立資料庫，接著又刪掉 .db 或用 create_all() 建了新的空資料庫，那就會導致 Alembic 控制的 schema 是全新建立的。
最好的做法就是一開始就用上 Alembic 吧!