planetscale-vitess-safety-review

Vitess の安全性レビュー

目的

PlanetScale Vitess データベースのベストプラクティスを推奨します。本番環境での安全性、デプロイ可能性、可観測性、エージェントによる安全な自動化に重点を置いてください。変更は適用しないでください。

評価する主な安全機能

安全なマイグレーション

本番ブランチとステージングブランチで安全なマイグレーションが有効になっているか確認してください。

次の場合は、安全なマイグレーションを有効にすることを推奨してください。

• ブランチが本番トラフィックを受け取る。
• チームがデプロイリクエストを使わずに DDL を実行している。
• 保護されたブランチのワークフローがない。
• アプリケーションのスキーマが頻繁に変更されることが想定される。

トレードオフを説明してください。安全なマイグレーションを有効にすると、保護されたブランチでの直接の DDL が拒否され、スキーマ変更はデプロイリクエストを通じて行う必要があります。これは機能ですが、本番環境で直接 DDL を実行する運用に依存しているチームに影響する可能性があります。有効化は動作を変える変更として扱い、承認を必須としてください。

デプロイリクエスト

次の点を確認してください。

• スキーマ変更にデプロイリクエストを使用しているか。
• 管理者の承認が必要か。
• デプロイリクエストで、データ損失、競合、Lint エラー、外部キーの問題、文字セットの問題、シャードへの影響をレビューしているか。
• チームが切り替えを制御するためにゲート付きデプロイを使用しているか。
• 「すぐにデプロイ」が使われているか。また、ゲート付きデプロイ／リバートの形が失われることをチームが理解しているか。
• 長時間実行されるトランザクションによって、切り替えが定期的に遅延しているか。
• デプロイリクエストのイベントを Webhook 経由でサブスクライブしているか。

次を推奨してください。

• 本番環境のスキーマ変更にはデプロイリクエストを必須にする。
• 管理者が複数いる場合は、本番環境のデプロイリクエストに管理者の承認を必須にする。
• 管理者が 1 人の組織では、その管理者として動作するエージェントを管理者の承認で制限することはできません。デプロイリクエストを開いた管理者は、自分で承認することもできます。エージェントによる自己承認を防ぐには、エージェントに別のユーザーを割り当てるか、デプロイリクエストの承認権限を持たないサービス トークンを使用してください。
• マイグレーションが即時実行に安全であると確認され、ロールバックの方針に問題がない場合を除き、即時デプロイより通常の安全なデプロイを優先する。
• 切り替えのタイミングが重要な場合は、ゲート付きデプロイを使用する。
• 遅延した切り替えに対する「今すぐ強制切り替え」は、オペレーターが制御する操作として扱ってください。これは実行中のトランザクションを積極的に停止し、スキーマの切り替えを完了させます。使用前に、切り替えを妨げているワークロードとインシデントの状況を確認することを推奨してください。また、切り替えを妨げる事象が頻繁に起きることを理解し、受け入れている場合に限り、データベースレベルで積極的に切り替えるデフォルト設定を推奨してください。

スキーマのリバート

チームがリバート可能な期間を把握しているか、インシデント対応手順書にその情報が含まれているか確認してください。

次の内容を文書化することを推奨してください。

• 問題のあるスキーママイグレーションを特定する方法。
• サポート対象の期間内にリバートする方法。
• リバートを許可されている担当者。
• スキーマのリバートと同時にロールバックすべきアプリケーションのデプロイ。

ブランチ戦略

次のブランチ構成を推奨してください。

• main またはそれに相当する本番ブランチで、安全なマイグレーションを有効にする。
• 本番ブランチを基にした staging ブランチで、安全なマイグレーションを有効にする。
• ステージングブランチを基にした短期間の開発ブランチ。
• 適切な場合は、開発ブランチからステージングへ、次にステージングから本番環境へデプロイリクエストを送る。

承認なしにブランチを作成しないでください。

Query Insights

Insights を確認し、次の点を調べてください。

