從升級到回溯，輕鬆掌握資料庫 Schema 進化的力量，在軟體開發的世界裡，我們很習慣使用 Git 來管理程式碼版本，但你有沒有想過， 資料庫的結構（Schema）也需要版本管理嗎？
例如你在某次開發中新增了一個欄位 phone 到 user 資料表，過兩天產品經理又說要改欄位名稱，之後可能又要移除，如果我們手動改 SQL，難以追蹤，更難還原， 此時，Alembic 就派上用場了。
🚀 Alembic 是什麼？
Alembic 是一套專門用來管理資料庫結構版本的工具，通常搭配 SQLAlchemy 使用。搭配 Alembic，你可以：
✔ 安全地更新資料庫結構（upgrade）
✔ 必要時回復到以前版本（downgrade）
✔ 清楚紀錄每次資料庫變化
✔ 多人協作時保持資料庫一致性
你可以把 Alembic 想像成： 👉 「資料庫世界的 Git」。
🎯 Alembic 就像 Git - 資料庫版控概念
🚀 Migration 檔案就像一個「前進」「後退」的盒子
Upgrade & Downgrade 升版與退版
alembic upgrade head → 跳到最新版本
alembic downgrade -1 → 回退一個版本
alembic downgrade base → 回到最初狀態
🛠️ Alembic 實際操作流程圖
🧠 資料庫版本像「樓層」，Alembic 是電梯
🗂 Alembic 目錄結構簡圖
/project
│
├─ alembic/
│ ├─ versions/ ← migration 檔案放這裡
│ │ ├─ 20231110_add_phone.py
│ │ └─ 20231112_add_orders_table.py
│ └─ env.py
│
├─ app/
│ └─ models.py ← SQLAlchemy Models
│
├─ alembic.ini ← Alembic 設定檔
└─ main.py
🛠 實作範例：用 Alembic 新增與回復欄位
① 建立基本專案結構
alembic_demo/
│
├─ models.py
└─ main.py
② 建立 SQLAlchemy Model（models.py）
from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import declarative_base
Base = declarative_base()
class User(Base):
__tablename__ = 'user'
id = Column(Integer, primary_key=True)
name = Column(String)
③ 啟動 SQLite 測試資料庫（main.py）
from sqlalchemy import create_engine
from models import Base
engine = create_engine("sqlite:///example.db", echo=True)
Base.metadata.create_all(engine)
執行：
python main.py
會產生一個 SQLite 資料庫檔 example.db，內含 user 表。
④ 安裝 Alembic 並初始化
pip install alembic
alembic init alembic
執行後會出現：
alembic/ ← Alembic 工作目錄
alembic.ini ← 設定檔
⑤ 設定資料庫連線（修改 alembic.ini）
找到這段，把它改成 SQLite 路徑：
sqlalchemy.url = sqlite:///example.db
⑥ 自動產生第一次 Migration（建立 user 表）
alembic revision --autogenerate -m "create user table"
執行後會在 alembic/versions/ 裡產生一支 migration 檔案。
接著執行 upgrade：
alembic upgrade head
資料庫就會建立 user 表。
⑦ 修改 models.py（新增 phone 欄位）
在 User 類別加上這一行：
phone = Column(String)
完整程式：
class User(Base):
__tablename__ = 'user'
id = Column(Integer, primary_key=True)
name = Column(String)
phone = Column(String) # 新增欄位
⑧ 產生 migration 來新增欄位
alembic revision --autogenerate -m "add phone column to user"
Alembic 會解析模型，產生這樣的 migration 檔：
def upgrade():
op.add_column('user', sa.Column('phone', sa.String()))
def downgrade():
op.drop_column('user', 'phone')
執行：
alembic upgrade head
此時，資料庫裡的 user 表就有 phone 欄位了。
⑨ 如果不需要這個欄位了？執行 downgrade！
alembic downgrade -1
這會自動移除 phone 欄位，資料庫回到前一個版本。
是不是就像 Git 的 git checkout 或 git revert？
🎯 結語：Alembic 讓資料庫不再「不可逆」
資料庫一直是軟體系統裡最難變更的部分之一，但透過 Alembic，我們不只可以「改」，還可以「追蹤、還原、協作、部署」， 它實現了資料庫也能被版本控制！
如果你的專案使用 Python、FastAPI、Flask、SQLAlchemy、或任何關於資料庫的服務，Alembic 絕對是你應該認識的工具。
