नयाPublication of @aurabase/aurabase-js v0.7.5 NPM Packages & Rust Crate v0.1.2चेंजलॉग देखें →

प्रदर्शन · 10 मिनट पढ़ा

PgBouncer लेनदेन पूलिंग की व्याख्या की गई

Affane Daylami · Fondateur · 12 जून 2026

ब्लॉग पर वापस जाएँ

PgBouncer का लेनदेन मोड प्रत्येक लेनदेन के अंत में PostgreSQL कनेक्शन जारी करता है, न कि तब जब क्लाइंट डिस्कनेक्ट हो जाता है। यह कुछ दर्जन वास्तविक सर्वर कनेक्शन के साथ हजारों HTTP क्लाइंट की सेवा करना संभव बनाता है, और यह किसी भी लघु-क्वेरी REST API के लिए अनुशंसित मोड है।

यह पृष्ठ स्वचालित रूप से अनुवादित किया गया था. अंग्रेजी संस्करण प्रामाणिक है.

इस लाभ की एक विशिष्ट लागत होती है: लेन-देन मोड चुपचाप उन सभी चीजों को तोड़ देता है जो एक अनुरोध से दूसरे अनुरोध तक स्थिर Postgres कनेक्शन मानता है। सत्र सेट, सुनें/सूचित करें, सलाहकार लॉक, कर्सर जो लेनदेन से बचे रहते हैं, तैयार विवरण नाम दिए गए हैं। यह आलेख तंत्र का विवरण देता है, इन सीमाओं को उनके सटीक लक्षणों के साथ सूचीबद्ध करता है, फिर दिखाता है कि उत्पादन में बैकएंड (हमारा, सीधे इसके भंडार में सत्यापित) इसे फंसने के बिना कैसे कॉन्फ़िगर करता है। यहां उद्धृत किसी भी प्रदर्शन आंकड़े के पीछे माप पद्धति के लिए, हमारी बेंचमार्क पद्धति देखें।

अनिवार्य है

  • लेन-देन मोड: सर्वर कनेक्शन प्रत्येक लेन-देन के अंत में जारी किया जाता है, न कि तब जब क्लाइंट डिस्कनेक्ट हो जाता है। लघु REST API प्रकार के कनेक्शन साझा करने के लिए यह सबसे कुशल तरीका है।
  • निर्माण द्वारा असंगत: सत्र सेट/रीसेट, सुनें/सूचित करें, सत्र सलाहकार लॉक, होल्ड कर्सर के साथ, एक अनुरोध से दूसरे अनुरोध में पुन: उपयोग की जाने वाली अस्थायी तालिकाएँ।
  • व्यवहार में सबसे आम नुकसान: नामित तैयार कथन, जो कई ड्राइवर (sqlx, asyncpg, JDBC pgjdbc ड्राइवर) डिफ़ॉल्ट रूप से सक्रिय होते हैं, एक अलग सर्वर कनेक्शन पर दोबारा चलाए जा सकते हैं और लोड के तहत prepared statement does not exist जैसी त्रुटि को ट्रिगर कर सकते हैं।
  • संस्करण 1.21 के बाद से, PgBouncer लेनदेन मोड (सर्वर कनेक्शन के माध्यम से एलआरयू कैश) में प्रोटोकॉल तैयार कथनों का पालन कर सकता है। यदि आपका एप्लिकेशन प्रत्येक अनुरोध पर search_path बदलता है तो यह क्लाइंट-साइड कैश को अक्षम करने से नहीं रोकता है।
  • Aurabase कोड में सत्यापित: किरायेदार पूल pool_mode=transaction में statement_cache_capacity(0) और PgBouncer के साथ चलते हैं, जबकि PostgREST स्वेच्छा से LISTEN/NOTIFY के माध्यम से अपने स्कीमा पुनः लोड करने के लिए सीधे कनेक्शन में रहता है।
#
अवधारणाओं

PgBouncer के 3 पूलिंग मोड