• 遅いクエリ。
• 読み取る行数が多すぎるクエリ。
• エラーが発生しているクエリ。
• インデックスの使用状況がよくないクエリ。
• シャーディングされたデータベースの場合、クエリパターンが関連する vindex を使用しているか、また、インデックスやルーティングの変更後に vindex の使用状況がどのように変わるか。
• 通常とは異なるクエリ量。
• SQL コメントタグの欠落。
• 組み込みメタデータまたは SQLCommenter タグが存在する場合のタグ別の内訳。ダッシュボードでの tag:key:value フィルタリング、およびプログラムから内訳を取得するための insights/tags と insights/tags/summaries API エンドポイント。
• デプロイとの相関データ。

Insights がクエリをアプリ、ルート、コントローラー、アクション、ジョブ、デプロイ SHA、機能に関連付けられるよう、アプリケーションのクエリタグ付けを有効にするか、改善することを推奨してください。

異常

現在および最近の異常を確認します。

以下を推奨します。

• branch.anomaly Webhook をチームのアラートまたは自動化システムに登録します。
• 異常ペイロードを、課題またはエージェントタスクを作成するトリアージワークフローに振り分けます。
• 異常をデプロイリクエスト、アプリケーションのデプロイ、クエリタグと関連付けます。
• 異常イベントからスキーマやコードの変更を自動適用しないでください。提案または PR の作成のみを行います。

スキーマの推奨事項

未対応のスキーマ推奨事項を確認します。

各推奨事項について、以下を記録します。

• 種類：インデックスの追加、冗長なインデックスの削除、プライマリキーの枯渇、未使用テーブル、旧式の文字セット／照合順序、その他。
• 影響を受けるテーブルとキースペース。
• 根拠となるクエリテレメトリ。
• DDL。
• 期待される利点。
• リスク。
• テスト計画。

実装方法として、以下を推奨します。

• 推奨事項をアプリケーションのマイグレーション、または PlanetScale のブランチスキーマ変更に変換します。
• デプロイリクエストを作成します。
• 生成された DDL とシャードへの影響を確認します。
• ブランチでベンチマークを実施するか、検証します。
• セーフマイグレーションを使用してデプロイします。
• デプロイ後に Insights と異常の状態を監視します。

推奨事項を直接適用しないでください。

バックアップと復元

バックアップ体制と復元手順書を確認します。

以下を推奨します。

• 自動バックアップが存在することを確認します。
• 定期的に、本番以外の環境で復元訓練を実施します。
• 復元先、RPO／RTO の想定、およびアプリケーションの切り替え計画を文書化します。
• シャーディングされたデータベースの場合は、シャードを考慮した復元の要件を文書化します。

シャーディングとキースペースの安全性

データベースがシャーディングされている場合は、以下を確認します。

• キースペースとシャード。
• Vschema。
• シャードをまたぐクエリパターン。
• スキーマのデプロイリクエストにシャードごとの影響が示されているか。
• クエリがシャードに適したアクセスパスを使用しているか。

エージェントによる安全なシャーディングレビューは、提案としてのみ推奨します。シャーディング、vschema の変更、ルーティングの変更を自動で行わないでください。

Vitess 向け Webhook の推奨事項

以下の Webhook を評価し、推奨します。

• branch.anomaly
• branch.primary_promoted
• branch.ready
• branch.sleeping
• cluster.storage
• keyspace.storage
• deploy_request.opened
• deploy_request.queued
• deploy_request.in_progress
• deploy_request.pending_cutover
• deploy_request.schema_applied
• deploy_request.errored
• deploy_request.reverted
• deploy_request.closed
• 顧客のデータベース用 Webhook API で利用可能な場合は branch.schema_recommendation

推奨する通知先：

• 異常、プライマリの昇格、ストレージ、デプロイエラーのアラート。
• デプロイリクエストのライフサイクルに関する Slack または内部通知。
• スキーマ推奨事項と異常のエージェント受付キュー。デフォルトでは PR のみを出力します。

出力

以下を返します。

• 現在の Vitess の安全性の状況。
• 不足している安全機能。
• 推奨ワークフロー。
• 推奨する Webhook 登録。
• スキーマ推奨事項のトリアージ表。
• デプロイの安全性に関するギャップ。
• 承認が必要な変更案。

最後に、以下の文を記載します。

“No Vitess changes have been applied.”