放課後リンク 開発仕様

Appearance

データベース移行・運用ガイド (Database Management Guide) ​

本ドキュメントでは、「放課後リンク」で使用されているデータベースシステム（Cloudflare D1 / ローカル SQLite）のスキーマ変更、マイグレーション管理、バックアップおよびデータメンテナンス手順について解説します。

1. D1データベース（本番）とローカルSQLite（開発）の仕様差異 ​

開発の迅速化のため、ローカル環境では SQLite ファイルを使用し、本番環境では Cloudflare D1 (SQLite 互換の分散サーバーレスDB) を使用します。基本的には同一の SQL を解釈しますが、以下の制約を考慮する必要があります。

Prisma使用時のD1固有の制限事項 ​

  • 自動インクリメント: D1での AUTOINCREMENT キーは、スキーマ定義によって予期しないインデックス競合を起こす場合があります。極力 UUID またはコード（文字列）による主キー設定を推奨します。
  • トランザクション: D1 は従来のマルチステートメントトランザクション（BEGIN TRANSACTION ... COMMIT）に一部制限があり、Prisma のインタラクティブトランザクション（$transaction）は限定的にエミュレートされます。バルク書き込み時には、トランザクション内の処理を最小限に抑えるよう設計してください。
  • 同時接続数とタイムアウト: D1はサーバーレス環境で水平スケールするため、一時的な書き込みロック（SQLITE_BUSY）が発生しやすくなります。Prisma の接続初期化オプションで、busy_timeout=5000 などのリトライタイムアウトを設定してタイムアウトを防止します。

2. マイグレーション実行とスキーマ変更手順 ​

スキーマを変更する（prisma/schema.prisma を書き換える）場合は、以下の手順に従ってローカルおよび本番 DB に適用します。

Step 1: schema.prisma の編集 ​

Prisma スキーマファイルに必要なフィールドやモデルを追加します。

Step 2: ローカルマイグレーションファイルの自動生成と適用 ​

bash
cd app/api
npx prisma migrate dev --name describe-your-change

これにより、以下の処理が実行されます。

  1. ローカルの SQLite データベースに変更が適用されます。
  2. prisma/migrations/YYYYMMDDHHMMSS_describe_your_change/migration.sql というマイグレーションSQLファイルが自動生成されます。
  3. ローカル用の Prisma Client が再生成されます。

Step 3: Cloudflare D1 (本番/検証) へのマイグレーション適用 ​

Wrangler を使用して、自動生成されたマイグレーションファイルを D1 データベースに適用します。

bash
# 検証（Staging）環境への適用
npx wrangler d1 migrations apply houkago_link_d1_test --remote --env staging

# 本番（Production）環境への適用
npx wrangler d1 migrations apply houkago_link_d1 --remote

3. 本番データのバックアップおよびリストア運用 ​

本番環境のデータを保全し、障害時やシステム移行時に迅速に復旧するための運用手順です。

3.1 Cloudflare 自動バックアップ ​

Cloudflare D1 は標準で 過去24時間毎の自動バックアップ をバックグラウンドで取得しています。

  • 復元方法: Cloudflare ダッシュボードの [D1] ＞ 対象データベース ＞ [Backups] タブを開き、復元したい世代の「Restore」をクリックします。

3.2 手動バックアップ（SQLダンプ出力） ​

マイグレーションの適用前など、重要な操作を行う直前には手動で SQL ダンプを出力してください。

bash
npx wrangler d1 export houkago_link_d1 --remote --output=./backups/backup_prod_$(date +%Y%m%d%H%M%S).sql

生成された .sql ファイルは安全なストレージに保管します。

3.3 リストア（復元）手順 ​

  1. 手動バックアップファイルまたはローカルの SQL スクリプトを D1 に流し込みます。
bash
npx wrangler d1 execute houkago_link_d1 --remote --file=./backups/backup_prod_2026xxxxxx.sql

4. Prisma Studio によるローカル・本番データの閲覧と編集 ​

Prisma Studio はブラウザベースの GUI を用いて、データベースのデータを直感的に検索・編集できる強力なツールです。

4.1 ローカルデータベースの閲覧 ​

bash
cd app/api
npx prisma studio

自動的にブラウザで http://localhost:5555 が開き、ローカルの児童マスタやログ情報を直接スプレッドシート感覚で閲覧・編集できます。

4.2 本番 D1 データの閲覧方法 ​

Wrangler にバインドされているため、直接 npx prisma studio を本番 D1 に向けることはできません。本番データを安全にローカルで確認したい場合は、一旦手動バックアップで SQL ダンプを取得し、ローカルの SQLite データベースにダンプを流し込んでから Prisma Studio を起動してください。

bash
# 1. 本番のデータをエクスポート
npx wrangler d1 export houkago_link_d1 --remote --output=./prisma/temp_prod.sql

# 2. ローカルの SQLite データベース(dev.db)を一時的にダンプ内容で上書き
sqlite3 prisma/dev.db < prisma/temp_prod.sql

# 3. Prisma Studio 起動
npx prisma studio

CAUTION

本番データをローカル環境にダウンロードして閲覧する際は、個人情報（PII）の取り扱いに極めて厳重な配慮（暗号化ディスクでの保持、確認後の速やかなファイル物理削除など）を行ってください。

放課後リンク 開発プロジェクト

Copyright © 2026 NGS / takao-dev. All Rights Reserved.