D1 Migrations:用版本控制管理資料表結構 | Cloudflare 完整教學

-- D1 自動建立與維護的追蹤表(你不需要手動建,了解結構即可)
CREATE TABLE d1_migrations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT UNIQUE,                              -- 遷移檔名,例如 0001_initial_schema.sql
  applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP -- 套用時間
);

{
  "name": "my-app",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "d1_databases": [
    {
      "binding": "DB",                                        // 程式中用 env.DB 存取
      "database_name": "my-app-db",                           // 建立後不可更改
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "migrations_dir": "migrations",                         // 遷移檔所在目錄(預設值)
      "migrations_table": "d1_migrations"                     // 追蹤表名稱(預設值,通常不用改)
    }
  ]
}

# 語法:wrangler d1 migrations create <資料庫名稱> <描述>
wrangler d1 migrations create my-app-db initial_schema

# 輸出範例:
# ✅ Successfully created Migration '0001_initial_schema.sql'!
#
# 此檔案位於:migrations/0001_initial_schema.sql
# 請在裡面寫入你的 SQL,然後用 apply 套用。

-- migrations/0001_initial_schema.sql
-- 建立基本使用者表與 session 表,含常用索引

CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  role TEXT NOT NULL DEFAULT 'user',
  active INTEGER NOT NULL DEFAULT 1,                 -- SQLite 沒有原生 boolean,用 0/1
  created_at TEXT NOT NULL DEFAULT (datetime('now')) -- 日期用 TEXT(ISO 8601)
);

-- 常查詢的欄位建索引
CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
CREATE INDEX IF NOT EXISTS idx_users_role ON users(role);

CREATE TABLE IF NOT EXISTS sessions (
  id TEXT PRIMARY KEY,                                -- UUID
  user_id INTEGER NOT NULL,
  expires_at TEXT NOT NULL,
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON sessions(user_id);

# 套用所有尚未套用的遷移到本地模擬庫
wrangler d1 migrations apply my-app-db --local

# 輸出範例:
# Migrations to be applied:
# ┌─────────────────────────────┐
# │ Name                        │
# ├─────────────────────────────┤
# │ 0001_initial_schema.sql     │
# └─────────────────────────────┘
# ✅ 0001_initial_schema.sql 已成功套用

# wrangler dev 預設連本地模擬庫,安全
wrangler dev

# 或直接下命令確認表存在
wrangler d1 execute my-app-db --local --command="SELECT name FROM sqlite_master WHERE type='table'"
# 應該看到 users、sessions,以及 D1 自動建的 d1_migrations

# 查本地狀態
wrangler d1 migrations list my-app-db --local

# 查遠端狀態
wrangler d1 migrations list my-app-db --remote

# 遠端輸出範例(還沒套用任何遷移到遠端時):
# ┌─────────────────────────────┬──────────────────┐
# │ Name                        │ Applied At       │
# ├─────────────────────────────┼──────────────────┤
# │ 0001_initial_schema.sql     │ ⏳ Not yet applied │
# └─────────────────────────────┴──────────────────┘

# 套用到 Cloudflare 上的正式資料庫
wrangler d1 migrations apply my-app-db --remote

# 套用後再 list 一次確認
wrangler d1 migrations list my-app-db --remote
# 這次 0001 應該顯示已套用的時間戳記,而非 "Not yet applied"

wrangler d1 migrations create my-app-db add_posts_table
# 建立 migrations/0002_add_posts_table.sql

-- migrations/0002_add_posts_table.sql
-- 新增文章表,並幫 users 補上 last_login 欄位

CREATE TABLE IF NOT EXISTS posts (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  author_id INTEGER NOT NULL,
  title TEXT NOT NULL,
  slug TEXT UNIQUE NOT NULL,
  content TEXT,
  published INTEGER NOT NULL DEFAULT 0,
  published_at TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE SET NULL
);

CREATE INDEX IF NOT EXISTS idx_posts_author_id ON posts(author_id);
CREATE INDEX IF NOT EXISTS idx_posts_published ON posts(published, published_at DESC);

-- 對既有 users 表新增欄位(schema 演進)
ALTER TABLE users ADD COLUMN last_login TEXT;

wrangler d1 migrations apply my-app-db --local
wrangler d1 migrations apply my-app-db --remote

-- migrations/0003_seed_roles.sql
-- 建立角色表並塞入預設角色(這類固定資料適合放進遷移)

CREATE TABLE IF NOT EXISTS roles (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT UNIQUE NOT NULL,
  permissions TEXT NOT NULL DEFAULT '[]'   -- 用 JSON 字串存權限陣列
);

INSERT INTO roles (name, permissions) VALUES
  ('admin',  '["read","write","delete","manage_users"]'),
  ('editor', '["read","write"]'),
  ('viewer', '["read"]');

-- seed-dev.sql:僅供本地開發的測試假資料(不放進 migrations/)
INSERT INTO users (email, name, role) VALUES
  ('alice@example.com', 'Alice', 'admin'),
  ('bob@example.com',   'Bob',   'editor');

# 用 execute 灌測試資料,只灌本地,不進追蹤表
wrangler d1 execute my-app-db --local --file=./seed-dev.sql

# .github/workflows/deploy.yml(節錄)
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      # 步驟一:先套用資料庫遷移(schema 先就緒)
      - name: Apply D1 migrations
        run: npx wrangler d1 migrations apply my-app-db --remote
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

      # 步驟二:再部署 Worker(此時新程式碼依賴的表已存在)
      - name: Deploy Worker
        run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

// src/schema.ts:用 TypeScript 定義 schema(這是唯一真相來源)
import { sqliteTable, text, integer, index } from "drizzle-orm/sqlite-core";
import { sql } from "drizzle-orm";

export const users = sqliteTable("users", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  email: text("email").notNull().unique(),
  name: text("name").notNull(),
  active: integer("active", { mode: "boolean" }).notNull().default(true),
  createdAt: text("created_at").notNull().default(sql`(datetime('now'))`),
}, (t) => ({
  emailIdx: index("idx_users_email").on(t.email),
}));

