第 3 週 · 資料庫與 D1
建立 D1、schema 與 migrations
建立 D1 資料庫，用 migration 檔留下 schema 的版本。
正在打開這一關…
學習目標
- 建立一個 D1，並把綁定寫進 wrangler.jsonc
- 說明 migration 是可以重複套用的版本紀錄
- 在本機套用第一份建立 messages 的 SQL
昨天的 SQL 需要一個真的資料庫來執行。D1 是 Cloudflare 的 SQL 資料庫。Worker 不連外部主機的連線字串，而是用 綁定：設定檔給它一個變數名字，例如 DB，程式裡就用 env.DB。
用生活例子理解
- schema 是表格的格式規定：有哪些表、哪些欄位。它還不是客人的留言。
- migration（遷移檔）是格式的版本紀錄。第一份檔案建立表，以後若要加欄位，再新增下一份檔案，不要回去改已經套用過的舊檔。
- 本機與線上是兩本帳。
--local寫進你電腦裡的模擬資料庫，不會碰到線上。
生活比喻：migration 像裝修圖的修訂編號。第 1 版畫了牆，第 2 版加了一扇窗。你不會把第 1 版圖紙塗掉假裝牆一開始就有窗，否則別的工地對不到進度。
建立資料庫：
npx wrangler d1 create guestbook-db指令會給你 database_id。可以讓 Wrangler 幫你寫進設定，綁定名字用 DB。本機開發選本機資源，不要一開始就連線上。
建立遷移檔：
npx wrangler d1 migrations create guestbook-db create_messages它會在 migrations/ 放一個空的 SQL 檔，名稱類似 0001_create_messages.sql。你把建表語句貼進去。套用到本機：
npx wrangler d1 migrations apply guestbook-db --local這裡用資料庫名字 guestbook-db，不要只用綁定名字，避免之後綁定改名時跑錯本帳。
動手做
大約 30 分鐘。可對照 examples/03-guestbook-d1/。
- 在新的 Worker 專案執行
d1 create。沒有 Cloudflare 帳號時，仍可先把設定裡的database_id暫填一個練習用的 UUID，並只用--local。線上建立留到你準備佈署時。 - 確認
wrangler.jsonc有d1_databases，binding是DB。 - 產生 migration，貼上案例的 SQL。
migrations apply ... --local。- 再執行一次 apply。已套用的檔案不應再重建表。若看到「沒有待套用的遷移」之類的訊息，就是版本紀錄在起作用。
- 用下面指令看表是否在：
npx wrangler d1 execute guestbook-db --local --command "SELECT name FROM sqlite_master WHERE type = 'table';"你應看到 messages，以及 D1 用來記遷移的 d1_migrations。
案例
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "guestbook-d1",
"main": "src/index.js",
"compatibility_date": "2026-10-30",
"d1_databases": [
{
"binding": "DB",
"database_name": "guestbook-db",
"database_id": "00000000-0000-0000-0000-000000000001",
"migrations_dir": "migrations"
}
]
}database_id 必須換成 d1 create 印出的那一組。上面的全零編號只讓本機檔案先有合法形狀。
CREATE TABLE messages (
id INTEGER PRIMARY KEY AUTOINCREMENT,
author TEXT NOT NULL,
body TEXT NOT NULL,
created_at TEXT NOT NULL DEFAULT (datetime('now'))
);Worker 進入點可以先只證明綁定存在，明天再查表：
export default {
async fetch(request, env) {
if (!env.DB) {
return Response.json({ error: "沒有 DB 綁定" }, { status: 500 });
}
return Response.json({ ok: true });
},
};常見錯誤
- 改了已經 apply 過的
0001檔，卻以為資料庫會自動跟上。已經紀錄的遷移不會重跑。要改格式就新增0002。 - 把
database_name和綁定名字搞混。程式用的是綁定env.DB，指令列常用資料庫名字。 - 沒加
--local，結果對到線上的空資料庫或真資料。學習指令先養成看旗標的習慣。 - 手改儀表板的表，專案裡卻沒有 SQL 檔。換一台電腦就無法重建。
自我檢查
- schema 與某一列留言，哪個是格式、哪個是內容？
- 為什麼不要修改已經套用的遷移檔？
--local保護你不碰到哪一本帳？