YENİPublication of @aurabase/aurabase-js v0.7.5 NPM Packages & Rust Crate v0.1.2Değişiklik günlüğüne bakın →

Performans · 10 dk. okuma

PgBouncer işlem havuzunun açıklaması

Affane Daylami · Fondateur · 12 Haziran 2026

Bloga geri dön

PgBouncer'nin işlem modu, istemcinin bağlantısı kesildiğinde değil, her işlemin sonunda PostgreSQL bağlantısını serbest bırakır. This is what makes it possible to serve thousands of HTTP clients with a few dozen actual server connections, and it's the recommended mode for any short-query REST API.

Bu sayfa otomatik olarak çevrildi. İngilizce versiyonu yetkilidir.

This gain has a specific cost: transaction mode silently breaks everything that assumes a stable Postgres connection from one request to the next. Oturum SET'i, LISTEN/NOTIFY, danışma kilitleri, işlemde hayatta kalan imleçler, hazırlanmış ifadeler olarak adlandırılmıştır. This article details the mechanism, lists these limits with their exact symptoms, then shows how a backend in production (ours, verified directly in its repository) configures it without being trapped by it. Burada belirtilen performans rakamlarının ardındaki ölçüm yöntemi için kıyaslama metodolojimize bakın.

Temeller

  • İşlem modu: sunucu bağlantısı, istemcinin bağlantısı kesildiğinde değil, her işlemin sonunda kesilir. Bu, kısa REST API türü bağlantıları paylaşmak için en etkili moddur.
  • Incompatible by construction with: session SET/RESET, LISTEN/NOTIFY, session advisory locks, WITH HOLD cursors, temporary tables reused from one request to another.
  • The most common pitfall in practice: named prepared statements, which several drivers (sqlx, asyncpg, the JDBC pgjdbc driver) activate by default, can be replayed on a different server connection and trigger an error like prepared statement does not exist under load.
  • Sürüm 1.21'den bu yana, PgBouncer işlem modunda (sunucu bağlantısı aracılığıyla LRU önbelleği) protokolle hazırlanmış ifadeleri takip edebilir. Bu, uygulamanızın her istekte search_path değişmesi durumunda istemci tarafı önbelleğinin devre dışı bırakılmasını engellemez.
  • Verified in the Aurabase code: the tenant pools run with statement_cache_capacity(0) and PgBouncer in pool_mode=transaction, while PostgREST voluntarily remains in direct connection for its schema reloading via LISTEN/NOTIFY.
#
Kavramlar

PgBouncer'nin 3 havuzlama modu

