Fitur PostgreSQL 19 yang Paling Relevan untuk Pengembang API

Fitur-fitur baru PostgreSQL 19 yang paling relevan bagi pengembang API: INSERT ... ON CONFLICT DO SELECT untuk endpoint get-or-create dalam satu statement, WAIT FOR LSN untuk read-your-writes di replica, REPACK (CONCURRENTLY) untuk membersihkan bloat secara online, output JSON dari COPY, metode string jsonpath yang baru, dan pemeriksaan foreign key yang lebih cepat untuk bulk insert.

Coba Apidog hari ini

Panduan ini membahas apa saja yang berubah pada handler, replica, dan rencana upgrade Anda. Setiap contoh sintaks diambil dari catatan rilis PostgreSQL 19 dan halaman referensinya.

Sekilas fitur baru PostgreSQL 19

PostgreSQL 19 adalah rilis mayor tahunan dari database open source ini, yang diumumkan oleh PostgreSQL Global Development Group pada 19 November 2026. Versi ini menambahkan insert get-or-create, replica wait untuk read-your-writes, repack tabel secara online, plan advice, dan replikasi logis untuk sequence, serta mengubah beberapa nilai default yang sebaiknya Anda periksa sebelum melakukan upgrade.

Fitur Menggantikan apa Di mana efeknya terasa
ON CONFLICT DO SELECT Loop retry SELECT-then-INSERT Endpoint POST idempoten dan signup
WAIT FOR LSN Sticky routing pembacaan ke primary Read replica di belakang sebuah API
REPACK (CONCURRENTLY) VACUUM FULL, CLUSTER, pg_repack Tabel panas yang bloat, tanpa downtime
COPY ... (FORMAT json) Konversi baris ke JSON di kode aplikasi Endpoint ekspor dan bulk download
jsonpath metode string Post-processing JSONB di kode aplikasi Filtering dan normalisasi kolom JSON
pg_plan_advice + pg_stash_advice Menulis ulang query untuk mengarahkan planner Regresi rencana eksekusi di produksi
Publikasi FOR ALL SEQUENCES Reset sequence manual setelah cutover Upgrade blue-green via replikasi logis

Pengumuman rilis resmi juga menyebutkan vacuum index paralel dan auto-scaling worker async I/O. Keduanya tidak mengubah SQL yang dikirim API Anda, jadi tulisan ini melewatkannya.

ON CONFLICT DO SELECT: get-or-create dalam satu statement

Setiap API punya endpoint yang harus mengembalikan sebuah baris, baik baris itu sudah ada maupun belum: registrasi perangkat, membuat tag, atau memulai checkout idempoten. Sebelum versi 19, Anda menjalankan SELECT lalu INSERT (dan rentan kalah race saat beban tinggi), atau menulis ON CONFLICT DO UPDATE dummy hanya agar RETURNING terpicu—yang menulis versi baris baru tanpa alasan.

PostgreSQL 19 menambahkan aksi konflik keempat. Referensi INSERT menyebutnya sebagai "idempotent insert atau get or create":

INSERT INTO distributors (did, dname) VALUES (11, 'Global Electronics') ON CONFLICT (did) DO SELECT RETURNING *; 

Jika did = 11 masih kosong, baris tersebut diinsert dan dikembalikan. Jika sudah dipakai, baris yang sudah ada dikembalikan tanpa ada yang dimodifikasi. Tiga aturan dari dokumentasi:

  • Klausa RETURNING wajib ada saat menggunakan DO SELECT.
  • conflict_target wajib ada, sama seperti DO UPDATE.
  • Exclusion constraint tidak bisa menjadi arbiter; gunakan unique index atau unique constraint NOT DEFERRABLE.

Flowchart of a POST /users request using INSERT ON CONFLICT (email) DO SELECT RETURNING

Handler Anda biasanya perlu tahu cabang mana yang dijalankan, agar bisa menjawab 201 Created atau 200 OK. Dokumentasi mencatat bahwa nilai lama RETURNING tidak NULL ketika terjadi konflik, jadi satu kolom saja cukup untuk mengetahuinya:

INSERT INTO users (email, name) VALUES ($1, $2) ON CONFLICT (email) DO SELECT RETURNING *, (old.id IS NULL) AS created; 

Perlu mengunci baris yang sudah ada sebelum menyentuh tabel terkait? Tambahkan klausa locking: ON CONFLICT (did) DO SELECT FOR UPDATE RETURNING *. Anda juga bisa memfilter dengan WHERE, misalnya DO SELECT WHERE d.dname != EXCLUDED.dname, dan hanya baris yang lolos yang dikembalikan.

WAIT FOR LSN: read-your-writes di replica

Bug klasik pada replica: seorang pengguna menyimpan profilnya, GET berikutnya mengarah ke async replica yang belum mereplay perubahan tersebut, dan data lama yang dikembalikan. Sebagian besar tim melakukan pinning pembacaan ke primary setelah operasi tulis, yang berarti replica jadi sia-sia.

