postgresql-docs

PostgreSQL ドキュメント

モデルが間違えやすい PostgreSQL 18 ドキュメントのルール：驚くべきデフォルト、ロックと並行性のトラップ、PostgreSQL 18 の変更点、およびドキュメントが推奨するパターン。各ルールの末尾に、それを裏付けるドキュメントの URL が付いています。

対象バージョン

参照は PostgreSQL 18 のドキュメント（マイナーリリース 18.6）に従います。18 からしか有効でない事実には「PostgreSQL 18」と記載します。まずサーバーバージョンを確認してください。古いサーバーでは、「PostgreSQL 18」と記載されたルールはすべて利用不可として扱ってください。

ナビゲーション方法

以下のテーブルから、タスクに必要な参照のみを読んでください。ソース：SOURCES.md。

クイックルール

1. PostgreSQL 18 では、キーワードなしの generated カラムは VIRTUAL（読み取り時に計算）になります。統計情報や論理レプリケーションには STORED と記述してください。 https://www.postgresql.org/docs/18/ddl-generated-columns.html https://www.postgresql.org/docs/18/sql-altertable.html
2. serial ではなく identity カラムを使用してください。identity カラムは NOT NULL ですが一意ではありません。PRIMARY KEY を追加してください。 https://www.postgresql.org/docs/18/ddl-identity-columns.html
3. 外部キーの参照側カラムには自分でインデックスを作成してください。PostgreSQL は参照される側のみにインデックスを作成します。 https://www.postgresql.org/docs/18/ddl-constraints.html
4. 単純な CREATE INDEX はビルド全体で書き込みをブロックします。ライブテーブルではトランザクションブロックの外で CREATE INDEX CONCURRENTLY を使用し、失敗した場合は残った INVALID インデックスを削除してください。 https://www.postgresql.org/docs/18/sql-createindex.html
5. 大きなテーブルへの制約追加は NOT VALID で行い、その後 VALIDATE CONSTRAINT を実行してください。これは書き込みをブロックしません。PostgreSQL 18 では NOT NULL に対してもこれが有効です。 https://www.postgresql.org/docs/18/sql-altertable.html
6. ADD COLUMN で揮発性のデフォルト値、STORED generated カラム、または identity を使用すると、テーブル全体が ACCESS EXCLUSIVE で書き換えられます。非揮発性のデフォルト値では書き換えは発生しません。 https://www.postgresql.org/docs/18/sql-altertable.html
7. マイグレーションセッションでは lock_timeout を設定し、statement_timeout、lock_timeout、transaction_timeout はロールまたはセッションごとに設定し、決してグローバルに設定しないでください。 https://www.postgresql.org/docs/18/runtime-config-client.html
8. アップサートは INSERT ... ON CONFLICT (cols) DO UPDATE を使用してください。これは READ COMMITTED では常に挿入または更新を並行して行います。MERGE は別のセッションが同じキーを挿入すると一意制約違反で失敗する可能性があります。 https://www.postgresql.org/docs/18/transaction-iso.html
9. SQLSTATE 40001 および 40P01 では、トランザクション全体を再試行してください。PostgreSQL は自動的には再試行しません。メッセージではなく SQLSTATE をテストしてください。 https://www.postgresql.org/docs/18/mvcc-serialization-failure-handling.html
10. デフォルトの分離レベルは READ COMMITTED です。各ステートメントは新しいスナップショットを参照します。複数行にわたるビジネスルールには SERIALIZABLE または明示的なロックが必要です。 https://www.postgresql.org/docs/18/transaction-iso.html https://www.postgresql.org/docs/18/applevel-consistency.html
11. ジョブキューには SELECT ... FOR UPDATE SKIP LOCKED を使用し、キーが変更されない場合は FOR NO KEY UPDATE を使用してください。 https://www.postgresql.org/docs/18/sql-select.html https://www.postgresql.org/docs/18/explicit-locking.html
12. リストまたはサブクエリに NULL が含まれる NOT IN は常に偽になります。count 以外の集計関数は、ゼロ行に対して NULL を返します。 https://www.postgresql.org/docs/18/functions-comparisons.html https://www.postgresql.org/docs/18/functions-aggregate.html
13. ページングと LIMIT には一意なキーによる ORDER BY が必要です。そうしないと実行ごとに結果が異なります。 https://www.postgresql.org/docs/18/queries-limit.html
14. 瞬間的な時刻は timestamptz として保存してください。TIMESTAMP '2004-10-19 10:23:54+02' はタイムゾーンのないタイムスタンプとなり、オフセットは無視されます。 https://www.postgresql.org/docs/18/datatype-datetime.html
15. now() はトランザクションの開始時刻です。実際の時刻が必要な場合は clock_timestamp() を使用してください。文字列リテラル 'now' をデフォルトに使用しないでください。 https://www.postgresql.org/docs/18/functions-datetime.html
16. jsonb を使用し、@> クエリには GIN (col jsonb_path_ops) でインデックスを作成してください。インデックスが使用されるためには、演算子がインデックス式に適用される必要があります。 https://www.postgresql.org/docs/18/datatype-json.html
17. PostgreSQL 18 では、gen_random_uuid() に加えて、時刻順の UUID を生成する uuidv7() が追加されました。 https://www.postgresql.org/docs/18/functions-uuid.html
18. PostgreSQL 18 の RETURNING は、INSERT、UPDATE、DELETE、MERGE で old.col と new.col を読み取れます。 https://www.postgresql.org/docs/18/dml-returning.html
19. EXPLAIN ANALYZE はステートメントを実行します。書き込み操作は BEGIN ... ROLLBACK でラップしてください。PostgreSQL 18 では BUFFERS が自動的に含まれます。 https://www.postgresql.org/docs/18/sql-explain.html https://www.postgresql.org/docs/18/using-explain.html
20. PostgreSQL 18 では、複数列 B-tree インデックスは先頭列なしでもクエリを処理できます（スキップスキャン）が、その先頭列の異なる値の数が少ない場合に限ります。 https://www.postgresql.org/docs/18/indexes-multicolumn.html
21. autovacuum は有効にしたままにし、VACUUM FULL は避けてください。autovacuum はパーティションテーブルや一時テーブルを分析しません。これらは自分で ANALYZE してください。 https://www.postgresql.org/docs/18/routine-vacuuming.html
22. 行レベルセキュリティは ENABLE ROW LEVEL SECURITY を実行するまで効果がなく、テーブル所有者は FORCE ROW LEVEL SECURITY がない限りこれをバイパスします。 https://www.postgresql.org/docs/18/ddl-rowsecurity.html
23. SECURITY DEFINER 関数では、SET search_path = trusted_schema, pg_temp を設定し、同じトランザクション内で PUBLIC に対する EXECUTE を取り消す必要があります。 https://www.postgresql.org/docs/18/sql-createfunction.html
24. テーブルへの権限付与は、それが使用するシーケンス（serial カラムのものを含む）には拡張されません。シーケンスの権限は個別に設定してください。 https://www.postgresql.org/docs/18/sql-grant.html
25. クライアントはデフォルトで sslmode=prefer を使用し、サーバーを検証しません。sslmode=verify-full を使用してください。 https://www.postgresql.org/docs/18/libpq-ssl.html
26. 動的 SQL は format('%I', ident) と値には EXECUTE ... USING を使用して構築し、連結は絶対に行わないでください。 https://www.postgresql.org/docs/18/plpgsql-statements.html
27. 全文検索の式インデックスは、2 引数の to_tsvector('english', col) を使用する必要があり、クエリでもその正確な形式を繰り返す必要があります。 https://www.postgresql.org/docs/18/textsearch-tables.html