# 1. drizzle-kit 比對 schema.ts 與現有遷移,自動產生新的遷移 SQL
npx drizzle-kit generate
# 產生 migrations/0001_xxx.sql(Drizzle 命名的遷移檔)

# 2. 用熟悉的 wrangler 指令套用(先本地後遠端)
wrangler d1 migrations apply my-app-db --local
wrangler d1 migrations apply my-app-db --remote

# ❌ 常見疏漏:只套本地就以為完成了
wrangler d1 migrations apply my-app-db --local

# ✅ 正確:本地驗證後,遠端也要套(或交給 CI 自動做)
wrangler d1 migrations apply my-app-db --local
wrangler d1 migrations apply my-app-db --remote

# ❌ 錯誤:直接改已套用的 0002_add_posts.sql

# ✅ 正確:新建 0004 往前修(補欄位 / 改索引)
wrangler d1 migrations create my-app-db fix_posts_add_excerpt

-- migrations/0004_fix_posts_add_excerpt.sql
-- 用新遷移修正:補上當初漏掉的 excerpt 欄位
ALTER TABLE posts ADD COLUMN excerpt TEXT;

-- migrations/0005_restructure.sql
-- 重組有外鍵關聯的表時,先延遲外鍵檢查(交易結束自動重置)
PRAGMA defer_foreign_keys = true;

DROP TABLE IF EXISTS post_tags;
CREATE TABLE post_tags (
  post_id INTEGER NOT NULL,
  tag_id  INTEGER NOT NULL,
  PRIMARY KEY (post_id, tag_id),
  FOREIGN KEY (post_id) REFERENCES posts(id) ON DELETE CASCADE,
  FOREIGN KEY (tag_id)  REFERENCES tags(id)  ON DELETE CASCADE
);