PgBouncer तीन मोड प्रदान करता है, जो केवल तभी भिन्न होता है जब Postgres सर्वर कनेक्शन सामान्य पूल में वापस आता है। आधिकारिक दस्तावेज में उनके नाम session, transaction और statement (pgbouncer.org/features.html, "पूलिंग मोड" अनुभाग, 24 अगस्त 2026 को एक्सेस किया गया) है।

पहनावासर्वर कनेक्शन ढीलासत्र अनुकूलता
सत्र (डिफ़ॉल्ट)क्लाइंट डिस्कनेक्शन परकुल: सेट करें, सुनें, कर्सर, सब कुछ लाइव की तरह काम करता है
लेन-देनप्रत्येक लेनदेन के अंत में (कमिट/रोलबैक)आंशिक: केवल वही जो लेन-देन में स्थानीय रहता है
कथनप्रत्येक व्यक्तिगत अनुरोध के बादन्यूनतम: स्पष्ट बहु-क्वेरी लेनदेन निषिद्ध है

सत्र मोड सबसे अनुमेय है लेकिन स्केलेबिलिटी में सबसे कम प्रभावी है: एक Postgres कनेक्शन क्लाइंट के लिए तब तक आरक्षित रहता है जब तक वह कनेक्ट रहता है, भले ही यह दो अनुरोधों के बीच कुछ भी नहीं करता है। स्टेटमेंट मोड बहुत विशिष्ट मामलों (केवल पढ़ने के लिए प्रॉक्सी, स्वास्थ्य-जाँच) के लिए आरक्षित है और यहां तक ​​कि क्लासिक स्पष्ट लेनदेन को भी तोड़ देता है। लेन-देन मोड वह समझौता है जो REST API के लिए व्यवहार में हावी है: प्रत्येक HTTP अनुरोध आम तौर पर एक छोटे Postgres लेन-देन से मेल खाता है।

#
तंत्र

लेनदेन मोड कैसे काम करता है, कनेक्शन दर कनेक्शन

लेन-देन मोड में, PgBouncer केवल तभी क्लाइंट से सर्वर कनेक्शन जोड़ता है जब क्लाइंट लेन-देन खोलता है, और COMMIT या ROLLBACK पर इसे पूल में वापस कर देता है। दो लेन-देन के बीच, एक ही क्लाइंट खुद को पूरी तरह से अलग सर्वर कनेक्शन पर पुनः असाइन किया हुआ पा सकता है।

सीधे तौर पर, 20 के default_pool_size के साथ, PgBouncer एक साथ कई सौ ग्राहकों को समाहित कर सकता है, जिनके पास किसी भी समय वास्तव में केवल कुछ ही लेनदेन प्रगति पर होते हैं। यह वह अनुपात है जो उच्च ट्रैफ़िक लेकिन कम लेनदेन वाले REST API के लिए लेनदेन मोड को उचित ठहराता है: दुर्लभ संसाधन (एक Postgres कनेक्शन, सर्वर साइड पर मेमोरी में महंगा) केवल आवश्यक समय के लिए ही लिया जाता है।

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)

यह अंतिम टिप्पणी सार प्रस्तुत करती है: लेनदेन मोड काम करता है क्योंकि यह जानबूझकर "मेरे एप्लिकेशन सत्र" और "मेरे Postgres कनेक्शन" के बीच के लिंक को तोड़ देता है। इस लिंक पर आधारित हर चीज़ टूट जाती है. अगला भाग सटीक रूप से क्या सूचीबद्ध करता है।

#
सीमाएं

लेन-देन पूलिंग मोड में क्या टूटता है?

आधिकारिक PgBouncer दस्तावेज़ स्पष्ट रूप से PostgreSQL सुविधाओं को सूचीबद्ध करता है जो एक ही क्लाइंट से दो अनुरोधों के बीच सर्वर कनेक्शन को पुन: चक्रित करते ही अपना अर्थ खो देते हैं।

