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 には場所だけ

シェアする

Xでシェア
ほかの記事も読んでみてねブログの一覧へ

← ブログ一覧へ