参照

参照	読むべき時
schema-design.md	テーブル作成時：identity とシーケンス、generated カラム、制約、時間キー、ドメイン、スキーマと search_path、パーティショニング設計
migrations-and-locks.md	マイグレーション作成時：ALTER TABLE のロックレベルと書き換え、NOT VALID、同時インデックス構築、REINDEX、パーティションのアタッチとデタッチ
data-types.md	数値、テキスト、bytea、enum、UUID、配列、範囲型の選択、範囲に対する排他制約
datetime.md	タイムスタンプ、タイムゾーン、期間、extract、date_trunc、to_char、to_timestamp に関すること
json.md	JSONB の保存、クエリ、インデックス作成、更新、jsonpath、JSON_VALUE、JSON_TABLE、JSON 集計関数
queries.md	SELECT のロジック：NULL セマンティクス、結合、LATERAL、グループ化、集計、ウィンドウ関数、ページング、UNION、CTE
writes.md	INSERT ON CONFLICT、UPDATE と DELETE の結合、大きな変更のバッチ処理、RETURNING、MERGE、COPY、一括ロード
indexes.md	インデックスの選択またはレビュー：型、カラム順序、スキップスキャン、部分、式、INCLUDE、pattern_ops、GIN、BRIN
concurrency.md	分離レベル、再試行、行ロックとテーブルロック、デッドロック、アドバイザリロック、タイムアウト、LISTEN と NOTIFY
performance.md	EXPLAIN の読み方、統計情報と拡張統計情報、バキューム、メモリとプランナ設定、パラレルクエリ、pg_stat_statements
security.md	GRANT とデフォルト権限、ロール、行レベルセキュリティ、SECURITY DEFINER、パスワード、TLS と libpq 接続パラメータ
plpgsql-triggers.md	関数、PL/pgSQL、動的 SQL、例外、トリガー、プロシージャの作成
text-search.md	文字列関数、LIKE と正規表現、引用、tsvector による全文検索、ランキング、ts_headline

アップグレード時に注意すべき PostgreSQL 18 の変更点

• initdb はデフォルトでデータチェックサムを有効にし、pg_upgrade は設定が一致する必要があります。 https://www.postgresql.org/docs/18/release-18.html
• パーティションテーブルに対する VACUUM と ANALYZE は、そのパーティションも処理します。親のみを対象にするには ONLY を記述してください。 https://www.postgresql.org/docs/18/release-18.html
• pg_upgrade はプランナ統計情報を保持しますが、拡張統計情報は保持しません。 https://www.postgresql.org/docs/18/release-18.html
• AFTER トリガーは、イベントがキューに入れられたときにアクティブだったロールとして実行されます。 https://www.postgresql.org/docs/18/release-18.html
• 非同期 I/O（io_method、デフォルト worker）、および effective_io_concurrency のデフォルトは 16 です。 https://www.postgresql.org/docs/18/runtime-config-resource.html

古いパターン

古いパターン	現在のパターン
デフォルト値のリテラル 'now' または 'today'	now()、CURRENT_DATE (https://www.postgresql.org/docs/18/datatype-datetime.html)
MD5 パスワード、password 認証方式	scram-sha-256 (https://www.postgresql.org/docs/18/auth-password.html)