प्रभावित कार्यक्षमताये क्यों टूटता हैविशिष्ट लक्षण
सेट / सेट सत्रसेटिंग ऐसे कनेक्शन पर लागू होती है जिसे तुरंत बाद पुनर्चक्रित किया जा सकता हैऐसा लगता है कि दो अनुरोधों के बीच एक पैरामीटर बेतरतीब ढंग से भूल गया है
सुनें/सूचित करेंसूचनाएं प्राप्त करने के लिए एक सतत कनेक्शन मानता हैग्राहक को कभी भी सूचित नहीं किया जाता, या केवल रुक-रुक कर
सत्र सलाहकार तालेलॉक सर्वर कनेक्शन द्वारा रखा जाता है, लॉजिकल क्लाइंट द्वारा नहींएक लॉक अपेक्षित पूर्णता से पहले रिलीज़ हो जाता है, या कभी रिलीज़ नहीं होता है
होल्ड स्लाइडर के साथइसे खोलने वाले लेन-देन से परे जीवित रहना चाहिएअगले पुनरावृत्ति पर "कर्सर मौजूद नहीं है" त्रुटि
अस्थायी टेबलPostgres सत्र से संबंधित, लेन-देन से नहींअगली क्वेरी पर तालिका "गायब" हो जाती है
नाम से तैयार बयानएक विशिष्ट सर्वर कनेक्शन पर तैयार किया गया, दूसरे पर दोबारा चलाया गयालोड के तहत "तैयार कथन ... मौजूद नहीं है"।
जाल हमेशा तत्काल नहीं होता

इनमें से अधिकांश सीमाएँ स्थानीय विकास में प्रकट नहीं होती हैं, जहाँ एक ही कनेक्शन आम तौर पर सभी ट्रैफ़िक को पूरा करता है। वे वास्तविक लोड के तहत दिखाई देते हैं, जब कई क्लाइंट वास्तव में पूल साझा करते हैं और एक सर्वर कनेक्शन वास्तव में एक ही तार्किक क्लाइंट से दो अनुरोधों के बीच हाथ बदलता है। धूम्रपान परीक्षण लगभग कभी भी उन्हें प्रकट नहीं करता है।

#
सामान्य जाल

तैयार किए गए कथन: सबसे गलत समझी जाने वाली सीमा

अधिकांश आधुनिक Postgres ड्राइवर, एप्लिकेशन कोड द्वारा स्पष्ट रूप से अनुरोध किए बिना, डिफ़ॉल्ट रूप से प्रोटोकॉल पक्ष पर नामित अनुरोध तैयार करते हैं। यही वह चीज़ है जिसके कारण इस जाल का अनुमान लगाना कठिन हो जाता है।

एक प्रोटोकॉल तैयार कथन को Parse के समय एक विशिष्ट सर्वर कनेक्शन पर नामित और कैश किया जाता है। लेन-देन मोड में, इस कनेक्शन को एक ही तार्किक क्लाइंट के दो अनुरोधों के बीच किसी अन्य क्लाइंट को पुन: असाइन किया जा सकता है। यदि ड्राइवर उसी स्टेटमेंट नाम को उस कनेक्शन पर दोबारा चलाता है जहां इसे कभी तैयार नहीं किया गया था, तो Postgres एक स्पष्ट त्रुटि के साथ प्रतिक्रिया करता है, आमतौर पर sqlx क्लाइंट के लिए prepared statement "sqlx_s_N" does not exist। व्यवहार रुक-रुक कर होता है: यह इस पर निर्भर करता है कि कनेक्शन लोड के तहत कैसा प्रदर्शन करता है, न कि प्रत्येक कॉल पर पुनरुत्पादित नियतात्मक बग पर।

भाषा की परवाह किए बिना क्लाइंट-साइड सुधार समान है: लेनदेन मोड में पूलर को पार करने वाले किसी भी पूल के लिए नामित तैयार कथनों के कैश को अक्षम करें, या अनाम प्रश्नों को बाध्य करें। sqlx के साथ Rust में, यह कनेक्शन विकल्पों पर statement_cache_capacity(0) से होकर गुजरता है।

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

// समतुल्य: asyncpg -> स्टेटमेंट_कैश_साइज़=0, pgjdbc -> तैयारथ्रेसहोल्ड=0

