convex-migrate-rehearse

本番環境に反映する前にプレビュー環境でスキーマ変更をリハーサルする

Convex でスキーマをプッシュすると、既存のすべてのドキュメントが新しいスキーマに適合するか検証され、適合しない行が1つでもあればプッシュは失敗します。これは実際のデータ適合性ゲートです。このゲートを安全に活用するには、本番環境ではなくリハーサル用のコピーで失敗させます。この機能を使うと、プレビューデプロイをそのコピーとして利用できます。本番環境のスナップショットをシードし、新しいスキーマをプッシュしてバックフィルを実行し、ゲートの状態を確認します。ゲートが成功してからのみ昇格させます。deploy-guard（ターゲットの分類）、migrate（任意項目から必須項目へ段階的に変更するパターン）、@convex-dev/migrations（バッチ処理に対応し、中断後に再開可能なバックフィル）を組み合わせます。

ワークフロー

0. 前提条件：プレビューデプロイには Preview Deploy Key（ダッシュボード → Project Settings → Deploy Keys → Preview）が必要です。--preview-create／--preview-name を使ったデプロイの前に、これを CONVEX_DEPLOY_KEY としてエクスポートしてください。通常の npx convex login セッションではプレビューを作成できず、この機能は有料プランでのみ利用できます。プレビューキーが利用できない場合は、スナップショットをシードした個人用開発デプロイでリハーサルし、その旨を明示してください。
1. ガード：deploy-guard を使って、読み取り元の SOURCE（本番環境）と、最終的に変更する TARGET（本番環境）を分類して明示します。本番環境への昇格について、あらかじめ明示的な最新の承認を得て、計画を確認してください。
2. 読み取り専用でソースデータのスナップショットを作成します：npx convex export --path snapshot.zip（実データを保持しているデプロイから実行します。移行でファイルを扱う場合にのみ --include-file-storage を追加します）。これは読み取り操作であり、何も変更しません。
3. 変更前のコードからプレビューを作成します。スナップショットのデータがすでに適合しているスキーマでプレビューを開始できるよう、schema.ts を編集する前に実行してください：npx convex deploy --preview-create migrate-<slug>（プレビューキーが必要です。プレビューは約5日後に自動的に期限切れになります）。シードします：npx convex import snapshot.zip --deployment migrate-<slug>（--deployment を使うと名前でデプロイを指定します。import に --preview-name フラグはありません）。データがまだ古いスキーマに適合しているため、インポートは成功します。
4. migrate の順序に従ってプレビューでリハーサルします。各プッシュには npx convex deploy --preview-name migrate-<slug> を使います（データを保持したまま同じプレビューに再デプロイします。個人用開発環境を対象にする convex dev は使いません）：(a) 新規または変更したフィールドを任意項目にしてデプロイします。既存の行が適合しない場合、データ形状を示してコピー上でここでプッシュが失敗します。修正して再度プッシュし、成功するまで繰り返します。(b) @convex-dev/migrations のバックフィルを作成してプレビューに対して実行し、すべての行が有効になったことを確認します。(c) バリデーターを厳格化（必須項目への変更／ユニオンの範囲縮小）して再度デプロイします。バックフィルが実行済みのため、ゲートを通過します。
5. プレビューで検証します。移行後のデータに対してアプリの関数を実行し（プレビューを指定した MCP run／runOneoffQuery、またはスモーククエリを使用）、動作とデータ形状を確認します。
6. 手順1で得た明示的な最新の承認を得てからのみ昇格します。同じ手順（スキーマを任意項目にする → バックフィル → 必須項目にする）を本番環境に適用します。本番環境に近いデータでの実行にすでに成功しているため、本番環境でのプッシュは実証済みの実行を再現します。スナップショットをロールバック用の成果物として保管します（npx convex import snapshot.zip --replace --prod）。スナップショット作成後に書き込まれたデータは失われることを明確に伝え、昇格の作業時間を短く保ってください。
7. クリーンアップ：プレビューは自動的に期限切れになります。完了したらローカルのスナップショットを削除してください（実データが含まれているため、機密情報として扱い、絶対にコミットしないでください）。

ルール

• schema.ts を編集する前に、変更前のコードからプレビューを作成し、スナップショットをシードしてください。これによりインポートが適合し、変更をプッシュしたときに、本番環境ではなくコピー環境で適合性ゲートが失敗します。プレビューへのプッシュには毎回 deploy --preview-name を使い、インポート先は --deployment で指定します。
• 移行の順序を毎回守ってください：フィールドをオプションにする → プッシュ → バックフィル → 検証 → 制約を厳しくする → プッシュ。この「最初にオプションにする」手順を省くと、最初のプッシュで既存の行が拒否されます。
• 本番環境への昇格には、新たに明示的な承認（deploy-guard）が必要です。これは、新たな試行ではなく、検証済みのプレビュー実行を再現するものです。
• ロールバック用の成果物として、本番環境のスナップショットを保管してください。スナップショットの復元では、スナップショット作成後に書き込まれたデータが失われることを明記し、昇格の時間枠を短く保ってください。
• エクスポートしたスナップショットは、機密性の高い実データとして扱ってください。作業が終わったらローカルから削除し、絶対にコミットしないでください。
• バックフィルには、場当たり的にテーブル全体を対象とする一括ミューテーションではなく、@convex-dev/migrations（バッチ処理、再開可能、ドライラン可能）を使用してください。
• これはリハーサルしてから昇格するフローです。ライブデータを使わず、「オプションにしてから制約を厳しくする」方法だけを説明する場合は、migrate を参照してください。