Gadget 38：D1 データベース

サーバーレス SQLite（D1）の使いどころ・注意点・マイグレーション

D1 データベース

Cloudflare のサーバーレス SQLite「D1」を、正しく使い分けるためのガイドです。

目的

  • D1 が「どの用途に向くか」を把握する
  • マイグレーション・SQL の基本と注意点を押さえる

前提条件

  • Workers 基礎（35-workers-basics）
  • 公式: https://developers.cloudflare.com/d1/

D1 とは

  • サーバーレス SQLite（書き込み分散・読み取りはエッジから）
  • SQL がそのまま使える。ACID・WAL。バックアップ付き
  • リレーショナルデータの主戦場（KV/R2 との使い分けは下表）

ストレージの使い分け

機能 用途の目安
D1 リレーショナル・集計・トランザクションが必要なデータ
KV キャッシュ的な高速読み書き（最終的に整合）
R2 大きなバイナリ・画像などのオブジェクト
DO Storage オブジェクト単位の強整合状態（36）

手順

1. データベースを作成

npx wrangler d1 create tasks-db

2. バインドを追加

[[d1_databases]]
binding = "DB"
database_name = "tasks-db"
database_id = "<id>"

3. スキーマとマイグレーション

npx wrangler d1 migrations create tasks-db create-tasks
-- migrations/0001_create-tasks.sql
CREATE TABLE tasks (
  id INTEGER PRIMARY KEY,
  title TEXT NOT NULL,
  done INTEGER NOT NULL DEFAULT 0
);
npx wrangler d1 migrations apply tasks-db

4. Worker から使う

async fetch(request, env) {
  const res = await env.DB.prepare(
    "INSERT INTO tasks (title) VALUES (?) RETURNING *"
  ).bind("買い物").run();
  return Response.json(res);
}

よくある失敗

症状 原因 対処
読み取りが遅い 大規模なクエリ インデックス・リード削減を検討
マイグレーションに失敗 migration ファイルの追記漏れ 適用順を管理し、テスト DB で先行
KV/D1/R2 を間違える 用途混同 使い分け表で再確認
ローカルと本番で差分 ローカル張替え漏れ wrangler d1 migrations apply --local を使う

確認

次に読む