本文 AI 產出，尚未審核

FastAPI 課程 – 資料庫整合（Database Integration）

主題：Alembic Migration

簡介

在開發 FastAPI 應用程式時，資料庫的結構往往會隨著需求變動而調整。若每次手動修改資料表，不僅容易遺漏，也會在多人協作或部署到不同環境時產生衝突。這時 Alembic（SQLAlchemy 官方的 migration 工具）就能派上用場。它能夠以版本化的方式管理資料庫變更，讓開發、測試、正式環境的結構保持一致，並提供 回溯（downgrade）、分支（branch） 等進階功能。

本文將從概念說明、安裝設定、實作範例，到常見陷阱與最佳實踐，完整帶領讀者在 FastAPI 專案中導入 Alembic，打造可維護、可擴充的資料庫遷移流程。

核心概念

1. Migration 與版本控制

  • Migration：指的是對資料庫結構（Schema）的變更，例如新增欄位、修改索引、建立新表等。
  • 版本控制：Alembic 為每一次 migration 產生一個唯一的 revision ID，並以腳本檔案形式保存於 alembic/versions 目錄。這與 Git 管理程式碼的方式相似，讓你能夠 升級（upgrade）、降級（downgrade），甚至在不同分支上同時開發不同的資料結構。

2. 為何結合 SQLAlchemy 與 Alembic

FastAPI 常與 SQLAlchemy 搭配使用，兩者的關係如下：

項目 SQLAlchemy Alembic
目的 ORM / DB 連線與操作 資料庫結構變更管理
產出 Python model 類別 Migration script（Python）
依賴 直接操作 DB 依賴 SQLAlchemy 的 MetaData 產生差異

重點：只要你的模型（Model）是以 Base = declarative_base() 建立的，Alembic 就能自動偵測變更，產生相對應的 migration 檔案。

3. Alembic 的基本指令

指令 說明
alembic init <dir> 初始化 Alembic 設定與目錄（通常為 alembic）
alembic revision -m "說明" 手動產生空的 migration，適合自行編寫腳本
alembic revision --autogenerate -m "說明" 自動比對模型與資料庫，生成 migration
alembic upgrade head 套用所有尚未執行的 migration，將 DB 更新至最新
alembic downgrade -1 回退最近一次 migration
alembic history 查看 migration 歷史

程式碼範例

以下範例以 FastAPI + SQLAlchemy + Alembic 為前提，示範從專案建立到實際遷移的完整流程。

1️⃣ 建立 FastAPI 專案與依賴

# 建立虛擬環境
python -m venv .venv
source .venv/bin/activate   # Windows 使用 .venv\Scripts\activate

# 安裝核心套件
pip install fastapi uvicorn sqlalchemy alembic pydantic

提示：若使用 PostgreSQL，請額外安裝 psycopg2-binary。

2️⃣ 定義 SQLAlchemy Base 與模型

# app/db.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

SQLALCHEMY_DATABASE_URL = "sqlite:///./test.db"   # 這裡以 SQLite 為例

engine = create_engine(
    SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False}
)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()

# app/models.py
from sqlalchemy import Column, Integer, String, Boolean
from .db import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    username = Column(String(50), unique=True, index=True, nullable=False)
    email = Column(String(120), unique=True, index=True, nullable=False)
    is_active = Column(Boolean, default=True)

說明：Base 會在 Alembic 的 env.py 中被引用，作為自動產生 migration 的依據。

3️⃣ 初始化 Alembic

alembic init alembic

此指令會產生以下結構：

your_project/
├─ alembic/
│  ├─ env.py
│  ├─ script.py.mako
│  └─ versions/
├─ alembic.ini
├─ app/
│  ├─ db.py
│  └─ models.py
└─ main.py

4️⃣ 設定 alembic.ini 與 env.py

alembic.ini（只需要修改 DB 連線字串）：

# alembic.ini
sqlalchemy.url = sqlite:///./test.db

env.py（讓 Alembic 能夠讀取我們的 Base）：

# alembic/env.py
from logging.config import fileConfig
from sqlalchemy import engine_from_config, pool
from alembic import context

# 這裡載入專案的設定
import sys
import os
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))

from app.db import Base   # <-- 重要！導入 Base
from app import models    # 確保 models 被 import，讓 Base 包含所有 Table

# 這段程式碼會自動讀取 alembic.ini
config = context.config
fileConfig(config.config_file_name)

target_metadata = Base.metadata   # <-- 告訴 Alembic 使用哪個 metadata

def run_migrations_offline():
    """離線模式（產生 SQL 檔）"""
    url = config.get_main_option("sqlalchemy.url")
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )
    with context.begin_transaction():
        context.run_migrations()

def run_migrations_online():
    """線上模式（直接對 DB 執行）"""
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )
    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
        )
        with context.begin_transaction():
            context.run_migrations()

if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

重點：target_metadata = Base.metadata 必須正確指向你的模型，否則 --autogenerate 無法偵測變更。

5️⃣ 產生第一個 Migration（自動偵測）

alembic revision --autogenerate -m "create users table"

執行後會在 alembic/versions/ 產生類似 20231120_1234_create_users_table.py 的檔案，內容大致如下：

# alembic/versions/20231120_1234_create_users_table.py
"""create users table

Revision ID: 20231120_1234
Revises: 
Create Date: 2023-11-20 12:34:56.789012

"""
from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision = "20231120_1234"
down_revision = None
branch_labels = None
depends_on = None