संस्करण 1.21 के बाद से, PgBouncer सर्वर साइड पर कुछ हद तक समस्या को कम करता है: यह लेनदेन मोड में प्रोटोकॉल तैयार किए गए कथनों का पालन कर सकता है और उन्हें निर्दिष्ट कनेक्शन पर तुरंत तैयार कर सकता है, प्रति कनेक्शन एक एलआरयू कैश के साथ जिसका आकार max_prepared_statements के माध्यम से समायोजित किया जाता है। यह चूक की संख्या को कम करता है, लेकिन यह आपको मल्टी-टेनेंट पूल में क्लाइंट कैश को अक्षम करने से छूट नहीं देता है जहां search_path एक अनुरोध से दूसरे अनुरोध में बदलता है: एक कैश्ड प्लान Parse के समय हल की गई तालिका के आंतरिक पहचानकर्ता (ओआईडी) को फ्रीज कर देता है, और इसे किसी अन्य स्कीमा के तहत दोबारा चलाने से एक साधारण त्रुटि के बजाय गलत किरायेदार से डेटा वापस आ सकता है।

#
कोड में चेक किया गया

Aurabase लेनदेन मोड में PgBouncer को कैसे कॉन्फ़िगर करता है

Aurabase रिपॉजिटरी साझा डेटा प्लेन (deploy/helm/aurabase/templates/infra/pgbouncer.yaml) के सामने PgBouncer को pool_mode=transaction के रूप में तैनात करता है, और एक किरायेदार (deploy/cnpg/tenant-pooler.yaml) के प्रत्येक समर्पित Postgres उदाहरण के सामने एक समान रूप से कॉन्फ़िगर किया गया Pooler CNPG तैनात करता है। दोनों रास्ते ऊपर वर्णित समान अनुशासन लागू करते हैं।

स्रोत कोड इस विकल्प के लिए एक विशिष्ट सुरक्षा कारण का दस्तावेजीकरण करता है, न कि केवल स्थिरता का कारण। किरायेदारों के बीच साझा किए गए Postgres पूल पुन: उपयोग किए गए कनेक्शन पर प्रति प्रोजेक्ट एक अलग search_path स्थिति में हैं। एक कैश्ड तैयार कथन Parse के समय हल की गई तालिका के OID को फ्रीज कर देता है; उसी कनेक्शन पर किसी अन्य किरायेदार के लिए इसे दोबारा चलाने से पहले किरायेदार की स्कीमा, एक अलगाव बाईपास के खिलाफ क्वेरी चलेगी, न कि केवल एक एप्लिकेशन त्रुटि। इसलिए statement_cache_capacity(0) को बिना किसी अपवाद के लागू किया जाता है, जिसमें समर्पित उदाहरण भी शामिल हैं जो लेनदेन मोड में CNPG पूलर से गुजरते हैं।

दूसरा सत्र स्वच्छता उपाय: जब प्रत्येक कनेक्शन पूल में लौटता है, तो एक हुक DISCARD ALL निष्पादित करता है (सेटिंग्स को रीसेट करना, सर्वर साइड पर तैयार कथनों को हटाना, सलाहकार लॉक जारी करना, कर्सर और अस्थायी तालिकाओं को शुद्ध करना)। इस हुक के बिना, पिछले अनुरोध द्वारा उत्पन्न सत्र अवशेष उसी पुनर्नवीनीकरण कनेक्शन का पुन: उपयोग करने वाले एक अलग किरायेदार से अगले अनुरोध पर लीक हो सकता है।

Exception accepted: dedicated PostgREST instances remain in direct connection to the primary, without going through the pooler. PostgREST schema reloading relies on LISTEN/NOTIFY, which assumes a persistent connection, exactly the functionality that transaction mode breaks (detail already documented in our article on PostgREST compatibility at Aurabase). RLS settings per request are passed to SET LOCAL within an explicit transaction, the only way to remain compatible with a pool that can change server connections at any COMMIT (see our article onmulti-tenant RLS isolation).

#
व्यावहारिक मार्गदर्शक

अपने एप्लिकेशन को तोड़े बिना लेनदेन मोड सक्षम करें