PgBouncer üç mod sunar; bunlar yalnızca Postgres sunucu bağlantısı ortak havuza döndüğünde farklılık gösterir. Resmi belgeler bunları session, transaction ve statement olarak adlandırır (pgbouncer.org/features.html, "Havuzlandırma modları" bölümü, 24 Ağustos 2026'da erişildi).

ModaSunucu bağlantısı gevşekOturum uyumluluğu
oturum (varsayılan)İstemci bağlantısı kesildiğindeToplam: AYARLA, DİNLE, imleçler, her şey canlı gibi çalışıyor
işlemHer işlem sonunda (COMMIT/ROLLBACK)Kısmi: yalnızca işlemde yerel kalanlar
beyanHer bireysel istekten sonraMinimal: açık çoklu sorgu işlemleri yasaktır

Oturum modu, ölçeklenebilirlik açısından en izin veren ancak en az etkili olanıdır: Postgres bağlantısı, iki istek arasında hiçbir şey yapmasa bile, bağlı kaldığı sürece istemci için ayrılmış olarak kalır. İfade modu çok özel durumlar (salt okunur proxy, durum kontrolleri) için ayrılmıştır ve hatta klasik açık işlemleri bile keser. İşlem modu, bir REST API için pratikte hakim olan uzlaşmadır: her HTTP isteği genellikle tek bir kısa Postgres işlemine karşılık gelir.

#
Mekanizma

İşlem modu nasıl çalışır, bağlantıdan bağlantıya

İşlem modunda, PgBouncer yalnızca istemci bir işlem açtığında istemciye bir sunucu bağlantısı ekler ve COMMIT veya ROLLBACK sonrasında onu havuza döndürür. İki işlem arasında, aynı istemci kendisini tamamen farklı bir sunucu bağlantısına yeniden atanmış halde bulabilir.

Somut olarak, default_pool_size 20 ile PgBouncer, herhangi bir zamanda gerçekte yalnızca birkaç işlemi devam eden birkaç yüz eşzamanlı müşteriyi absorbe edebilir. Yüksek trafiğe sahip ancak kısa işlemlere sahip bir REST API için işlem modunu haklı çıkaran da bu orandır: nadir kaynak (sunucu tarafında bellek açısından pahalı olan bir Postgres bağlantısı) yalnızca kesinlikle gerekli olan süre boyunca kullanılır.

pgbouncer.iniini
[pgbouncer]
listen_port = 5432

; La connexion serveur est libérée dès la fin de chaque transaction
pool_mode = transaction

default_pool_size = 80
max_client_conn = 1000

; Ne pas utiliser avec des sessions stateful (SET, advisory locks, LISTEN/NOTIFY)

Bu son yorum ana fikri özetliyor: işlem modu çalışıyor çünkü "uygulama oturumum" ile "Postgres bağlantım" arasındaki bağlantıyı kasıtlı olarak kesiyor. Bu bağlantıya dayanan her şey bozulur. Bir sonraki bölüm tam olarak ne olduğunu listeliyor.

#
Sınırlar

İşlem havuzu modunda neler bozulur?

Resmi PgBouncer belgeleri, bir sunucu bağlantısı aynı istemciden gelen iki istek arasında geri dönüştürülebildiğinde anlamını yitiren PostgreSQL özelliklerini açıkça listeler.

Etkilenen işlevsellikNeden kırılıyorTipik semptom
SET / SET OTURUMUAyar, hemen geri dönüştürülebilecek bir bağlantı için geçerlidir.Bir parametre iki istek arasında rastgele unutulmuş gibi görünüyor
DİNLE / BİLDİRBildirimleri almak için kalıcı bir bağlantı olduğunu varsayarMüşteriye hiçbir zaman bildirimde bulunulmaz veya yalnızca aralıklı olarak
Oturum danışma kilitleriKilit mantıksal istemci tarafından değil sunucu bağlantısı tarafından tutulurBir kilit beklenen tamamlanmadan önce açılır veya hiç açılmaz
HOLD kaydırıcıları İLEOnu açan işlemin ötesinde hayatta kalmalısonraki yinelemede "imleç mevcut değil" hatası
Geçici tablolarİşlemle değil, Postgres oturumuyla ilgiliBir sonraki sorguda tablo "kayboluyor"
Adı geçen açıklamalar hazırlandıBelirli bir sunucu bağlantısında hazırlandı, başka bir sunucuda yeniden oynatıldıYük altında "hazırlanmış ifade ... mevcut değil"
Tuzak her zaman hemen gerçekleşmez

Bu sınırlamaların çoğu, tek bir bağlantının genellikle tüm trafiğe hizmet verdiği yerel geliştirmede kendini göstermez. Birkaç istemci havuzu paylaştığında ve bir sunucu bağlantısı aynı mantıksal istemciden gelen iki istek arasında gerçekten el değiştirdiğinde, gerçek yük altında görünürler. Bir duman testi bunları neredeyse hiçbir zaman ortaya çıkarmaz.

#
Ortak tuzak

Hazırlanan ifadeler: En çok yanlış anlaşılan sınır

Çoğu modern Postgres sürücüsü, uygulama kodu açıkça talep etmeden, varsayılan olarak protokol tarafında adlandırılmış istekler hazırlar. Bu tuzağı öngörmeyi zorlaştıran da tam olarak budur.

Protokol tarafından hazırlanan bir ifade, Parse zamanında belirli bir sunucu bağlantısında adlandırılır ve önbelleğe alınır. İşlem modunda, bu bağlantı aynı mantıksal istemciden gelen iki istek arasında başka bir istemciye yeniden atanabilir. Sürücü daha sonra aynı ifade adını hiç hazırlanmadığı bir bağlantıda yeniden yürütürse, Postgres açık bir hatayla yanıt verir, genellikle bir sqlx istemcisi için prepared statement "sqlx_s_N" does not exist. Davranış aralıklıdır: her çağrıda tekrarlanabilen deterministik bir hataya değil, bağlantıların yük altında nasıl performans gösterdiğine bağlıdır.

İstemci tarafı düzeltmesi, dile bakılmaksızın aynıdır: işlem modunda bir havuzlayıcıdan geçen herhangi bir havuz için adlandırılmış hazırlanmış ifadelerin önbelleğini devre dışı bırakın veya adsız sorguları zorlayın. Sqlx ile Rust'de bağlantı seçeneklerinde statement_cache_capacity(0) üzerinden geçer.

pool.rsrust
let connect_options = url
    .parse::<PgConnectOptions>()?
    .statement_cache_capacity(0);

// Eşdeğerler: asyncpg ->statement_cache_size=0, pgjdbc -> hazırThreshold=0

Sürüm 1.21'den bu yana, PgBouncer sunucu tarafındaki sorunun bir kısmını hafifletiyor: protokolle hazırlanmış ifadeleri işlem modunda takip edebilir ve bunları, boyutu max_prepared_statements aracılığıyla ayarlanan bağlantı başına bir LRU önbelleğiyle, atanmış bağlantıda anında hazırlayabilir. Bu, kaçırılanların sayısını azaltır, ancak search_path'nin bir istekten diğerine değiştiği çok kiracılı bir havuzdaki istemci önbelleğini devre dışı bırakmaktan sizi muaf tutmaz: önbelleğe alınmış bir plan, çözümlenen tablonun dahili tanımlayıcısını (OID) Parse zamanında dondurur ve başka bir şema altında yeniden oynatmak, basit bir hata yerine yanlış kiracıdan veri döndürebilir.

#
Giriş kodu

Aurabase, işlem modunda PgBouncer'yi nasıl yapılandırır?

Aurabase deposu, PgBouncer'yi paylaşılan veri düzleminin (deploy/helm/aurabase/templates/infra/pgbouncer.yaml) önünde pool_mode=transaction olarak ve kiracının her ayrılmış Postgres örneğinin (deploy/cnpg/tenant-pooler.yaml) önünde aynı şekilde yapılandırılmış bir Pooler CNPG dağıtır. Her iki yol da yukarıda açıklanan aynı disiplini uygular.

Kaynak kodu, bu seçimin yalnızca kararlılık nedenini değil, belirli bir güvenlik nedenini de belgeliyor. Kiracılar arasında paylaşılan Postgres havuzları, yeniden kullanılan bağlantılarda proje başına farklı bir search_path konumlandırır. Önbelleğe alınmış hazırlanmış bir ifade, çözümlenen tablonun OID'sini Parse zamanında dondurur; aynı bağlantıdaki başka bir kiracı için yeniden oynatmak, sorguyu yalnızca bir uygulama hatası değil, bir izolasyon atlaması olan ilk kiracının şemasına karşı çalıştırır. Bu nedenle statement_cache_capacity(0), işlem modunda bir CNPG Havuzlayıcıdan geçen özel örnekler de dahil olmak üzere istisnasız olarak uygulanır.

İkinci oturum hijyen önlemi: her bağlantı havuza geri döndüğünde, bir kanca DISCARD ALL komutunu çalıştırır (ayarların sıfırlanması, sunucu tarafında hazırlanmış ifadelerin yerinin değiştirilmesi, öneri kilitlerinin serbest bırakılması, imleçlerin ve geçici tabloların temizlenmesi). Bu kanca olmadan, önceki bir isteğin oluşturduğu oturum kalıntısı, aynı geri dönüştürülmüş bağlantıyı yeniden kullanan farklı bir kiracının sonraki isteğinde sızabilir.

İstisna kabul edildi: tahsis edilmiş PostgREST örnekleri, havuzlayıcıdan geçmeden birincil ile doğrudan bağlantıda kalır. PostgREST şemasının yeniden yüklenmesi, kalıcı bir bağlantı olduğunu varsayan LISTEN/NOTIFY öğesine dayanır; bu, tam olarak işlem modunun bozduğu işlevselliğe sahiptir (ayrıntı, PostgREST uyumluluğu hakkındaki makalemizde Aurabase adresinde zaten belgelenmiştir). İstek başına RLS ayarları açık bir işlem içinde SET LOCAL'ye iletilir; bu, herhangi bir COMMIT'de sunucu bağlantılarını değiştirebilen bir havuzla uyumlu kalmanın tek yoludur (çok kiracılı RLS yalıtımı hakkındaki makalemize bakın).

#
Pratik kılavuz

Uygulamanızı bozmadan işlem modunu etkinleştirin

Doğrudan bir Postgres bağlantısından işlem modunda bir PgBouncer bağlantısına geçen tüm arka uçlar için geçerli olan kısa bir kontrol listesi.

  1. Uygulama kodunu denetleyin. İşlem dışı SET, LISTEN/NOTIFY, oturum danışma kilitlerini, WITH HOLD imleçlerini ve sorgular arasında yeniden kullanılan geçici tabloları arayın.
  2. Oturum SET'lerini açık bir işlem içindeki YEREL SET'lerle değiştirin. Bu, bağlantı geri dönüşümünden düzgün şekilde kurtulan tek ayardır, çünkü bir sonraki bağlantıda sızıntı yapmak yerine COMMIT/ROLLBACK'te temizlenir.
  3. Havuzunuz havuzlayıcıdan geçiyorsa ve şema veya rol bir istekten diğerine değişiyorsa, sürücü tarafında hazırlanan ifadeler önbelleğini devre dışı bırakın. Performans maliyeti gerçektir ancak ölçülebilirdir ve kiracılar arasındaki sızıntı riskinden çok daha düşüktür.
  4. Gerçekten oturum moduna ihtiyaç duyan bağlantıları (geçişler, yönetici komut dosyaları, LISTEN/NOTIFY'ye bağlı olan herhangi bir şey), diğer tüm trafik için işlem modundan vazgeçmek yerine doğrudan havuzlayıcı olmayan bir bağlantıya ayırın.
  5. Boyut default_pool_size ve max_client_conn Postgres' gerçek max_connections'ye göre, başka bir projeden kopyalanan rastgele bir rakamla değil.
  6. Sadece duman testi değil, gerçek yük altında test yapın. Hazırlanan ifade hataları ve oturum ayarları sızıntıları neredeyse hiçbir zaman tek bir yerel bağlantıda görünmez.
  7. Üretimdeyken SHOW POOLS ve SHOW STATS'yi üretimdeyken PgBouncer yönetim konsolundan izleyerek havuz doygunluğunu istemci tarafında görünür hale gelmeden önce tespit edin.
#
Karar

Her zaman oturum yerine işlem modunu mu seçmelisiniz?

Hayır, ancak REST API'lerin büyük çoğunluğu için doğru varsayılan seçimdir. Oturum modu, hızlı bir şekilde yeniden düzenleyemeyeceğiniz oturum işlevlerine büyük ölçüde bağımlı olan eski bir uygulama için veya havuz kazancının geçiş çabasını telafi etmediği düşük trafik için tercih edilmeye devam eder.

PgBouncer bu havuzlama modelinin tek uygulaması da değildir: Supavisor (Supabase) ve PgCat yük dağıtımı ve kümelemede farklı ödünleşimlere sahip iki yeni alternatiftir. Topolojinize bağlı olarak üçü arasında seçim yapmak için ayrıntılı karşılaştırmamıza bakın, PgBouncer vs Supavisor vs PgCat.

#
Sıkça Sorulan Sorular

SSS

Üretimde işlem modu etkinleştirildiğinde en sık karşılaşılan sorular.

PgBouncer işlem havuzu modu nedir?+
This is one of the 3 modes of PgBouncer (with session and statement) in which the Postgres connection is reassigned to another client at the end of each transaction, rather than when the client disconnects. Bu, gerçekte açık olan Postgres bağlantılarından çok daha fazla sayıda rakip müşteriye hizmet verilmesini mümkün kılar.
Hazırladığım ekstreler neden işlem modunda çöküyor?+
Belirli bir sunucu bağlantısında adlandırılmış hazırlanmış bir ifade hazırlanır. İşlem modunda bu bağlantı, iki istek arasında başka bir istemciye yeniden atanabilir. If your driver replays the name of the statement on a connection where it has never been prepared, Postgres returns an error like prepared statement does not exist. The correction consists of disabling the prepared statements cache on the driver side (statement_cache_capacity(0) with sqlx, statement_cache_size=0 with asyncpg).
İşlem modunda PgBouncer arkasında LISTEN/NOTIFY kullanabilir miyiz?+
Hayır, güvenilir değil. LISTEN/NOTIFY, bildirimleri almak için kalıcı bir bağlantı olduğunu varsayar ve işlem modu bunu garanti etmez. Standard practice is to pass components that depend on LISTEN/NOTIFY (PostgREST, for example) through a direct connection to Postgres, outside the pooler.
İşlem modunda SET yerine SET LOCAL kullanmalı mıyız?+
Evet, belirli bir isteğe uygulanması gereken herhangi bir ayar için sistematik olarak. SET LOCAL, COMMIT veya ROLLBACK üzerinde otomatik olarak temizlenerek iki işlem arasında değişebilecek sunucu bağlantısı ile güvenli hale getirilir. Klasik bir SET, aynı geri dönüştürülmüş sunucu bağlantısını kurtaran bir sonraki istemciye sızıntı yapabilir.
İşlem modu Satır Düzeyinde Güvenlik (RLS) ile çalışıyor mu?+
Yes, provided that the JWT claims or session variables used by your RLS policies are set in LOCAL SET inside the transaction, not in session SET. Bu, çok kiracılı RLS izolasyonu hakkındaki makalemizde açıklanan kalıptır.
PgBouncer, Supavisor, PgCat: hangisini seçmelisiniz?+
The three implement a similar pooling model, with differences in clustering, load distribution and the ecosystem (Supavisor is developed by Supabase, PgCat is written in Rust). Seçim her şeyden önce dağıtım topolojinize ve mevcut operasyonel kısıtlamalarınıza bağlıdır: ayrıntılar için özel karşılaştırmamıza bakın.

DAĞITILMAYA HAZIR MISINIZ?

Beş dakika içinde arka ucunuz.

Kredi kartı gerekmez · 500 MB ücretsiz · 50.000 MAU