Cloudflare D1 を運用するときの基本 — バックアップ、マイグレーション、大きなデータ
Cloudflare D1 は、Cloudflare Pages や Workers から使える SQLite ベースのデータベースです。サーバーを用意しなくても使えて手軽な反面、ふだんの運用で「どうやってバックアップする?」「大きなデータが入らない」といったところで手が止まりがちです。この記事では、Pages Functions から D1 を使うときの基本と、運用で気をつけたいことをまとめます。Pages そのものの話は Cloudflare Pages の記事 もどうぞ。
つなぎ方:wrangler.toml にバインディングを書く
D1 は、プログラムからは「バインディング」という名前で見えます。wrangler.toml にデータベースを登録しておくと、Functions の中で env.DB のように使えます。
[[d1_databases]]
binding = "DB"
database_name = "my-content"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
// functions/api/posts/[slug].ts
export const onRequestGet: PagesFunction<{ DB: D1Database }> = async ({ env, params }) => {
const post = await env.DB
.prepare("SELECT title, body_html FROM posts WHERE slug = ? AND status = 'published'")
.bind(String(params.slug))
.first();
if (!post) return new Response("Not found", { status: 404 });
return Response.json(post);
};
値は文字列でつなげず、かならず ? と bind() で渡します。SQL インジェクションを防ぐ、いちばん大事な習慣です。
ローカルとリモートを取りちがえない
wrangler のコマンドは、手元の開発用データベース(ローカル)と、本番のデータベース(リモート)のどちらにも向けられます。
npx wrangler d1 execute my-content --local --command "SELECT count(*) FROM posts"
npx wrangler d1 execute my-content --remote --command "SELECT count(*) FROM posts"
どちらも付けないと、最近の wrangler ではローカルに向きます。【要確認:既定の向き先は wrangler の版によってちがう】本番を見ているつもりで手元を見ていた、ということが起きやすいので、--local か --remote はいつも明示しておくのがおすすめです。
書きかえる前に、バックアップ
本番のデータを書きかえたり、テーブルの形を変えたりする前には、まず SQL ファイルに書き出しておきます。
npx wrangler d1 export my-content --remote --output backups/my-content-$(date +%Y%m%d-%H%M%S).sql
書き出しが失敗したら、その先には進まない、と決めておくと安心です。スクリプトにするなら、ファイルが空でないことまで確かめます。
f=backups/my-content-$(date +%Y%m%d-%H%M%S).sql
npx wrangler d1 export my-content --remote --output "$f" && test -s "$f" || { echo "backup failed"; exit 1; }
D1 には、過去の時点に戻せる「Time Travel」という機能もあります。万一のときの保険になりますが、戻せる期間には上限があります。【要確認:保存期間はプランによってちがう(無料プランと有料プラン)】手元の SQL ファイルとあわせて使うと、より安心です。
マイグレーション:順番は「バックアップ → マイグレーション → デプロイ」
テーブルの形の変更は、マイグレーションのファイルにして管理します。
npx wrangler d1 migrations create my-content add_cover_to_posts
# migrations/0002_add_cover_to_posts.sql を編集
# ALTER TABLE posts ADD COLUMN cover_url TEXT NOT NULL DEFAULT '';
npx wrangler d1 migrations apply my-content --remote
新しい列を使うコードを先にデプロイすると、列がまだないあいだにエラーが出ます。バックアップ、マイグレーション、デプロイの順にしておくと、この食いちがいが起きません。列は「足す」だけにして、古いコードからも動く形にしておくと、デプロイを戻したときにも困りません。
大きなデータでつまずくとき
D1 には、1つの SQL 文の長さに上限があります。【要確認:Cloudflare の制限ページでは 100 KB】画像などを BLOB で入れようとして、長い INSERT 文を作ると「SQLITE_TOOBIG」というエラーで止まります。
どうしても D1 に入れたいときは、データを16進の文字列にして、何回かに分けてつなげ、最後にバイナリへ戻す方法があります。
INSERT INTO media (id, data_hex) VALUES ('a1', '89504e47...'); -- 1つめのかけら
UPDATE media SET data_hex = data_hex || '0d0a1a0a...' WHERE id = 'a1'; -- 続きを足す
-- ...くり返す...
UPDATE media SET data = unhex(data_hex), data_hex = NULL WHERE id = 'a1';
ただ、これは小さな画像などにとどめておくのが無難です。大きなファイルは、オブジェクトストレージの R2 に置いて、D1 にはその場所(キー)だけを入れるほうが、読み書きもバックアップも軽くなります。
もうひとつ、1つの文で bind() に渡せる値の数にも上限があります。【要確認:制限ページの値】たくさんの行をまとめて入れるときは、何行かずつに分けて env.DB.batch() で送ると、まとめて実行できます。
ローカルで試してから、本番へ
マイグレーションや、データを書きかえる SQL は、先にローカルのデータベースで流してみると安心です。本番のバックアップをローカルに読みこめば、ほぼ同じデータで試せます。
npx wrangler d1 execute my-content --local --file backups/my-content-20261022-103000.sql
npx wrangler d1 migrations apply my-content --local
ローカルで問題なく動いたら、同じ手順を --remote で行います。【要確認:書き出したファイルをローカルへ読みこむとき、テーブルがすでにあるとエラーになるので、空のローカル環境で試す】
運用の小さなコツ
- まとまった変更は SQL ファイルにして
--fileで流す。あとから何をしたか読み返せる - 記事など人が書く中身は、書きかえる前の版を別テーブルに残しておくと、戻すのがかんたん
--jsonを付けると結果が JSON で返るので、スクリプトで確かめやすい- API トークンなどの秘密の値は、コマンドやファイルに書きこまない
まとめ
- D1 はバインディングで使う。値は
bind()で渡す --localと--remoteはいつも明示する- 書きかえる前に export。失敗したら進まない
- バックアップ → マイグレーション → デプロイの順
- 大きなファイルは R2 へ。D1 には場所だけ

