API開発者が知っておくべきPostgreSQL 19の新機能

PostgreSQL 19では、get-or-create系エンドポイントに使えるON CONFLICT DO SELECT、レプリカでのread-your-writesを実現するWAIT FOR LSN、REPACK (CONCURRENTLY)、COPYからのJSON出力などが追加されています。アップグレード前に確認しておくべきデフォルト設定の変更点の一覧も要チェックです。

INEZA Felin-Michel

INEZA Felin-Michel

20 11月 2026

API開発者が知っておくべきPostgreSQL 19の新機能

Apidog エンタープライズ

オンプレミスデプロイ

SSO & RBAC

SOC 2 準拠

Apidog Enterpriseを見る

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つのルールがあります:

INSERT ON CONFLICT (email) DO SELECT RETURNING を使った POST /users リクエストのフローチャート: コンフリクトなしの場合は行を挿入して返す (201)、コンフリクト時は既存の行をそのまま返す (200)

ハンドラーは通常、どちらの分岐が実行されたかを知る必要があります。それにより 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サーバーがプライマリ上でUPDATEをコミットし、pg_current_wal_insert_lsn 0/0306EE20 を読み取ってセッションに保存、次のリクエスト時に読み取りレプリカへ WAIT FOR LSN を送信し、成功を確認してから SELECT で最新の行を取得する

APIで重要な詳細は以下の通りです:

  1. モード。 デフォルトの MODE 'standby_replay' は変更が適用されるまで待機します。read-your-writesに必要なのはこれです。standby_write、standby_flush、primary_flush は耐久性チェック用に存在します。
  2. タイムアウト。 TIMEOUT がない場合、または TIMEOUT '0' の場合は無限に待機します。リクエストパスでは必ず設定してください。
  3. NO_THROW。 これがないと、タイムアウトでエラーが発生しトランザクションが中断されます。これを付けると、ステータスとして success、timeout、not in recovery が返され、プライマリへフォールバックできます。
  4. 配置。 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 の変更点

アップグレード前に確認すべき破壊的変更

リリースノートの移行セクションには、ステージング環境では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) は読み取りや書き込みをブロックせずに膨張を回収し、インデックスに従ってテーブルを再編成できます。しかもコアに同梱されています。

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる