convex-backup

バックアップを取り、復元が機能することを確認する

バックアップには2つの段階がありますが、ほとんどの人が行うのは最初の段階だけです。バックアップを取得することと、実際に復元できることを確認することです。この機能では両方を行います。定期的なスナップショットのエクスポートを設定し、さらに RESTORE DRILL を実行して、データを使い捨てのプレビュー環境に実際に復元し、データが正常であることを検証します。このドリルでは、migrate-rehearse と同じプリミティブ（スナップショットのエクスポート → プレビューへのデプロイ → スナップショットのインポート）を再利用し、前向きな変更ではなく復旧に適用します。つまり、安全策を前提とせず、実際にテストします。

ワークフロー

1. ガード：deploy-guard を使って、バックアップ対象のデプロイを分類し、告知します（読み取り／エクスポートは安全です。ドリルの復元先は使い捨てのプレビュー環境であり、本番環境ではありません）。
2. スナップショットを取得します：npx convex export --path backup-<date>.zip（アプリでファイルを保存している場合は --include-file-storage を追加します）。これがバックアップ成果物です。実データとして慎重に扱ってください。
3. スケジュールを設定します（継続的な対策です）：データの変更頻度と許容できる損失量（RPO）に合わせた頻度を推奨します。たとえば、ユーザーが管理する永続ストレージに、CI／cron から npx convex export を毎日実行し、保持期間を設定します。Convex 独自のプラットフォームバックアップは存在しますが、これによりユーザーが所有するポータブルなコピーが追加されます。
4. RESTORE DRILL を実行します（ほとんど誰も行わない段階です。これが要点です）。 (a) 前提条件：Preview Deploy Key を CONVEX_DEPLOY_KEY として設定します（migrate-rehearse と同じ要件です。有料プランの機能です）。利用できない場合は、代わりに新しい個人用の開発デプロイを対象にドリルを行い、その旨を伝えます。 (b) 現在のコードから使い捨てのプレビュー環境を作成します：npx convex deploy --preview-create restore-drill-<date>。 (c) スナップショットをその環境に復元します：npx convex import backup-<date>.zip --deployment restore-drill-<date> --replace（インポートでは --deployment を使ってデプロイを名前で指定します。インポートに --preview-name はありません）。 (d) 復旧を検証します：復元されたデータを読み戻し（行数には MCP の tables、抜き取り確認には data／runOneoffQuery を使用します）、重要なテーブルが想定される行数で復元され、実際のレコードのサンプルもあることを確認します。「成功」しても行数が0件なら、ドリルは失敗です。利用できる場合は、ソースの行数と比較します。
5. ドリルの結果を明確に報告します：何をバックアップしたか、復元が実際に実行され検証されたか（または失敗した場合はその理由。実際の災害が起きる前に発見できるため、ドリルの失敗は最も価値のある成果です）、推奨するスケジュールと保持期間、復旧手順（本番環境に復元する正確なコマンド：npx convex import backup.zip --replace --prod。deploy-guard によるゲートがあり、スナップショット取得後に書き込まれたデータは失われる可能性があるという注意事項を明記します）。
6. 衛生管理：完了したらローカルのスナップショットのコピーを削除します（実データです）。ドリルのプレビュー環境は自動的に期限切れになります。バックアップファイルをコミットしてはいけません。

ルール

• 一度も復元したことがないバックアップは、バックアップではなく単なる期待にすぎません。エクスポートを取得するだけでなく、必ず復元ドリルを実行するか、実行を提案してください。
• ドリルでは、使い捨てのプレビュー環境（または開発環境）に復元します。本番環境には復元しません。復元先とバックアップ元は異なるデプロイでなければなりません。
• 復旧を仮定せず、検証してください。復元後の行数が0件ならドリルは失敗です。重要なテーブルの行数と実際のレコードのサンプルをソースと照合してください。
• ドリルの失敗は最も価値のある成果です。はっきりと伝えてください。実際の災害が起きる前にドリルを行う理由は、まさにそこにあります。
• スケジュールは RPO（許容できるデータ損失量）に合わせます。Convex のプラットフォームバックアップに加えて、ユーザーが所有するポータブルなコピーを保持期間とともに保管してください。
• スナップショットには実データが含まれており、慎重な取り扱いが必要です。完了したらローカルコピーを削除し、決してコミットしないでください。本番環境への復元手順は deploy-guard によるゲートを設け、スナップショット取得後に書き込まれたデータが失われる可能性があることを明記します。
• migrate-rehearse のスナップショットとプレビューの仕組みを共有しますが、目的は前向きな変更ではなく復旧です。前向きなスキーマ変更には migrate-rehearse を使います。