API開発者にとって最も重要な PostgreSQL 19 の新機能: 1文で get-or-create エンドポイントを実現する INSERT ... ON CONFLICT DO SELECT、レプリカでの read-your-writes を可能にする WAIT FOR LSN、オンラインで膨張を解消する REPACK (CONCURRENTLY)、COPY からのJSON出力、新しい jsonpath 文字列メソッド、そして一括挿入時の外部キーチェックの高速化。
本ガイドでは、ハンドラー、レプリカ、アップグレード計画において何が変わるのかを解説します。すべての構文例は PostgreSQL 19 リリースノート およびリファレンスページから引用しています。
PostgreSQL 19 の新機能一覧
PostgreSQL 19 はオープンソースデータベースの年次メジャーリリースで、2026年11月19日に PostgreSQL Global Development Group から発表されました。get-or-create インサート、read-your-writes のためのレプリカ待機、オンラインテーブル再編成、プランアドバイス、シーケンスの論理レプリケーションが追加され、アップグレード前に確認すべきデフォルト設定がいくつか変更されています。
| 機能 | 置き換えるもの | 効果がある場所 |
|---|---|---|
ON CONFLICT DO SELECT |
SELECT後にINSERTするリトライループ | 冪等なPOSTやサインアップエンドポイント |
WAIT FOR LSN |
プライマリへの読み取り固定(スティッキールーティング) | APIの背後にある読み取りレプリカ |
REPACK (CONCURRENTLY) |
VACUUM FULL、CLUSTER、pg_repack |
膨張したホットテーブルのダウンタイムなしの解消 |
COPY ... (FORMAT json) |
アプリコードでの行からJSONへの変換 | エクスポート・一括ダウンロードエンドポイント |
jsonpath 文字列メソッド |
アプリコードでのJSONB後処理 | JSONカラムのフィルタリング・正規化 |
pg_plan_advice + pg_stash_advice |
プランナーを誘導するためのクエリ書き換え | 本番環境でのプラン退行 |
FOR ALL SEQUENCES パブリケーション |
切り替え後の手動シーケンスリセット | 論理レプリケーションによるブルーグリーンアップグレード |
公式リリース発表では、並列インデックスバキュームや自動スケーリングする非同期I/Oワーカーについても言及されています。これらはAPIが送信するSQLに影響しないため、本記事では割愛します。
ON CONFLICT DO SELECT: 1文で実現する get-or-create
すべてのAPIには、行が存在するかどうかにかかわらず返す必要のあるエンドポイントがあります。デバイスの登録、タグの作成、冪等なチェックアウトの開始などです。バージョン19以前では、SELECTを実行してからINSERTする(負荷下で競合が発生)、または RETURNING を機能させるためだけにダミーの ON CONFLICT DO UPDATE を書く(無意味に新しい行バージョンを書き込む)しかありませんでした。
PostgreSQL 19 では4つ目のコンフリクトアクションが追加されました。INSERT リファレンスではこれを「冪等な insert or get or create」と呼んでいます:
INSERT INTO distributors (did, dname) VALUES (11, 'Global Electronics')
ON CONFLICT (did) DO SELECT
RETURNING *;
did = 11 が空いていれば行が挿入されて返されます。すでに使われていれば既存の行が返され、何も変更されません。ドキュメントには3つのルールがあります:
DO SELECTにはRETURNING句が必要です。DO UPDATEと同様に、conflict_targetが必要です。- 排他制約はアービターとして機能できません。一意インデックスか
NOT DEFERRABLEの一意制約を使用してください。

ハンドラーは通常、どちらの分岐が実行されたかを知る必要があります。それにより 201 Created か 200 OK かを返し分けられるからです。ドキュメントには、行がコンフリクトした場合に RETURNING の old 値が非NULLになると記載されているため、1つのカラムで判別できます:
INSERT INTO users (email, name) VALUES ($1, $2)
ON CONFLICT (email) DO SELECT
RETURNING *, (old.id IS NULL) AS created;
関連テーブルに触れる前に既存の行をロックしたいですか?ロック句を追加します:ON CONFLICT (did) DO SELECT FOR UPDATE RETURNING *。WHERE でフィルタすることもできます。たとえば DO SELECT WHERE d.dname != EXCLUDED.dname のようにすると、条件を通過した行のみが返されます。
権限について:DO SELECT にはテーブルに対する SELECT 権限が必要で、FOR UPDATE/FOR SHARE 形式では少なくとも1カラムに対する UPDATE 権限も必要です。
WAIT FOR LSN: レプリカでの read-your-writes
レプリカの典型的なバグ: ユーザーがプロフィールを保存した直後、次のGETがまだ変更を再生していない非同期レプリカにヒットし、古いデータが返ってくる。ほとんどのチームは書き込み後に読み取りをプライマリへ固定しますが、それではレプリカが無駄になります。
PostgreSQL 19 では WAIT FOR コマンドが追加されました。書き込み後、プライマリのWAL位置を取得します:
UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama';
SELECT pg_current_wal_insert_lsn(); -- returns 0/0306EE20
そのLSNをユーザーのセッションに保存します(Simon Willison が彼の記事で署名付きクッキーを提案しています)。次のリクエスト時に、読み取りの前にレプリカで以下を実行します:
WAIT FOR LSN '0/0306EE20' WITH (TIMEOUT '100ms', NO_THROW);
SELECT * FROM movie WHERE genre = 'Drama';

