はじめに
チケットサービスに緊急度を追加する必要があります。ただし、既存のリクエストは失わないようにします。古い行が新しいルールを満たせない場合、スキーマの展開は失敗する可能性があります。この実験では、順序付けたマイグレーションを作成してローカルでテストし、チケットの ID と件名を保持したまま、同じファイルをリモートにも適用します。
この実験は、用意された初期マイグレーションを使って独立して開始します。D01 で扱ったデータベースの作成と基本的な SQL を前提としますが、以前の VM やデータベースは使用しません。
自分の学習用アカウントと新しい VM を使用してください。セットアップでは、まず Node.js 22.22.0 を準備し、その後 /home/labex/project/ticket-database でプロジェクト専用の Wrangler 4.131.1 と評価用依存関係を npm install します。直接指定された依存関係のバージョンは固定されており、インストール時に専用のロックファイルが作成されます。セットアップ中にクラウドへのログインや、評価対象となるデータベース操作は実行されません。個人のマシンで実行する場合は、プロジェクト内で npm install --save-dev wrangler@4.131.1 を実行して同じバージョンの Wrangler をインストールしてください。
この演習では、D1 Free の無料枠の範囲内で小さな合成レコードを使用します。既存のアカウント使用量も無料枠に加算されます。購入済みのドメインは必要ありません。リソースの削除とログアウトの両方を確認するまで、この VM を保持してください。
この VM を認証し、アカウントを選択する
このステップでは、新しいターミナルを自分の学習用アカウントに接続します。Dashboard にログインしただけでは、VM は認証されません。D1 の権限によって、データベースの作成、SQL の変更、削除が可能になります。認証する前に、Background Access を含む同意画面の内容を確認してください。
用意されたプロジェクトを開き、固定されている CLI のバージョンを確認します。
cd /home/labex/project/ticket-database
npx wrangler --version
4.131.1 と表示されることを確認します。デバイス認証を開始します。--device はブラウザーに入力するコードを表示し、--browser=false はブラウザーを自分で選択できるようにします。
npx wrangler login --device --browser=false --scopes account:read user:read d1:write
表示された URL をブラウザーで開き、現在のコードを入力します。学習用アカウントと権限を確認して、認証を許可してください。ターミナルに成功メッセージが表示されるまで待ちます。パスワードやトークンをプロジェクトファイルに貼り付けないでください。
npx wrangler whoami --json
loggedIn: true を確認します。アカウントが 1 つだけ表示される場合でも、アカウントの name と id を読み取ってください。使用するアカウントの ID を、次の設定にコピーします。次のシェル変数では、他の学習者との衝突を避けるために 6 バイトの乱数（16 進数 12 文字）を使用します。ヒアドキュメントにより、JSON の行で囲まれた内容から JSON が作成されます。内部では $RUN が展開されます。
$schema の前のバックスラッシュは、この JSON キーを文字どおり保持します。$RUN は引き続き今回の実行に固有の名前に展開されます。
RUN=labex-c04-d03-$(openssl rand -hex 6)
cat > wrangler.jsonc <<JSON
{
"\$schema": "./node_modules/wrangler/config-schema.json",
"name": "$RUN",
"account_id": "YOUR_ACCOUNT_ID",
"main": "src/index.js",
"compatibility_date": "2026-09-15",
"workers_dev": true,
"preview_urls": false
}
JSON
ブロックを実行する前に、YOUR_ACCOUNT_ID を実際のアカウント ID に置き換えてください。RUN の値を引き続き使えるように、このターミナルは開いたままにします。name は今回の実行を識別し、account_id はクラウド操作に使用するアカウントを選択します。このファイルは通常の JSON であり、JSONC としても有効です。このファイルを書き込むだけでは、Worker はデプロイされません。
既存のチケットデータベースを準備する
このステップでは、アプリケーションデータベースの既存バージョンを準備します。マイグレーションは、スキーマの変更内容を記述した番号付きの SQL ファイルです。Wrangler は適用済みファイル名を d1_migrations に記録するため、完了済みの作業と保留中の作業を区別できます。セットアップでは、古いアプリケーションバージョンとして 0001_initial.sql が用意されています。アップグレード用のファイルは自分で作成します。
一時的に使用するクラウドデータベースを作成します。--binding DB はアプリケーションコードで使う短い名前を設定し、--update-config は実際の名前と UUID を wrangler.jsonc に記録します。--use-remote=false により、開発時の操作をローカルに限定します。
npx wrangler d1 create "$RUN-db" --binding DB --update-config --use-remote=false
作成された名前と ID を読み取り、保存されたバインディングを確認します。
cat wrangler.jsonc
DB エントリには、この実行で作成したデータベースの名前が設定されている必要があります。バインディングとは、コードとリソースを接続する設定です。UUID はクラウドデータベースを識別し、--local を指定するとこの VM 内の別の SQLite データベースが使用されます。SQL コマンドでは、必ず --local または --remote のどちらかを指定してください。
適用する前に、古いスキーマを確認します。
cat migrations/0001_initial.sql
既存のチケットは 2 件で、priority 列はありません。このマイグレーションをローカルとリモートの両方に個別に適用し、確認を求められたら、この実験で作成したデータベースであることを確認します。
npx wrangler d1 migrations apply DB --local
npx wrangler d1 migrations apply DB --remote
行と、適用済みの状態を確認します。
npx wrangler d1 execute DB --remote --command "SELECT id, subject, status, source FROM tickets ORDER BY id; SELECT name FROM d1_migrations ORDER BY id;"
元の 2 件のチケットが両方存在し、適用済みのマイグレーションが 0001_initial.sql である必要があります。適用済みのマイグレーションは履歴です。後から変更する場合は、その履歴を編集せず、新しいファイルを作成してください。
制約付きの優先度をローカルに追加する
このステップでは、テーブルを削除せずに、既存のチケットへデフォルトの優先度を追加します。ALTER TABLE ... ADD COLUMN は、テーブルをその場で変更します。NULL を許可しない列を追加する場合、既存の行に使用できるデフォルト値が必要です。CHECK により、優先度を normal または urgent に制限します。
次の番号のマイグレーションを作成します。
npx wrangler d1 migrations create DB add_priority
この新しいプロジェクトでは、migrations/0002_add_priority.sql が作成されます。出力でファイル名を確認してください。新しく作成されたファイルに変更内容を書き込みます。
cat > migrations/0002_add_priority.sql <<'SQL'
ALTER TABLE tickets ADD COLUMN priority TEXT NOT NULL DEFAULT 'normal' CHECK(priority IN ('normal','urgent'));
SQL
保留中のマイグレーションを一覧表示してから、ローカルにだけ適用します。
npx wrangler d1 migrations list DB --local
npx wrangler d1 migrations apply DB --local
既存の 2 件のチケットに normal が設定されるはずです。緊急度が高いチケットを 1 件追加し、確認します。
npx wrangler d1 execute DB --local --command "INSERT INTO tickets (id, subject, source, priority) VALUES (3, 'Service unavailable', 'local', 'urgent'); SELECT id, subject, priority FROM tickets ORDER BY id;"
許可されていない優先度は、黙ってテーブルに登録されず、エラーになる必要があります。
npx wrangler d1 execute DB --local --command "UPDATE tickets SET priority = 'critical' WHERE id = 3;"
CHECK constraint failed と表示されることを確認します。この意図的なエラーにより、チケット 3 の優先度は urgent のままです。リモートデータベースで PRAGMA table_info(tickets) を読み取り、クラウドのスキーマがまだ古いバージョンであることを確認します。
npx wrangler d1 execute DB --remote --command "PRAGMA table_info(tickets);"
リモートにはまだ priority 列がありません。ローカルでマイグレーションに成功しても、クラウドは更新されません。
テスト済みのマイグレーションをリモートに適用する
このステップでは、確認済みの同じファイルをリモートデータベースに展開します。確認する前に、保留中の作業を確認します。
npx wrangler d1 migrations list DB --remote
npx wrangler d1 migrations apply DB --remote
保留中なのは 0002_add_priority.sql だけであることを確認します。既存の行は保持されます。リモートに緊急度の高いチケットを追加し、データとマイグレーション履歴の両方を確認します。
npx wrangler d1 execute DB --remote --command "INSERT INTO tickets (id, subject, source, priority) VALUES (3, 'Service unavailable', 'remote', 'urgent'); SELECT id, subject, priority FROM tickets ORDER BY id; SELECT name FROM d1_migrations ORDER BY id;"
チケット 1 と 2 は件名を保持し、優先度は normal になります。チケット 3 の優先度は urgent です。2 つの番号付きファイルが両方とも記録されます。もう一度 apply を実行します。
npx wrangler d1 migrations apply DB --remote
保留中のマイグレーションはないと報告され、行は変更されないはずです。これが履歴テーブルの重要な理由です。展開を再実行しても、完了済みのファイルは再実行されません。Dashboard で今回の実行に対応する D1 データベースを開き、スキーマまたはテーブルの表示を確認して、新しい列と CLI の結果を対応付けてください。そこでスキーマを編集しないでください。
この例では、元の 2 件のチケットにデフォルトの優先度 normal が設定され、新しいリモートチケットに urgent が設定されています。生成されたデータベース名はこの実行例を識別するもので、あなたの名前は異なります。上記の SQL クエリ、移行履歴、制約のチェックで結果を確認します。スクリーンショットは見た目の参考です。
一時リソースを削除する
このステップでは、VM がまだ認証された状態で、この実験で作成したリソースだけを削除します。最初に、すべての機能確認を完了してください。削除の確認が終わるまで、設定ファイルは保持します。
npx wrangler d1 delete DB
プロンプトの内容を確認し、この実行で作成したデータベースだけが対象であることを確認します。その後、データベースを一覧表示します。
npx wrangler d1 list --json
成功した応答に、記録しておいたデータベース名と UUID が含まれていないことを確認します。他のリソースは残っていてもかまいません。認証またはネットワークのエラーが発生した場合、削除を確認できたとは限りません。アクセスを解決し、続行する前に読み取り操作を再実行してください。ログインしたまま、このステップの検証を実行します。
この VM の認証を終了する
このステップでは、独立した削除確認に成功した後でのみ、認証を終了します。ログアウトすると、この VM に保存された Wrangler の認証情報が削除されます。VM を閉じただけでは、クラウドのクリーンアップにはなりません。
npx wrangler logout
npx wrangler whoami --json
loggedIn: false と表示されることを確認します。認証されていない状態でのこのクエリは、終了ステータスが 0 以外になる場合があります。構造化された応答でログアウト済みであることが明示されている場合に限り、それは想定された動作です。確認を完了してから、実験環境を終了してください。
まとめ
チケットスキーマのマイグレーションを実践しました。データベースで確認できる結果を確認し、選択したアカウントとローカルの状態を明示したうえで、ログアウトする前に一時リソースを削除しました。