PostgreSQL 19 menambahkan perintah WAIT FOR. Setelah operasi tulis, ambil posisi WAL dari primary:

UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama'; SELECT pg_current_wal_insert_lsn(); -- returns 0/0306EE20 

Simpan LSN tersebut di sesi pengguna (Simon Willison menyarankan signed cookie dalam tulisan miliknya). Pada permintaan berikutnya, jalankan ini di replica sebelum membaca:

WAIT FOR LSN '0/0306EE20' WITH (TIMEOUT '100ms', NO_THROW); SELECT * FROM movie WHERE genre = 'Drama'; 

Sequence diagram: API server commits an UPDATE on the primary, reads pg_current_wal_insert_lsn

Detail-detail yang penting untuk API:

  1. Mode. Default MODE 'standby_replay' menunggu sampai perubahan diterapkan, inilah yang dibutuhkan untuk read-your-writes. standby_write, standby_flush dan primary_flush tersedia untuk pemeriksaan durability.
  2. Timeout. Tanpa TIMEOUT, atau dengan TIMEOUT '0', ia menunggu selamanya. Selalu tetapkan timeout di jalur permintaan.
  3. NO_THROW. Tanpa ini, timeout akan menimbulkan error dan membatalkan transaksi Anda. Dengan ini, Anda mendapatkan status success, timeout atau not in recovery, dan bisa fallback ke primary.
  4. Penempatan. WAIT harus berupa perintah top-level, bukan di dalam fungsi atau blok DO. Jalankan di luar transaksi atau sebagai statement pertama, sebelum apa pun yang mengambil lock, jika tidak perintah ini akan ditolak.

REPACK (CONCURRENTLY) menggantikan VACUUM FULL untuk tabel aktif

Tabel di belakang endpoint yang sibuk, seperti sessions atau webhook_deliveries, cepat mengalami bloat. VACUUM FULL dan CLUSTER bisa memperbaikinya tetapi mengunci tabel. PostgreSQL 19 menambahkan opsi online:

REPACK (CONCURRENTLY) webhook_deliveries; REPACK (CONCURRENTLY, ANALYZE) orders USING INDEX orders_created_at_idx; 

Catatan rilis menyatakan REPACK (CONCURRENTLY) mengklaim kembali ruang dan bisa menyusun ulang tabel berdasarkan index tanpa memblokir baca maupun tulis. VACUUM FULL dan CLUSTER tetap tersedia demi kompatibilitas. Pantau progresnya di view baru pg_stat_progress_repack, dan perhatikan pengaturan server baru max_repack_replication_slots saat men-tuning cluster.

Output JSON dari COPY dan metode string jsonpath baru

Endpoint ekspor sering mengalirkan baris melalui kode aplikasi hanya untuk mengubahnya menjadi JSON. Kini COPY TO bisa melakukannya langsung di database, sesuai referensi COPY:

COPY (SELECT * FROM (VALUES(1),(2)) val(id)) TO STDOUT (FORMAT JSON, FORCE_ARRAY); 

Perintah itu mencetak [, {"id":1}, ,{"id":2} dan ] di baris terpisah, sehingga hasilnya berupa satu array JSON yang valid. Tanpa FORCE_ARRAY, Anda mendapat satu objek JSON per baris, yang ramah NDJSON. SQL NULL menjadi JSON null, dan format json hanya bekerja dengan COPY TO.

Untuk kolom JSONB, jsonpath mendapat metode string baru: lower(), upper(), initcap(), ltrim(), rtrim(), btrim(), replace() dan split_part(). Dokumentasi menunjukkan:

jsonb_path_query('"TOM"', '$.lower()') -- "tom" jsonb_path_query('" hello "', '$.btrim()') -- "hello" jsonb_path_query('"abc,def,ghi,jkl"', '$.split_part(",", 3)') -- "ghi" 

Catatan rilis menandai metode-metode ini sebagai immutable, dan memungkinkan Anda menormalisasi field JSONB (trim, lowercase, split) langsung di dalam query alih-alih di handler.

Selain itu, json_array() atas nol baris kini mengembalikan [] alih-alih NULL, yang bisa merusak klien yang memeriksa null.

Perubahan PostgreSQL 19 lain yang perlu diketahui tim API

  • Pemeriksaan foreign key lebih cepat. Pengumuman resmi menyatakan bulk insert hampir 2x lebih cepat dalam pengujian mereka. Berguna untuk endpoint impor yang menulis baris anak.
  • Plan advice. Ekstensi pg_plan_advice mem-pin pilihan planner, dan pg_stash_advice menerapkan saran tersebut berdasarkan query ID, sehingga Anda bisa memperbaiki query yang mengalami regresi tanpa redeploy.
  • UUID dan encoding. Anda bisa melakukan cast antara bytea dan uuid, serta encode()/decode() mendukung base64url, format yang aman untuk URL guna ID di path dan token.
  • Replikasi logis untuk upgrade. CREATE PUBLICATION all_sequences FOR ALL SEQUENCES; menyinkronkan sequence, dan FOR ALL TABLES EXCEPT (TABLE users, departments) mengecualikan tabel. Ini menutup celah "ID bertabrakan setelah cutover" pada migrasi blue-green.

