D1 入門:Serverless SQLite,在邊緣用 SQL 查資料,免管理資料庫 | Cloudflare 完整教學

// 三步驟拆解
const stmt = env.DB.prepare("SELECT * FROM users WHERE id = ?"); // 1. 準備語句(未執行)
const bound = stmt.bind(userId);                                 // 2. 綁定參數到 ? 佔位符
const result = await bound.all();                                // 3. 執行,取回所有列

// 實務上多半鏈式寫(method chaining)
const { results } = await env.DB
  .prepare("SELECT * FROM users WHERE id = ?")
  .bind(userId)
  .all();

# 建立新資料庫(名稱建立後不可更改,慎選)
wrangler d1 create my-app-db

# 輸出範例(把這段 d1_databases 設定複製到 wrangler.jsonc):
# ✅ Successfully created DB 'my-app-db' in region APAC
#
# [[d1_databases]]
# binding = "DB"
# database_name = "my-app-db"
# database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# 列出所有資料庫、查看單一資料庫詳情
wrangler d1 list
wrangler d1 info my-app-db

{
  "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"   // 建立時取得的 UUID
    }
  ]
}

// src/index.ts
interface Env {
  DB: D1Database;
}

-- schema.sql:定義 users 表與常用索引
CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  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);

# 先套用到本地模擬資料庫(開發用,資料在你電腦裡)
wrangler d1 execute my-app-db --local --file=./schema.sql

# 確認本地正常後,再套用到雲端正式資料庫
wrangler d1 execute my-app-db --remote --file=./schema.sql

# 也可以直接下單行命令快速查看(例如確認建表成功)
wrangler d1 execute my-app-db --local --command="SELECT name FROM sqlite_master WHERE type='table'"

interface User {
  id: number;
  email: string;
  name: string;
  active: number;
  created_at: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    // ── .all():查所有列,回傳 { results, success, meta } ──
    if (url.pathname === "/users") {
      const { results, meta } = await env.DB
        .prepare("SELECT * FROM users WHERE active = ? ORDER BY created_at DESC")
        .bind(1)
        .all<User>();
      console.log(`查到 ${results.length} 筆,讀取 ${meta.rows_read} 列`); // rows_read 是計費依據
      return Response.json(results);
    }

    // ── .first():只取第一列,找不到回 null ──
    if (url.pathname === "/user") {
      const id = url.searchParams.get("id");
      const user = await env.DB
        .prepare("SELECT * FROM users WHERE id = ? LIMIT 1")
        .bind(id)
        .first<User>();
      if (user === null) {
        return new Response("找不到使用者", { status: 404 }); // 一定要處理 null
      }
      return Response.json(user);
    }

    return new Response("Not Found", { status: 404 });
  },
} satisfies ExportedHandler<Env>;

// 新增一筆使用者
const result = await env.DB
  .prepare("INSERT INTO users (name, email) VALUES (?, ?)")
  .bind("Alice", "alice@example.com")
  .run();

console.log(`新增成功,新 ID:${result.meta.last_row_id}`); // 取回自增主鍵

// 更新:用 meta.changes 判斷是否真的有更新到
const update = await env.DB
  .prepare("UPDATE users SET name = ? WHERE id = ?")
  .bind("Alice Wang", 1)
  .run();

if (update.meta.changes === 0) {
  // changes === 0 代表沒有任何列符合條件(例如該 id 不存在)
  console.log("沒有更新任何列");
}

// 情境:建立訂單的同時扣庫存,兩件事必須同生共死
async function placeOrder(env: Env, userId: number, productId: number, qty: number) {
  const results = await env.DB.batch([
    // 這兩個語句作為一個原子交易:要嘛都成功,要嘛都不做
    env.DB
      .prepare("INSERT INTO orders (user_id, product_id, qty) VALUES (?, ?, ?)")
      .bind(userId, productId, qty),
    env.DB
      .prepare("UPDATE products SET stock = stock - ? WHERE id = ?")
      .bind(qty, productId),
  ]);

  // batch 回傳一個 D1Result 陣列,順序對應傳入的語句
  const [orderResult] = results;
  return orderResult.meta.last_row_id; // 新訂單 ID
}

// 批次插入多筆:一次往返,而不是迴圈裡 N 次查詢
async function seedUsers(env: Env, users: { name: string; email: string }[]) {
  const stmt = env.DB.prepare("INSERT INTO users (name, email) VALUES (?, ?)");
  // 用 map 把每一筆資料綁到同一個語句,組成一個陣列丟給 batch
  await env.DB.batch(users.map((u) => stmt.bind(u.name, u.email)));
}

const userId = new URL(request.url).searchParams.get("id");

// ❌ 危險:字串插值。若 userId = "1 OR 1=1 --",這查詢會回傳整張表!
const bad = await env.DB
  .prepare(`SELECT * FROM users WHERE id = ${userId}`)
  .all();

// ✅ 安全:? 佔位符 + bind()。userId 永遠被當成純資料,不會被解析成 SQL
const good = await env.DB
  .prepare("SELECT * FROM users WHERE id = ?")
  .bind(userId)
  .all();

// 動態 WHERE:結構動態組,值全部走 bind(),仍然 100% 防注入
function buildUserQuery(filters: { name?: string; active?: boolean }) {
  const conditions: string[] = [];
  const params: (string | number)[] = [];

  if (filters.name !== undefined) {
    conditions.push("name LIKE ?");   // 結構:欄位 + 佔位符
    params.push(`%${filters.name}%`); // 值:進 params,之後 bind
  }
  if (filters.active !== undefined) {
    conditions.push("active = ?");
    params.push(filters.active ? 1 : 0);
  }

  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
  return { sql: `SELECT * FROM users ${where} ORDER BY created_at DESC`, params };
}

// 使用
const { sql, params } = buildUserQuery({ name: "王", active: true });
const { results } = await env.DB.prepare(sql).bind(...params).all<User>();

// ❌ 錯誤:用使用者輸入的 email 拼字串
const email = await request.text();
await env.DB.prepare(`SELECT * FROM users WHERE email = '${email}'`).first();

// ✅ 正確:? + bind(),值被當成純資料
await env.DB.prepare("SELECT * FROM users WHERE email = ?").bind(email).first();

// ❌ 錯誤:兩個 ? 卻只 bind 一個值
await env.DB.prepare("INSERT INTO users (name, email) VALUES (?, ?)").bind("Alice").run();

// ✅ 正確:? 的數量 = bind 參數個數,且順序對應
await env.DB.prepare("INSERT INTO users (name, email) VALUES (?, ?)").bind("Alice", "alice@example.com").run();

// ❌ 慢:迴圈裡 N 次獨立往返
for (const u of users) {
  await env.DB.prepare("INSERT INTO users (name, email) VALUES (?, ?)").bind(u.name, u.email).run();
}

// ✅ 快:batch 一次往返,還順便有交易保證
const stmt = env.DB.prepare("INSERT INTO users (name, email) VALUES (?, ?)");
await env.DB.batch(users.map((u) => stmt.bind(u.name, u.email)));

# 開發:先在本地建表、灌測試資料、跑 dev server(全都連本地庫)
wrangler d1 execute my-app-db --local --file=./schema.sql
wrangler dev                 # 預設連本地模擬庫,安全

# 上線:確認無誤,才把 schema 套到遠端正式庫
wrangler d1 execute my-app-db --remote --file=./schema.sql