एक छोटी चेकलिस्ट, लेनदेन मोड में सीधे Postgres कनेक्शन से PgBouncer तक जाने वाले किसी भी बैकएंड पर लागू होती है।

  1. एप्लिकेशन कोड का ऑडिट करें। गैर-लेनदेन SET, LISTEN/NOTIFY, सत्र सलाहकार लॉक, WITH HOLD कर्सर और प्रश्नों के बीच पुन: उपयोग की जाने वाली अस्थायी तालिकाओं को देखें।
  2. एक स्पष्ट लेनदेन के भीतर सत्र सेट को स्थानीय सेट से बदलें। यह एकमात्र सेटिंग है जो कनेक्शन रीसाइक्लिंग से ठीक से बच जाती है, क्योंकि इसे अगले कनेक्शन पर लीक होने के बजाय COMMIT/रोलबैक पर साफ किया जाता है।
  3. यदि आपका पूल पूलर को पार करता है और स्कीमा या भूमिका एक अनुरोध से दूसरे अनुरोध में बदल जाती है, तो ड्राइवर-साइड तैयार स्टेटमेंट कैश को अक्षम करें। प्रदर्शन में लागत वास्तविक है लेकिन मापने योग्य है, और किरायेदारों के बीच रिसाव के जोखिम से बहुत कम है।
  4. उन कनेक्शनों को अलग करें जिनके लिए वास्तव में सत्र मोड (माइग्रेशन, एडमिन स्क्रिप्ट, कुछ भी जो LISTEN/NOTIFY पर निर्भर करता है) को अन्य सभी ट्रैफ़िक के लिए लेनदेन मोड को छोड़ने के बजाय सीधे गैर-पूलर कनेक्शन में अलग करें।
  5. आकार default_pool_size और max_client_conn Postgres'वास्तविक max_connections के सापेक्ष, किसी अन्य प्रोजेक्ट से कॉपी किए गए मनमाने आंकड़े द्वारा नहीं।
  6. वास्तविक भार के तहत परीक्षण करें, न कि केवल धूम्रपान परीक्षण। तैयार कथन त्रुटियां और सत्र सेटिंग्स लीक लगभग कभी भी एक स्थानीय कनेक्शन पर दिखाई नहीं देते हैं।
  7. उत्पादन में एक बार PgBouncer प्रशासन कंसोल से SHOW POOLS और SHOW STATS की निगरानी करें, ताकि क्लाइंट साइड पर दिखाई देने से पहले पूल संतृप्ति का पता लगाया जा सके।
#
फ़ैसला

क्या आपको हमेशा सत्र के बजाय लेनदेन मोड चुनना चाहिए?

नहीं, लेकिन अधिकांश REST API के लिए यह सही डिफ़ॉल्ट विकल्प है। सत्र मोड एक विरासत एप्लिकेशन के लिए बेहतर रहता है जो सत्र कार्यात्मकताओं पर अत्यधिक निर्भर होता है जिसे आप जल्दी से रिफैक्टर नहीं कर सकते हैं, या कम ट्रैफ़िक के लिए जहां पूलिंग लाभ माइग्रेशन प्रयास की भरपाई नहीं करता है।

PgBouncer इस पूलिंग मॉडल का एकमात्र कार्यान्वयन नहीं है: Supavisor (Supabase) और PgCat दो हालिया विकल्प हैं, जिनमें लोड वितरण और क्लस्टरिंग पर अलग-अलग ट्रेड-ऑफ हैं। अपनी टोपोलॉजी के आधार पर तीनों के बीच चयन करने के लिए हमारी विस्तृत तुलना, PgBouncer बनाम Supavisor बनाम PgCat देखें।

#
अक्सर पूछे जाने वाले प्रश्नों

पूछे जाने वाले प्रश्न

उत्पादन में लेन-देन मोड सक्रिय होने के बाद अक्सर जो प्रश्न सामने आते हैं।