def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table(
        "users",
        sa.Column("id", sa.Integer(), nullable=False),
        sa.Column("username", sa.String(length=50), nullable=False),
        sa.Column("email", sa.String(length=120), nullable=False),
        sa.Column("is_active", sa.Boolean(), nullable=True),
        sa.PrimaryKeyConstraint("id"),
    )
    op.create_index(op.f("ix_users_email"), "users", ["email"], unique=True)
    op.create_index(op.f("ix_users_username"), "users", ["username"], unique=True)
    # ### end Alembic commands ###


def downgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_index(op.f("ix_users_username"), table_name="users")
    op.drop_index(op.f("ix_users_email"), table_name="users")
    op.drop_table("users")
    # ### end Alembic commands ###

說明：upgrade() 用於升級（建立表格），downgrade() 用於回退（刪除表格）。在實務上，你可以自行加入資料遷移（data migration）程式碼，例如搬移舊資料至新欄位。

6️⃣ 套用 Migration

alembic upgrade head

此指令會依序執行 upgrade()，在 SQLite 中會產生 test.db 並建立 users 表。

7️⃣ 新增欄位與自動產生 Migration

假設我們要在 User 模型加入 full_name 欄位：

# app/models.py（修改後）
class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    username = Column(String(50), unique=True, index=True, nullable=False)
    email = Column(String(120), unique=True, index=True, nullable=False)
    is_active = Column(Boolean, default=True)
    full_name = Column(String(100), nullable=True)   # 新增欄位

重新執行自動產生：

alembic revision --autogenerate -m "add full_name to users"

產生的 migration 會類似：

def upgrade() -> None:
    op.add_column("users", sa.Column("full_name", sa.String(length=100), nullable=True))

def downgrade() -> None:
    op.drop_column("users", "full_name")

再次套用：

alembic upgrade head

常見陷阱與最佳實踐

陷阱 說明 最佳做法
未正確載入模型 env.py 沒有 import 所有 model，導致 --autogenerate 找不到變更。 在 env.py 中 from app import models，或使用 import importlib; importlib.import_module("app.models") 確保載入。
使用 SQLite 測試環境 SQLite 不支援某些 DDL（如 ALTER TYPE），在開發時會產生不一致。 在本機測試時改用 PostgreSQL/MySQL，或在 migration 中加入條件判斷 if context.get_bind().dialect.name == "sqlite": ...
直接改寫已發布的 migration 已在 production 執行的 migration 不能隨意修改，會造成版本衝突。 永遠 以新增 migration 的方式解決問題，若必須修正已執行的 migration，使用 alembic downgrade 回退至該版後重新升級。
忘記同步 alembic_version 表 手動變更 DB 結構但未更新 Alembic 版本，導致 upgrade head 失敗。 執行 alembic stamp head 讓 Alembic 知道當前 DB 已是最新狀態（僅在特殊遷移時使用）。
大量資料遷移寫在 upgrade() 大批資料搬移會拖慢部署，甚至因為錯誤導致 migration 中斷。 把大量資料搬移拆分成 獨立腳本（如使用 alembic op.execute() 搭配批次 commit），或使用 background job 完成。

其他實務建議

  1. 版本命名：在 revision -m 中使用清晰的描述，例如 add_user_profile_table，有助於日後追蹤。
  2. CI/CD 整合：在部署 pipeline 中加入 alembic upgrade head，確保每次部署前 DB 結構已同步。
  3. 測試 Migration：利用測試資料庫執行 alembic upgrade → 執行測試 → alembic downgrade -1，確保升降級皆可順利完成。
  4. 備份：在正式環境執行 upgrade 前，務必備份資料庫；若出現意外，可快速回復。

實際應用場景

場景 1：多租戶 SaaS 平台的動態欄位

在 SaaS 服務中，客戶可能自行決定要新增自訂欄位。開發者可以在 每次客戶需求變更 時，產生一個新的 migration（alembic revision --autogenerate），然後在背景工作者中自動執行 upgrade. 這樣既保證了 資料庫一致性，又不需要手動編寫 DDL。

場景 2：微服務間共享資料模型

假設有兩個微服務 user-service 與 order-service 共用 users 表。當 user-service 需要在 users 表加入 last_login 欄位時，只要在 user-service 中產生 migration，所有使用相同資料庫的服務 都會在部署時自動套用最新結構，避免因欄位缺失導致的 RuntimeError。

場景 3：資料庫升級與回滾的灰度發布

在大型電商平台，部署新功能往往需要 先升級資料庫 再釋出程式碼。利用 Alembic，你可以先在 測試環境 完成 alembic upgrade head，確認所有查詢仍然正確；若發現問題，立即使用 alembic downgrade -1 回滾，並在 CI 中自動驗證。

總結

  • Alembic 為 FastAPI + SQLAlchemy 專案提供了 版本化、可回溯 的資料庫遷移方案，讓開發者能以 程式化、自動化 的方式管理結構變更。
  • 只要在 env.py 正確設定 target_metadata，配合 --autogenerate，大部分的 DDL 都能自動生成，減少手寫錯誤。
  • 在實務上，避免直接修改已執行的 migration、確保模型被正確載入、以及 在 CI/CD 中加入 migration 步驟，是保證系統穩定性的關鍵。
  • 透過上述範例與最佳實踐，你現在已具備在 FastAPI 專案中使用 Alembic 進行資料庫整合的完整能力，無論是小型 MVP 還是大型企業級系統，都能以安全、可維護的方式推進開發。

祝開發順利，資料庫永遠保持 同步、可控、可回溯！ 🚀