當你執行 alembic upgrade head，卻發現資料庫沒有任何資料表、甚至連 alembic_version 都不見時，恭喜你進入了 Alembic 的地雷區。

😵 我遇到的情況：

  • 已跑 alembic revision --autogenerate -m "init"
  • upgrade 完全無錯誤訊息
  • 資料表沒出現、DB 是空的

🔍 排查方向

  1. 確認你跑的是正確的 DB？

    • alembic.ini 裡的 sqlalchemy.url 是正確的嗎？
    • 有時你以為是本地 PostgreSQL，但實際上是連到空的 docker volume！

  2. env.py 裡 Base 有帶進去嗎？

from app.db.models import Base  # ← 你要確認這行有執行

target_metadata = Base.metadata

  1. __init__.py 有 import 所有模型嗎？

    Alembic autogenerate 會依靠 metadata 裡有無模型。若沒 import，metadata 是空的，自然不會產生 migration。

✅ 最後的修復方式（我的解法）

  • 檢查 DB URL 是否正確
  • 檢查 env.py 有帶入正確的 Base.metadata
  • 確保所有模型都被 import（哪怕只是靜靜地出現在某個檔案中）

🧘‍♀️ 結語

這次踩坑之後我才真正了解 Alembic 是怎麼組合 metadata 的。
它不像 Prisma 有 GUI 或 schema file，Alembic 是全靠你手動定義與 import 的「程式碼掃描」。

建立信任、寫對程式，是 migration 的基礎。