API geliştiricileri için en önemli PostgreSQL 19 yenilikleri: tek komutla get-or-create uçları için INSERT ... ON CONFLICT DO SELECT, replikalarda read-your-writes için WAIT FOR LSN, çevrimiçi şişkinlik temizliği için REPACK (CONCURRENTLY), COPY'den JSON çıktısı, yeni jsonpath string metotları ve toplu eklemelerde daha hızlı yabancı anahtar kontrolleri.
Bu rehber, handler'larınızda, replikalarınızda ve yükseltme planınızda nelerin değiştiğini ele alıyor. Her sözdizimi örneği PostgreSQL 19 sürüm notlarından ve referans sayfalarından alınmıştır.
PostgreSQL 19'daki yeniliklere hızlı bakış
PostgreSQL 19, açık kaynak veritabanının yıllık ana sürümüdür ve PostgreSQL Global Development Group tarafından 19 Kasım 2026'da duyuruldu. Get-or-create ekleme, read-your-writes için replika beklemesi, çevrimiçi tablo yeniden düzenleme, plan tavsiyesi ve sequence'ların mantıksal replikasyonunu ekliyor; ayrıca yükseltmeden önce kontrol etmeniz gereken birkaç varsayılanı değiştiriyor.
| Özellik | Neyin yerini alıyor | Farkını nerede hissedeceksiniz |
|---|---|---|
ON CONFLICT DO SELECT |
SELECT-sonra-INSERT yeniden deneme döngüleri | Idempotent POST ve kayıt uçları |
WAIT FOR LSN |
Okumaları primary'ye sabitleyen yönlendirme | Bir API'nin arkasındaki read replikaları |
REPACK (CONCURRENTLY) |
VACUUM FULL, CLUSTER, pg_repack |
Şişmiş sıcak tablolar, kesinti olmadan |
COPY ... (FORMAT json) |
Uygulama kodunda satır-JSON dönüşümü | Dışa aktarma ve toplu indirme uçları |
jsonpath string metotları |
Uygulama kodunda JSONB son işleme | JSON sütunlarını filtreleme ve normalleştirme |
pg_plan_advice + pg_stash_advice |
Planlayıcıyı yönlendirmek için sorgu yeniden yazma | Üretimdeki plan regresyonları |
FOR ALL SEQUENCES yayınları |
Geçiş sonrası manuel sequence sıfırlama | Mantıksal replikasyonla blue-green yükseltmeler |
Resmi sürüm duyurusu ayrıca paralel index vakumlama ve otomatik ölçeklenen async I/O worker'ları da listeliyor. Bunlar API'nizin gönderdiği SQL'i değiştirmediği için bu yazı onlara değinmiyor.
ON CONFLICT DO SELECT: tek komutla get-or-create
Her API'de, satır var olmasa da mutlaka geri döndürmesi gereken bir uç vardır: cihaz kaydetme, etiket oluşturma, idempotent checkout başlatma. 19 öncesi sürümlerde önce SELECT sonra INSERT çalıştırıyordunuz (yük altında yarışları kaybediyordunuz) ya da sadece RETURNING'in tetiklenmesi için sahte bir ON CONFLICT DO UPDATE yazıyordunuz ki bu da boşuna yeni bir satır sürümü yazıyordu.
PostgreSQL 19 dördüncü bir çakışma eylemi ekliyor. INSERT referansı buna "idempotent insert veya get or create" diyor:
INSERT INTO distributors (did, dname) VALUES (11, 'Global Electronics')
ON CONFLICT (did) DO SELECT
RETURNING *;
Eğer did = 11 boşsa, satır eklenir ve döndürülür. Doluysa, mevcut satır geri gelir ve hiçbir şey değiştirilmez. Dokümandaki üç kural:
DO SELECTile birRETURNINGifadesi zorunludur.DO UPDATEgibi birconflict_targetzorunludur.- Exclusion constraint'leri hakem olarak kullanılamaz; benzersiz bir index veya
NOT DEFERRABLEbenzersiz constraint kullanın.

