superior-database

優れたデータベース設計

実際のデータストア、ワークロード、デプロイ環境に適した正確なデータ変更を行います。既存のマイグレーションツールと責任分界を維持し、エンジンの動作やリポジトリでの慣例を確認せずに、汎用的なデータベースの慣例を持ち込まないでください。

データの契約を明確にする

スキーマ、クエリ、マイグレーションを変更する前に、次の項目を確認します。

• データストアのエンジン、バージョン、トポロジー、および関連する拡張機能
• 正式なスキーマとマイグレーション履歴
• エンティティの所有者、識別子、リレーションシップ、テナントの境界
• 書き込み時と読み取り時に維持すべき不変条件
• 想定されるカーディナリティ、アクセスパターン、順序付け、保持期間
• アプリケーションのバージョン、ワーカー、レプリカ間の互換性期間
• データ量、トラフィックの特性、ロックへの許容度、復旧要件

本番環境の実効的な制約は、許可された非機密の証拠からのみ確認してください。ローカルのフィクスチャが、本番環境のデータ量、偏り、NULL 許容性、レガシー状態を表していると仮定しないでください。

スキーマとクエリを一緒に設計する

テーブル、コレクション、フィールド、リレーションシップ、インデックス、クエリ形式、ページネーション、保持動作を追加または変更する場合は、references/schema-query-and-index-design.mdを参照してください。

• エンジンとデプロイ方法が許す範囲で、永続的な不変条件をデータストアに組み込みます。
• ユーザーへのフィードバックにはアプリケーションのバリデーションを使用しますが、並行処理や別経路の書き込みに対する唯一の保護策として依存しないでください。
• フィルタリングされるすべてのフィールドにインデックスを付けるのではなく、実際の述語、結合、順序付け、一意性、カーディナリティに基づいてインデックスを選択します。
• NULL、照合順序、タイムゾーン、同値の場合の順序、空の集合に対するクエリの意味を確認します。
• 結果セットと書き込みバッチに上限を設け、隠れた全件スキャン、無制限のファンアウト、行ごとのクエリを避けます。

ワークロード上の負荷が実証され、整合性の責任者が明確でない限り、非正規化、パーティショニング、シャーディング、キャッシュの導入は行わないでください。

トランザクションの整合性を守る

関連する書き込み、並行アクター、レプリカ、キュー、キャッシュ、冪等性、サービスをまたぐワークフローに関わる作業では、references/transactions-and-consistency.mdを参照してください。

• 不変条件と、アトミックである必要がある正確な境界を定義します。
• データストアの保証を意図的に利用し、アプリケーションのリクエスト順序から直列化を推測しないでください。
• トランザクションは短く保ち、既存のアーキテクチャによって安全性が確認されていない限り、ロックを保持したままリモート呼び出しを行わないでください。
• 再試行可能な操作は冪等にし、トランザクションの再試行とビジネス操作の再実行を区別します。
• キャッシュの無効化、レプリカの遅延、イベントの公開を、明示的な整合性契約として扱います。

マイグレーションをデプロイとして計画する

本番環境に関わるスキーマ変更、制約の導入、型の変更、テーブルの再構築、バックフィル、データ修復、古い表現の削除については、references/safe-migrations-and-backfills.mdを参照してください。

• 複数のアプリケーションバージョンが共存する可能性がある場合は、互換性を優先した拡張、移行、検証、縮小の各フェーズを選びます。
• 実行前に、ロック、再構築、検証コスト、レプリケーションへの影響、障害からの復旧方法を特定します。
• 実用上可能な範囲で、バックフィルは範囲を限定し、状況を観測可能にし、中断後に再開でき、冪等となるようにします。
• 破壊的または不可逆な手順を実行する前に、検証方法とロールバックまたは前進復旧の動作を定義します。
• 明示的な許可と対象環境の指定なしに、本番マイグレーション、破壊的なクエリ、大規模なデータ修正、共有環境での負荷テストを実行しないでください。

マイグレーションファイルがローカルでコンパイルできても、本番環境で安全に実行できる証拠にはなりません。

結果を検証する

リポジトリに既存のデータベースとテストツールを使用します。変更の規模に応じて検証します。

• マイグレーションがサポート対象の以前の状態から適用され、意図したスキーマに到達することを確認します。
• ロールバックが保証されており、意味的に可能な場合は、ロールバックが機能することを確認します。
• 古いバージョンと新しいバージョンのアプリケーションが、互換性計画に従って動作することを確認します。
• 制約が無効な状態を拒否し、有効な既存データを保持することを確認します。
• 代表的なクエリが、安定した順序で正しい結果を返すことを確認します。
• パフォーマンスが対象範囲に含まれる場合は、代表的なデータ形状と規模を使って、クエリプランと実行時の挙動を確認します。
• バックフィルの件数、チェックポイント、エラー処理、再実行によって不変条件が保たれることを確認します。

実際に実行したコマンド、使用したデータストアとバージョン、対象としたデータ規模、検証していない条件を報告します。関連するエンジン、トポロジー、ワークロード、デプロイ順序についての根拠がない限り、ダウンタイムがゼロだと主張してはいけません。

スキルは必要な範囲に絞って組み合わせる

• 永続化に関するドメイン動作、API コントラクト、アプリケーションのオーケストレーションには、superior-logic を使用します。
• マイグレーション、統合、互換性、並行性に関するテスト設計が主な懸念事項である場合は、superior-testing を使用します。
• データの症状はあるものの、原因となる仕組みが不明な場合は、superior-debugging を使用します。
• 代表的なクエリ、容量、リソース、レイテンシの測定が主な懸念事項である場合は、superior-performance を使用します。
• レプリケーション、可用性、フェイルオーバー、バックアップ目標、復旧準備が主な懸念事項である場合は、superior-reliability を使用します。
• マイグレーションをアーティファクトの昇格、ロールアウト、ロールバックと調整する必要がある場合は、superior-delivery を使用します。
• テナント分離、安全でないクエリ構築、機密データの露出、悪用を想定したリソース制御には、superior-api-security を使用します。
• スキーマ、マイグレーション、復旧、運用手順の変更を検証した後は、superior-docs を使用します。

明示的に対象範囲に含まれていない限り、範囲を絞ったデータベースの変更を、データストアの置き換え、ORM の書き換え、インフラストラクチャのマイグレーションに拡大してはいけません。