設計 D1 資料庫綱要（資料表與 migration）

綱要（schema）就是你資料庫的設計藍圖——有哪些資料表、每張表有哪些欄位，以及讓資料保持乾淨的規則。這篇我們會設計一個迷你部落格：使用者（users）撰寫貼文（posts）。你會學到主鍵（primary key）、外鍵（foreign key）、索引（index），以及 NOT NULL／UNIQUE 規則，最後用 migration 管理之後的每一次變更。

D1 底層是 SQLite，所以這裡用的就是樸實的標準 SQL。核心觀念是：一開始把資料表設計好，之後絕不直接手動改線上資料庫——而是為每次變更寫一個小小的 migration 檔，讓你的綱要擁有清楚、有版本紀錄的歷史。

一位使用者可以發表很多篇貼文，而每篇貼文剛好屬於一位使用者，這就是「一對多」（one-to-many）關聯。我們用外鍵把它們連起來：posts.user_id 指回 users.id。

以下是你之後設計幾乎每一張資料表都會用到的基本元件。

應用程式會長大：你總會需要新增欄位、新表，或新索引。Migration 就是一個小小、有編號的 SQL 檔（0001_...、0002_...），剛好記錄一次變更。Wrangler 會記住哪些檔案已經跑過，所以在每個環境套用都能重現一樣的結果。

黃金守則：一旦某個 migration 已經套用到共用或正式資料庫，就絕對不要再去改那個檔案。要修正或變更，就寫一個新的 migration。這能讓歷史保持誠實，隊友只要跑一次 migrations apply 就能跟上進度。

現在把全部串起來：建立資料庫、綁定到 Worker、在 migration 裡定義綱要、套用它、再加第二個 migration 讓綱要演進，最後用 JOIN 跨兩張表查詢。

1. 建立資料庫

   Wrangler 會印出一組 database_id——複製起來，下一步會用到。

   bashcontent_copy複製

   npx wrangler d1 create blog-db

2. 綁定到你的 Worker

   把這段加進 wrangler.jsonc，讓 Worker 能用 env.DB 存取這個資料庫。

   jsoncontent_copy複製

   {
     "d1_databases": [
       {
         "binding": "DB",
         "database_name": "blog-db",
         "database_id": "<paste-your-id-here>"
       }
     ]
   }

3. 建立第一個 migration

   這會建立一個 migrations/ 資料夾，以及一個空的 0001_create_users_and_posts.sql 檔。

   bashcontent_copy複製

   npx wrangler d1 migrations create blog-db create_users_and_posts

4. 寫下綱要 SQL

   打開剛產生的檔案，把兩張表連同它們的鍵、約束與索引都定義好。

   sqlcontent_copy複製

   -- migrations/0001_create_users_and_posts.sql
   -- Enforce foreign keys (SQLite leaves this off by default)
   PRAGMA foreign_keys = ON;
   
   CREATE TABLE users (
     id         INTEGER PRIMARY KEY,
     email      TEXT NOT NULL UNIQUE,
     name       TEXT NOT NULL,
     created_at TEXT NOT NULL DEFAULT (datetime('now'))
   );
   
   CREATE TABLE posts (
     id         INTEGER PRIMARY KEY,
     user_id    INTEGER NOT NULL,
     title      TEXT NOT NULL,
     body       TEXT,
     status     TEXT NOT NULL DEFAULT 'draft',
     created_at TEXT NOT NULL DEFAULT (datetime('now')),
     FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
   );
   
   -- Index the columns we filter and join on
   CREATE INDEX idx_posts_user_id ON posts (user_id);
   CREATE INDEX idx_posts_status  ON posts (status);

5. 先套用到本機，再套用到遠端

   先對本機副本測試；確認沒問題後，再套用到雲端上真正的資料庫。

   bashcontent_copy複製

   # Build the schema on the local test DB
   npx wrangler d1 migrations apply blog-db --local
   
   # See what is still pending on production
   npx wrangler d1 migrations list blog-db --remote
   
   # Apply to the real cloud database
   npx wrangler d1 migrations apply blog-db --remote

6. 之後讓綱要演進

   需要新欄位？建立第二個 migration，而不是去改第一個——接著用同樣方式套用。

   bashcontent_copy複製

   npx wrangler d1 migrations create blog-db add_published_at_to_posts
   
   # In migrations/0002_add_published_at_to_posts.sql:
   #   ALTER TABLE posts ADD COLUMN published_at TEXT;
   
   npx wrangler d1 migrations apply blog-db --local
   npx wrangler d1 migrations apply blog-db --remote

7. 從 Worker 跨表查詢

   prepare() 建立安全查詢，bind() 填入 ? 佔位符（擋掉 SQL 注入），JOIN 則把每篇貼文和它的作者一起拉出來。

   jscontent_copy複製

   export default {
     async fetch(request, env) {
       const url = new URL(request.url);
       const userId = url.searchParams.get("user_id") ?? "1";
   
       // Join each post to its author, newest first.
       const { results } = await env.DB
         .prepare(
           `SELECT posts.id, posts.title, posts.status, users.name AS author
            FROM posts
            JOIN users ON users.id = posts.user_id
            WHERE posts.user_id = ?
            ORDER BY posts.created_at DESC`
         )
         .bind(userId)
         .all();
   
       return Response.json(results);
     },
   };

8. 部署上線

   發布這個 Worker——你那個有綱要撐腰的 API 就上線了。

   bashcontent_copy複製

   npx wrangler deploy

塞一點資料來測試

npx wrangler d1 execute blog-db --remote --command "INSERT INTO users (email, name) VALUES ('mei@example.com', 'Mei');"

npx wrangler d1 execute blog-db --remote --command "INSERT INTO posts (user_id, title, status) VALUES (1, 'Hello D1', 'live');"

• 用 PRAGMA foreign_keys = ON; 開啟外鍵約束，否則 SQLite 會忽略 FK 規則。
• 為每個外鍵、以及任何常用來篩選或排序的欄位都建立索引。
• SQLite 的 ALTER TABLE 能新增欄位、改名，但不容易刪欄位——欄位請事先想清楚再設計。
• 新增欄位時優先用 NOT NULL 搭配 DEFAULT，這樣既有的列才不會變不合法。
• 每個 migration 都先用 --local 測過再 --remote；本機副本又快又可隨時丟掉重建。
• 把 migrations/ 資料夾放進 Git，整段綱要歷史就會跟著你的程式碼一起走。