postgresql

PostgreSQL

作業ルール

• 忠実性が重要な場合は、未加工のバイト列をバイト列のまま保持し、クエリ用には別途、解析済みの型を選択します。
• デプロイ済みのマイグレーションは不変として扱い、ロールアウト中に旧バージョンと新バージョンのアプリケーションが共存することを考慮します。
• データのロールバックには来歴情報が必要です。 移行先の値で行を選択すると、フォワードマイグレーションが変更していない行も選択される可能性があります。可逆性が必要な場合は、後続の書き込みに関する明示的なポリシーを定めたうえで、影響を受けた行の識別情報と元の値を保持します。復元したデータを、それを読み取るアプリケーションバージョンで検証します。
• ロックの継続時間とトランザクションの範囲を確認し、読み取り・変更・書き込みの処理を同時更新から保護します。
• インデックスの述語と NULL の意味を、すべての書き込み処理およびマイグレーションクエリに合わせます。
• 代表的なデータと実際の実行計画を使ってクエリの変更を測定し、データベース上の結果を使って不変条件を検証します。

データ型のデフォルト

用途	使用する型	避ける型
主キー	BIGINT GENERATED ALWAYS AS IDENTITY	SERIAL、BIGSERIAL
タイムスタンプ	TIMESTAMPTZ	TIMESTAMP（タイムゾーンが失われます）
テキスト	TEXT	制約が必要な場合を除く VARCHAR(n)
金額	NUMERIC(precision, scale)	MONEY、FLOAT
真偽値	NOT NULL DEFAULT を指定した BOOLEAN	NULL を許容する真偽値
JSON	JSONB	JSON（インデックスを作成できません）、テキスト形式の JSON
UUID	gen_random_uuid()（PG13 以降）	uuid-ossp 拡張機能
IP アドレス	INET / CIDR	テキスト
範囲	TSTZRANGE、INT4RANGE など	2 つのカラムの組み合わせ
未加工バイト列（ペイロードをそのまま保持）	BYTEA	JSONB、TEXT（どちらも再エンコードされます）

仕様で「未加工のレスポンスを記録する」とされている場合、バイト列の忠実な保持が求められます。これを実現できるテキスト型はありません。JSONB は再解析されるため、重要でない空白が除去され、オブジェクトのキーがソートされ、重複するキーは最後のものだけが残り、指数表記の数値（1e0 → 1）は書き換えられます（1.00 の末尾のゼロは保持されるため、「すべての数値表記が同一になる」と言うのは誇張です）。JSON 以外の本文は保存できず、通常は NULL になります。TEXT は NUL バイトと、データベースのエンコーディングで無効なバイト列を拒否するため、バイナリ形式または不正なエンコーディングの本文は保存されずにエラーになります。バイト列は BYTEA に保存し、その横にコンテンツタイプを保持します。クエリで必要な場合は、解析済みの JSONB カラムを別途追加します。カラムの型だけを根拠に本文が保持されていると判断するのは、レビュー上の誤りです。

検証

変更したクエリの調査は EXPLAIN から始めます。クエリの実行とその副作用が許可され、安全な場合に限り、代表的なデータを使って EXPLAIN (ANALYZE, BUFFERS) を実行します。書き込みの場合は使い捨てデータを優先します。関連するすべての作用がトランザクション対象である場合に限り、トランザクションを実行してからロールバックします。想定外のシーケンシャルスキャンを調査し、実際のコストを比較します。テーブルの大部分を読み取るには、インデックスを使うよりシーケンシャルスキャンのほうが効率的な場合があります。完了と判断する前に、インデックスのない外部キー列がないことを確認します。

タスク別の参考資料

実装またはレビューする動作に該当する参考資料を、作業前に読んでください。

• テーブル設計、制約、スキーマ変更、バックフィルについては、schema-and-migrations.md を参照してください。
• インデックス、クエリプラン、JSONB、ページネーション、クエリのアンチパターンについては、query-and-index-patterns.md を参照してください。
• RLS、トランザクション境界、ロック、パーティショニング、接続プーリング、運用機能については、security-and-operations.md を参照してください。

該当するトピックに応じて、以下の既存の専門的な参考資料も参照してください。

• operations.md。
• concurrency-patterns.md。
• full-text-search.md。
• performance-patterns.md。