Handler'ınız genellikle hangi dalın çalıştığını bilmek ister, böylece 201 Created ya da 200 OK yanıtını verebilir. Doküman, satır çakıştığında RETURNING'deki eski değerlerin non-NULL olduğunu belirtir; yani tek bir sütun size bunu söyler:
INSERT INTO users (email, name) VALUES ($1, $2)
ON CONFLICT (email) DO SELECT
RETURNING *, (old.id IS NULL) AS created;
İlgili tablolara dokunmadan önce mevcut satırı kilitlemeniz mi gerekiyor? Bir kilitleme ifadesi ekleyin: ON CONFLICT (did) DO SELECT FOR UPDATE RETURNING *. Ayrıca WHERE ile filtreleyebilirsiniz, örneğin DO SELECT WHERE d.dname != EXCLUDED.dname; yalnızca filtreyi geçen satırlar geri gelir.
Yetkiler: DO SELECT tablo üzerinde SELECT gerektirir; FOR UPDATE/FOR SHARE biçimleri ayrıca en az bir sütun üzerinde UPDATE gerektirir.
WAIT FOR LSN: replikalarda read-your-writes
Klasik replika hatası: kullanıcı profilini kaydeder, sonraki GET isteği değişikliği henüz uygulamamış asenkron bir replikaya düşer ve eski veri geri döner. Çoğu ekip yazmadan sonra okumaları primary'ye sabitler, bu da replikayı boşa çıkarır.
PostgreSQL 19, WAIT FOR komutunu ekliyor. Yazmadan sonra primary'nin WAL konumunu alın:
UPDATE movie SET genre = 'Dramatic' WHERE genre = 'Drama';
SELECT pg_current_wal_insert_lsn(); -- returns 0/0306EE20
Bu LSN'i kullanıcının oturumuna kaydedin (Simon Willison, yazısında imzalı bir çerez öneriyor). Sonraki istekte, okumadan önce replika üzerinde şunu çalıştırın:
WAIT FOR LSN '0/0306EE20' WITH (TIMEOUT '100ms', NO_THROW);
SELECT * FROM movie WHERE genre = 'Drama';