APIで重要な詳細は以下の通りです:
- モード。 デフォルトの
MODE 'standby_replay'は変更が適用されるまで待機します。read-your-writesに必要なのはこれです。standby_write、standby_flush、primary_flushは耐久性チェック用に存在します。 - タイムアウト。
TIMEOUTがない場合、またはTIMEOUT '0'の場合は無限に待機します。リクエストパスでは必ず設定してください。 NO_THROW。 これがないと、タイムアウトでエラーが発生しトランザクションが中断されます。これを付けると、ステータスとしてsuccess、timeout、not in recoveryが返され、プライマリへフォールバックできます。- 配置。
WAITはトップレベルのコマンドである必要があり、関数内やDOブロック内では使えません。トランザクションの外で実行するか、トランザクションの最初の文として、ロックを取得する処理の前に実行してください。そうしないと拒否されます。
REPACK (CONCURRENTLY) が稼働中テーブルの VACUUM FULL を置き換え
sessions や webhook_deliveries のような、負荷の高いエンドポイントの背後にあるテーブルは急速に膨張します。VACUUM FULL や CLUSTER はこれを解決できますが、テーブルをロックしてしまいます。PostgreSQL 19 ではオンラインオプションが追加されました:
REPACK (CONCURRENTLY) webhook_deliveries;
REPACK (CONCURRENTLY, ANALYZE) orders USING INDEX orders_created_at_idx;
リリースノートによると、REPACK (CONCURRENTLY) は領域を回収し、読み取りや書き込みをブロックせずにインデックスに従ってテーブルを再編成できます。VACUUM FULL と CLUSTER は互換性のために残されています。進捗は新しい pg_stat_progress_repack ビューで確認でき、クラスタをチューニングする際は新しい max_repack_replication_slots サーバー設定に注目してください。
COPY からのJSON出力と新しい jsonpath 文字列メソッド
エクスポートエンドポイントでは、行をJSONに変換するためだけにアプリコードを通してストリーミングすることがよくあります。COPY リファレンスによると、COPY TO がデータベース内で直接これを行えるようになりました:
COPY (SELECT * FROM (VALUES(1),(2)) val(id)) TO STDOUT (FORMAT JSON, FORCE_ARRAY);
これは [、{"id":1}、,{"id":2}、] を別々の行に出力し、出力全体が1つの有効なJSON配列になります。FORCE_ARRAY がない場合は1行に1つのJSONオブジェクトが出力され、NDJSONに適した形式になります。SQLの NULL はJSONの null になり、json フォーマットは COPY TO でのみ動作します。
JSONBカラムについては、jsonpath に文字列メソッドが追加されました:lower()、upper()、initcap()、ltrim()、rtrim()、btrim()、replace()、split_part()。ドキュメントの例:
jsonb_path_query('"TOM"', '$.lower()') -- "tom"
jsonb_path_query('" hello "', '$.btrim()') -- "hello"
jsonb_path_query('"abc,def,ghi,jkl"', '$.split_part(",", 3)') -- "ghi"
リリースノートではこれらは immutable(不変)とされており、JSONBフィールドの正規化(トリム、小文字化、分割)をハンドラーではなくクエリ内で行えるようになります。
また、ゼロ行に対する json_array() は NULL ではなく [] を返すようになりました。これにより null をチェックしているクライアントが壊れる可能性があります。
APIチームが知っておくべきその他の PostgreSQL 19 の変更点
- 外部キーチェックの高速化。 発表によると、テストで一括挿入が約2倍高速化されたとのことです。子行を書き込むインポートエンドポイントに有効です。
- プランアドバイス。
pg_plan_advice拡張はプランナーの選択を固定し、pg_stash_adviceはクエリIDごとにそのアドバイスを適用します。これにより、再デプロイせずに退行したクエリを修正できます。 - UUIDとエンコーディング。
byteaとuuidの間でキャストでき、encode()/decode()がbase64url(パスやトークン内のIDに使われるURLセーフ形式)をサポートするようになりました。 - アップグレードのための論理レプリケーション。
CREATE PUBLICATION all_sequences FOR ALL SEQUENCES;でシーケンスが同期され、FOR ALL TABLES EXCEPT (TABLE users, departments)でテーブルを除外できます。これにより、ブルーグリーン移行における「切り替え後にIDが衝突する」という問題が解消されます。
アップグレード前に確認すべき破壊的変更
リリースノートの移行セクションには、ステージング環境では1つもクエリが失敗しないのにAPIに影響しうる変更が記載されています:
| PostgreSQL 19 での変更 | 確認すべきこと |
|---|---|
max_locks_per_transaction のデフォルトが64から128に変更、既存の設定値は2倍にする必要あり |
設定ファイルやマネージドサービスのパラメータグループ内のカスタム値 |
| JITがデフォルトで無効化 | 長時間クエリでJITに依存していたアナリティクス系エンドポイント |
デフォルトのTOAST圧縮が pglz から lz4 に変更 |
破損はないが、ストレージとCPUの特性が変化 |
standard_conforming_strings が強制的に on に |
off の状態で取得した古いダンプはリストア不可 |
| MD5パスワード認証が警告をログ出力、RADIUSは削除 | アプリ用ロールを SCRAM-SHA-256 へ移行 |
ゼロ行に対する json_array() が [] を返す |
null をテストしているクライアント |
READ ONLY が postgres_fdw に透過される |
外部テーブル経由で書き込みを行っていた読み取り専用トランザクション |
log_lock_waits がデフォルトでオン |
ログの量とアラートのノイズ |
それ以前のメジャーバージョンからのアップグレードには、引き続き pg_upgrade、pg_dumpall によるダンプ&リストア、または論理レプリケーションが必要です。PostgreSQL 14 をお使いの場合は、今のうちに移行を計画してください。バージョニングポリシーによると、PostgreSQL 14 の最終リリースは2026年11月12日です。
Apidog CLI でアップグレード後のAPIリグレッションテストをコーディングエージェントに任せる
Postgresのメジャーアップグレードで壊れるのは、SQL構文ではなく動作です。[] を返すようになった json_array()、ロック上限、遅くなった実行プランなど。PostgreSQL 19 のステージングデータベースに対してAPIのテストシナリオを実行し、HTTPレスポンスとその背後の行をアサートすることで検出できます。Apidog CLI を使えば、コーディングエージェントに任せられます。
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
その後、エージェントに次のプロンプトを1つ与えます:
In Apidog project <projectId>, add a test case for POST /users that sends the same
email twice and asserts the first call returns 201 and the second returns 200 with the
same id. Then run test scenario <scenarioId> against the pg19-staging environment with
database assertions, and summarize every failure next to the PostgreSQL 19 change
that could explain it.
エージェントはペイロードスキーマを読み取って検証し、テストケースを作成した後、データベース接続ファイルを指定してシナリオを実行するため、データベースステップは新しいクラスタにアクセスします:
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run -t <scenarioId> --project <projectId> -e <envId> \
--database-connection ./database-connections.json -r cli,junit
Apidog のデータベース操作はFreeプランでPostgreSQLをサポートしているため、各リクエスト後にテーブルをクエリし、get-or-createエンドポイントが正確に1行だけ書き込んだことをアサートできます。ドキュメントではAPIテストでのデータベースクエリやCLIからのデータベース接続を使ったシナリオ実行について解説しています。同じ apidog run ... -r junit コマンドをCIパイプラインに組み込めば、今後のマイナーリリースでも同じチェックが行われます。エージェントにPostgresへ直接クエリさせたい場合は、PostgreSQL MCPサーバーガイドをご覧ください。
FAQ
PostgreSQL 19 はいつリリースされましたか? 2026年11月19日です。PostgreSQLプロジェクトでは各メジャーバージョンを5年間サポートするため、バージョン19は2031年11月19日まで修正が提供されます。
ON CONFLICT DO SELECT はアップサートと同じですか? いいえ。DO UPDATE は既存の行を変更しますが、DO SELECT は変更せずにそのまま返します。get-or-create や冪等なPOSTに使用してください。RETURNING 句とコンフリクトターゲットが必要です。
WAIT FOR LSN はプライマリでも動作しますか? デフォルトの standby_replay モードは、リカバリ中のスタンバイでのみ動作します。プライマリではエラーになるか、NO_THROW を付けた場合は not in recovery が返されます。プライマリ自体で待機する必要がある場合は MODE 'primary_flush' を使用してください。
PostgreSQL 18 から 19 へインプレースアップグレードできますか? はい、pg_upgrade を使えば可能です。ダンプ&リストアや論理レプリケーションも利用でき、論理レプリケーションでは FOR ALL SEQUENCES によるシーケンスのレプリケーションが可能になりました。まずは上記の破壊的変更の表を確認してください。
PostgreSQL 19 は pg_repack を置き換えますか? ほとんどのケースでは、はい。REPACK (CONCURRENTLY) は読み取りや書き込みをブロックせずに膨張を回収し、インデックスに従ってテーブルを再編成できます。しかもコアに同梱されています。