Perubahan yang merusak yang perlu diperiksa sebelum upgrade

Bagian migrasi pada catatan rilis mencantumkan perubahan yang bisa menimpa API tanpa satu pun query yang gagal di staging:

Perubahan di PostgreSQL 19 Yang perlu diperiksa
Default max_locks_per_transaction dari 64 menjadi 128, dan pengaturan yang sudah ada harus digandakan Nilai kustom di konfigurasi Anda atau parameter group layanan terkelola
JIT dinonaktifkan secara default Endpoint analitik yang mengandalkan JIT untuk query panjang
Kompresi TOAST default dari pglz ke lz4 Tidak ada yang rusak, tetapi profil penyimpanan dan CPU bergeser
standard_conforming_strings dipaksa on Dump lama yang dibuat dengan off tidak bisa direstore
Autentikasi password MD5 memunculkan peringatan; RADIUS dihapus Pindahkan role aplikasi ke SCRAM-SHA-256
json_array() pada nol baris mengembalikan [] Klien yang menguji null
READ ONLY diteruskan ke postgres_fdw Transaksi read-only yang menulis melalui foreign table
log_lock_waits aktif secara default Volume log dan kebisingan alert

Upgrade dari versi mayor sebelumnya tetap membutuhkan pg_upgrade, dump dan restore dengan pg_dumpall, atau replikasi logis. Rencanakan migrasinya sekarang jika Anda masih menggunakan PostgreSQL 14: sesuai kebijakan versioning, rilis terakhirnya adalah 12 November 2026.

Biarkan coding agent Anda melakukan regression test API setelah upgrade dengan Apidog CLI

Upgrade mayor Postgres jarang merusak sintaks SQL. Yang rusak adalah perilakunya: json_array() yang mengembalikan [], batas lock, atau rencana eksekusi yang lebih lambat. Tangkap masalah ini dengan menjalankan skenario pengujian API Anda terhadap database staging PostgreSQL 19, dengan assertion pada respons HTTP dan baris di baliknya. Biarkan coding agent Anda melakukannya dengan 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 

Lalu beri satu prompt kepada agent Anda:

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. 

Agent membaca schema payload, memvalidasinya, membuat test case, lalu menjalankan skenario dengan file koneksi database Anda sehingga langkah database mengarah ke cluster baru:

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 

Operasi database Apidog mendukung PostgreSQL di paket Free, sehingga Anda bisa melakukan query tabel setelah setiap request dan memastikan endpoint get-or-create menulis tepat satu baris. Dokumentasi menjelaskan query database dalam pengujian API dan menjalankan skenario dengan koneksi database dari CLI. Masukkan perintah apidog run ... -r junit yang sama ke pipeline CI Anda, dan setiap rilis minor berikutnya mendapat pemeriksaan yang sama. Jika Anda lebih suka membiarkan agent Anda melakukan query Postgres secara langsung, lihat panduan PostgreSQL MCP server.

FAQ

Kapan PostgreSQL 19 dirilis? 19 November 2026. Proyek PostgreSQL mendukung setiap versi mayor selama 5 tahun, jadi versi 19 mendapat perbaikan hingga 19 November 2031.

Apakah ON CONFLICT DO SELECT sama dengan upsert? Tidak. DO UPDATE mengubah baris yang sudah ada; DO SELECT mengembalikannya tanpa perubahan. Gunakan untuk get-or-create dan POST idempoten. Ia membutuhkan klausa RETURNING dan conflict target.

Apakah WAIT FOR LSN bekerja di primary? Mode default standby_replay hanya bekerja pada standby yang sedang recovery. Di primary Anda mendapatkan error, atau not in recovery dengan NO_THROW. Gunakan MODE 'primary_flush' jika Anda perlu menunggu di primary itu sendiri.

Bisakah saya upgrade dari PostgreSQL 18 ke 19 langsung di tempat? Bisa, dengan pg_upgrade. Anda juga bisa dump dan restore, atau menggunakan replikasi logis, yang kini mereplikasi sequence dengan FOR ALL SEQUENCES. Tinjau dulu tabel perubahan yang merusak di atas.

Apakah PostgreSQL 19 menggantikan pg_repack? Untuk sebagian besar kasus, ya. REPACK (CONCURRENTLY) mengklaim kembali bloat dan menyusun ulang tabel berdasarkan index tanpa memblokir baca atau tulis, dan tersedia di core.