Bir API'de önemli olan ayrıntılar:
- Modlar. Varsayılan
MODE 'standby_replay', değişiklik uygulanana kadar bekler; read-your-writes için gereken tam olarak budur.standby_write,standby_flushveprimary_flushdayanıklılık kontrolleri içindir. - Zaman aşımları.
TIMEOUTverilmezse ya daTIMEOUT '0'olursa sonsuza kadar bekler. İstek yollarında her zaman bir timeout belirleyin. NO_THROW. Olmadan, bir zaman aşımı hata fırlatır ve transaction'ınızı iptal eder. İle birliktesuccess,timeoutya danot in recoverydurumu alırsınız ve primary'ye düşebilirsiniz.- Yerleşim.
WAITüst düzey bir komut olmalıdır; fonksiyonun ya daDObloğunun içinde olamaz. Transaction dışında ya da transaction'ın ilk komutu olarak, herhangi bir kilit almadan önce çalıştırın; aksi halde reddedilir.
REPACK (CONCURRENTLY), canlı tablolar için VACUUM FULL'ın yerini alıyor
Yoğun uçların arkasındaki tablolar, örneğin sessions ya da webhook_deliveries, hızla şişer. VACUUM FULL ve CLUSTER bunu düzeltir ama tabloyu kilitler. PostgreSQL 19 çevrimiçi bir seçenek ekliyor:
REPACK (CONCURRENTLY) webhook_deliveries;
REPACK (CONCURRENTLY, ANALYZE) orders USING INDEX orders_created_at_idx;
Sürüm notları, REPACK (CONCURRENTLY)'in alan geri kazandığını ve okuma/yazmaları engellemeden bir tabloyu bir index'e göre yeniden sıralayabileceğini söylüyor. VACUUM FULL ve CLUSTER uyumluluk için duruyor. İlerlemeyi yeni pg_stat_progress_repack görünümünden takip edin ve cluster'ı ayarlarken yeni max_repack_replication_slots sunucu ayarına göz atın.
COPY'den JSON çıktısı ve yeni jsonpath string metotları
Dışa aktarma uçları genellikle satırları JSON'a çevirmek için uygulama kodundan geçirir. COPY TO artık bunu veritabanında yapabiliyor; bkz. COPY referansı:
COPY (SELECT * FROM (VALUES(1),(2)) val(id)) TO STDOUT (FORMAT JSON, FORCE_ARRAY);
Bu, ayrı satırlarda [, {"id":1}, ,{"id":2} ve ] yazdırır; yani çıktı tek bir geçerli JSON dizisidir. FORCE_ARRAY olmadan her satırda bir JSON nesnesi alırsınız, bu da NDJSON dostudur. SQL NULL, JSON null olur ve json formatı yalnızca COPY TO ile çalışır.
JSONB sütunları için jsonpath string metotları kazanıyor: lower(), upper(), initcap(), ltrim(), rtrim(), btrim(), replace() ve split_part(). Doküman şunu gösteriyor:
jsonb_path_query('"TOM"', '$.lower()') -- "tom"
jsonb_path_query('" hello "', '$.btrim()') -- "hello"
jsonb_path_query('"abc,def,ghi,jkl"', '$.split_part(",", 3)') -- "ghi"
Sürüm notları bunları immutable olarak işaretliyor; bu metotlar bir JSONB alanını (boşluklarını kırpmak, küçük harfe çevirmek, bölmek gibi) handler'ınızda değil, sorgunun içinde normalleştirmenizi sağlıyor.
Ayrıca, sıfır satır üzerinde json_array() artık NULL yerine [] döndürüyor; bu, null kontrolü yapan bir istemciyi bozabilir.
API ekiplerinin bilmesi gereken diğer PostgreSQL 19 değişiklikleri
- Daha hızlı yabancı anahtar kontrolleri. Duyuruya göre testlerde toplu eklemeler neredeyse 2 kat hızlandı. Alt satırlar yazan içe aktarma uçları için faydalı.
- Plan tavsiyesi.
pg_plan_adviceeklentisi planlayıcı seçimlerini sabitler,pg_stash_adviceise bu tavsiyeyi sorgu kimliğine göre uygular; böylece yeniden dağıtım yapmadan regrede olmuş bir sorguyu düzeltebilirsiniz. - UUID ve encoding.
byteaileuuidarasında cast yapabilirsiniz;encode()/decode()yollarda ve token'lardaki kimlikler için URL-güvenli format olanbase64url'yi destekliyor. - Yükseltmeler için mantıksal replikasyon.
CREATE PUBLICATION all_sequences FOR ALL SEQUENCES;sequence'ları senkronize eder veFOR ALL TABLES EXCEPT (TABLE users, departments)tabloları hariç tutar. Bu, blue-green migrasyonlarındaki "geçiş sonrası kimlikler çakışıyor" açığını kapatır.
Yükseltmeden önce kontrol etmeniz gereken kırıcı değişiklikler
Sürüm notlarının migrasyon bölümü, staging'de tek bir sorgu bile başarısız olmadan bir API'yi vurabilen değişiklikleri listeliyor:
| PostgreSQL 19'daki değişiklik | Neyi kontrol etmelisiniz |
|---|---|
max_locks_per_transaction varsayılanı 64'ten 128'e çıktı; mevcut ayarlar iki katına çıkarılmalı |
Yapılandırmanızdaki ya da yönetilen servisin parametre grubundaki özel değerler |
| JIT varsayılan olarak devre dışı | Uzun sorgular için JIT'e güvenen analiz uçları |
Varsayılan TOAST sıkıştırması pglz'den lz4'e |
Hiçbir şey bozulmaz ama depolama ve CPU profili değişir |
standard_conforming_strings zorla on |
Bu ayar off iken alınan eski dump'lar geri yüklenemez |
| MD5 şifre kimlik doğrulaması uyarı loglar; RADIUS kaldırıldı | Uygulama rollerini SCRAM-SHA-256'ya taşıyın |
Sıfır satırda json_array() [] döndürür |
null testi yapan istemciler |
READ ONLY, postgres_fdw'ya aktarılıyor |
Foreign table üzerinden yazan salt okunur transaction'lar |
log_lock_waits varsayılan olarak açık |
Log hacmi ve alarm gürültüsü |
Önceki herhangi bir ana sürümden yükseltmek hâlâ pg_upgrade, pg_dumpall ile dump ve restore ya da mantıksal replikasyon gerektirir. PostgreSQL 14 kullanıyorsanız geçişi şimdiden planlayın: sürüm politikasına göre son sürümü 12 Kasım 2026'da çıktı.
Yükseltmeden sonra API'nizi Apidog CLI ile kodlama agent'ınıza regresyon testi yaptırın
Bir Postgres ana sürüm yükseltmesi nadiren SQL sözdizimini bozar. Davranışı bozar: [] döndüren bir json_array(), bir kilit sınırı, daha yavaş bir plan. API'nizin test senaryolarını bir PostgreSQL 19 staging veritabanına karşı çalıştırıp hem HTTP yanıtını hem de arkasındaki satırları doğrulayarak yakalayın. Bunu kodlama agent'ınıza Apidog CLI ile yaptırın.
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Sonra agent'ınıza tek bir komut verin:
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 payload şemasını okur, doğrular, test case'ini oluşturur ve ardından veritabanı bağlantı dosyanızla senaryoyu çalıştırır; böylece veritabanı adımları yeni cluster'a yönelir:
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'un veritabanı işlemleri Free planda PostgreSQL'i destekler; böylece her istekten sonra tabloyu sorgulayıp get-or-create ucunun tam olarak bir satır yazdığını doğrulayabilirsiniz. Dokümanlar, API testlerinde veritabanı sorgularını ve CLI'dan veritabanı bağlantılarıyla senaryo çalıştırmayı anlatır. Aynı apidog run ... -r junit komutunu CI pipeline'ınıza ekleyin; sonraki her ara sürüm aynı kontrolü alır. Agent'ınızın Postgres'i doğrudan sorgulamasını tercih ederseniz PostgreSQL MCP sunucu rehberine bakın.
SSS
PostgreSQL 19 ne zaman yayınlandı? 19 Kasım 2026. PostgreSQL projesi her ana sürümü 5 yıl destekler; yani 19. sürüm 19 Kasım 2031'e kadar düzeltme alır.
ON CONFLICT DO SELECT bir upsert ile aynı mı? Hayır. DO UPDATE mevcut satırı değiştirir; DO SELECT ona dokunmadan döndürür. Get-or-create ve idempotent POST'lar için kullanın. Bir RETURNING ifadesi ve bir çakışma hedefi gerektirir.
WAIT FOR LSN primary üzerinde çalışır mı? Varsayılan standby_replay modu yalnızca recovery sırasındaki bir standby üzerinde çalışır. Primary üzerinde hata alırsınız ya da NO_THROW ile not in recovery. Primary üzerinde beklemeniz gerekiyorsa MODE 'primary_flush' kullanın.
PostgreSQL 18'den 19'a yerinde yükseltebilir miyim? Evet, pg_upgrade ile. Ayrıca dump-restore ya da mantıksal replikasyon kullanabilirsiniz; bu artık FOR ALL SEQUENCES ile sequence'ları da replike eder. Önce yukarıdaki kırıcı değişiklikler tablosunu inceleyin.
PostgreSQL 19, pg_repack'in yerini alıyor mu? Çoğu durumda evet. REPACK (CONCURRENTLY) şişkinliği geri kazanır ve okuma/yazmaları engellemeden tabloları index'e göre yeniden sıralar; ayrıca çekirdekte gelir.