PgBouncer लेनदेन पूलिंग मोड क्या है?+
यह PgBouncer (सत्र और कथन के साथ) के 3 तरीकों में से एक है जिसमें Postgres कनेक्शन प्रत्येक लेनदेन के अंत में किसी अन्य क्लाइंट को पुनः सौंपा जाता है, न कि जब क्लाइंट डिस्कनेक्ट करता है। इससे वास्तव में खुले Postgres कनेक्शनों की तुलना में कई अधिक प्रतिस्पर्धी ग्राहकों को सेवा प्रदान करना संभव हो जाता है।
मेरे तैयार किए गए विवरण लेनदेन मोड में क्रैश क्यों हो जाते हैं?+
एक नामित तैयार विवरण एक विशिष्ट सर्वर कनेक्शन पर तैयार किया जाता है। लेनदेन मोड में, इस कनेक्शन को दो अनुरोधों के बीच किसी अन्य क्लाइंट को पुनः सौंपा जा सकता है। यदि आपका ड्राइवर उस कनेक्शन पर स्टेटमेंट का नाम दोबारा चलाता है जहां इसे कभी तैयार नहीं किया गया है, तो Postgres एक त्रुटि देता है जैसे तैयार स्टेटमेंट मौजूद नहीं है। सुधार में ड्राइवर साइड पर तैयार स्टेटमेंट कैश को अक्षम करना शामिल है (स्टेटमेंट_कैश_कैपेसिटी(0) एसक्यूएलएक्स के साथ, स्टेटमेंट_कैश_साइज=0 एसिंकपीजी के साथ)।
क्या हम लेनदेन मोड में PgBouncer के पीछे LISTEN/NOTIFY का उपयोग कर सकते हैं?+
नहीं, विश्वसनीय रूप से नहीं. सुनें/सूचित करें सूचनाएं प्राप्त करने के लिए एक सतत कनेक्शन मानता है, जिसकी लेनदेन मोड गारंटी नहीं देता है। मानक अभ्यास उन घटकों को पारित करना है जो पूलर के बाहर, Postgres से सीधे कनेक्शन के माध्यम से सुनें/सूचित करें (उदाहरण के लिए PostgREST) पर निर्भर हैं।
क्या हमें लेनदेन मोड में SET के बजाय SET LOCAL का उपयोग करना चाहिए?+
हां, किसी भी सेटिंग के लिए व्यवस्थित रूप से जो किसी दिए गए अनुरोध पर लागू होनी चाहिए। SET LOCAL को COMMIT या ROLLBACK पर स्वचालित रूप से साफ़ किया जाता है, जिससे यह सर्वर कनेक्शन के साथ सुरक्षित हो जाता है जो दो लेनदेन के बीच बदल सकता है। एक क्लासिक SET अगले क्लाइंट तक लीक हो सकता है जो उसी पुनर्नवीनीकरण सर्वर कनेक्शन को पुनर्प्राप्त करता है।
क्या लेन-देन मोड पंक्ति स्तर सुरक्षा (RLS) के साथ काम करता है?+
हां, बशर्ते कि आपकी RLS नीतियों द्वारा उपयोग किए गए JWT दावे या सत्र चर लेनदेन के अंदर LOCAL SET में सेट हों, सत्र SET में नहीं। यह बहु-किरायेदार RLS अलगाव पर हमारे लेख में वर्णित पैटर्न है।
PgBouncer, Supavisor, PgCat: इनमें से किसे चुनना है?+
तीनों क्लस्टरिंग, लोड वितरण और पारिस्थितिकी तंत्र में अंतर के साथ एक समान पूलिंग मॉडल लागू करते हैं (Supavisor को Supabase द्वारा विकसित किया गया है, PgCat को Rust में लिखा गया है)। चुनाव सबसे पहले आपकी तैनाती टोपोलॉजी और आपकी मौजूदा परिचालन बाधाओं पर निर्भर करता है: विवरण के लिए हमारी समर्पित तुलना देखें।

तैनाती के लिए तैयार हैं?

पाँच मिनट में आपका बैकएंड।

किसी क्रेडिट कार्ड की आवश्यकता नहीं · 500 एमबी निःशुल्क · 50,000 एमएयू