API Geliştiricilerin Bilmesi Gereken PostgreSQL 19'ın Yeni Özellikleri

PostgreSQL 19; get-or-create uç noktaları için ON CONFLICT DO SELECT, replikalarda okuduğunu-yaz özelliği için WAIT FOR LSN, REPACK (CONCURRENTLY), COPY ile JSON çıktısı ve yükseltme yapmadan önce kontrol etmeniz gereken bir dizi varsayılan değişiklik getirmekte.

INEZA Felin-Michel

INEZA Felin-Michel

20 November 2026

API Geliştiricilerin Bilmesi Gereken PostgreSQL 19'ın Yeni Özellikleri

Kurumsal İçin Apidog

Şirket İçi (On-Premises) Dağıtım

SSO ve RBAC

SOC 2 Uyumlu

Apidog Enterprise'ı Keşfedin

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:

INSERT ON CONFLICT (email) DO SELECT RETURNING kullanan bir POST /users isteğinin akış şeması: çakışma yoksa satır eklenir ve döndürülür (201), çakışma varsa mevcut satır değiştirilmeden döndürülür (200)

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';
Sıra diyagramı: API sunucusu primary üzerinde bir UPDATE işlemi commit eder, pg_current_wal_insert_lsn 0/0306EE20 değerini okur, bunu oturuma kaydeder; ardından sonraki istekte read replikasına WAIT FOR LSN gönderir, başarı alır ve güncel satırı SELECT eder

Bir API'de önemli olan ayrıntılar:

  1. Modlar. Varsayılan MODE 'standby_replay', değişiklik uygulanana kadar bekler; read-your-writes için gereken tam olarak budur. standby_write, standby_flush ve primary_flush dayanıklılık kontrolleri içindir.
  2. Zaman aşımları. TIMEOUT verilmezse ya da TIMEOUT '0' olursa sonsuza kadar bekler. İstek yollarında her zaman bir timeout belirleyin.
  3. NO_THROW. Olmadan, bir zaman aşımı hata fırlatır ve transaction'ınızı iptal eder. İle birlikte success, timeout ya da not in recovery durumu alırsınız ve primary'ye düşebilirsiniz.
  4. Yerleşim. WAIT üst düzey bir komut olmalıdır; fonksiyonun ya da DO bloğ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

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.

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin