PgBouncer شرح تجميع المعاملات

يقدم PgBouncer ثلاثة أوضاع، والتي تختلف فقط عندما يعود اتصال خادم Postgres إلى التجمع المشترك. تسميها الوثائق الرسمية sessionو transaction و statement (pgbouncer.org/features.html، قسم "أوضاع التجميع"، تم الوصول إليه في 24 أغسطس 2026).

يعد وضع الجلسة هو الأكثر تساهلاً ولكنه الأقل فعالية في قابلية التوسع: يظل اتصال Postgres محجوزًا للعميل طالما ظل متصلاً، حتى لو لم يفعل شيئًا بين طلبين. يتم حجز وضع كشف الحساب لحالات محددة جدًا (وكيل للقراءة فقط، وفحوصات السلامة) وحتى كسر المعاملات الصريحة الكلاسيكية. وضع المعاملة هو الحل الوسط الذي يهيمن عمليًا على REST API: كل طلب HTTP يتوافق عمومًا مع معاملة Postgres قصيرة واحدة.

في وضع المعاملة، يقوم PgBouncer فقط بإرفاق اتصال الخادم بالعميل عندما يفتح الأخير معاملة، ويعيدها إلى المجمع عند الالتزام أو ROLLBACK. بين معاملتين، قد يجد نفس العميل نفسه قد تم إعادة تعيينه إلى اتصال خادم مختلف تمامًا.

بشكل ملموس، مع default_pool_size من 20، يمكن لـ PgBouncer استيعاب عدة مئات من العملاء المتزامنين الذين، في أي وقت، ليس لديهم سوى عدد قليل من المعاملات الجارية فعليًا. هذه هي النسبة التي تبرر وضع المعاملة لواجهة برمجة تطبيقات REST ذات حركة مرور عالية ولكن معاملات قصيرة: المورد النادر (اتصال Postgres، باهظ الثمن في الذاكرة من جانب الخادم) مشغول فقط للوقت الضروري تمامًا.

[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 الحديثة بإعداد الطلبات المسماة من جانب البروتوكول بشكل افتراضي، دون أن يطلبها رمز التطبيق صراحةً. وهذا بالضبط ما يجعل من الصعب توقع هذا الفخ.

تتم تسمية بيان البروتوكول المُعد وتخزينه مؤقتًا على اتصال خادم محدد، في وقت Parse. في وضع المعاملة، يمكن إعادة تعيين هذا الاتصال إلى عميل آخر بين طلبين من نفس العميل المنطقي. إذا أعاد برنامج التشغيل بعد ذلك تشغيل نفس اسم العبارة على اتصال لم يتم إعداده مطلقًا، فسيستجيب Postgres بخطأ صريح، عادةً prepared statement "sqlx_s_N" does not exist لعميل sqlx. السلوك متقطع: فهو يعتمد على كيفية أداء الاتصالات تحت الحمل، وليس على خطأ حتمي يمكن تكراره في كل مكالمة.

التصحيح من جانب العميل هو نفسه بغض النظر عن اللغة: قم بتعطيل ذاكرة التخزين المؤقت للبيانات المُجهزة المُسماة، أو فرض استعلامات غير مسماة، لأي تجمع يتقاطع مع مُجمّع في وضع المعاملة. في Rust مع sqlx، يمر عبر statement_cache_capacity(0) في خيارات الاتصال.

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

// المكافئات: asyncpg ->statement_cache_size=0، pgjdbc -> PreparationThreshold=0

منذ الإصدار 1.21، خفف PgBouncer جزءًا من المشكلة على جانب الخادم: يمكنه متابعة البيانات المعدة للبروتوكول في وضع المعاملة وإعدادها سريعًا على الاتصال المعين، باستخدام ذاكرة تخزين مؤقت LRU لكل اتصال يتم ضبط حجمها عبر max_prepared_statements. يؤدي هذا إلى تقليل عدد الأخطاء، لكنه لا يعفيك من تعطيل ذاكرة التخزين المؤقت للعميل في تجمع متعدد المستأجرين حيث يتغير search_path من طلب إلى آخر: تجمد الخطة المخزنة مؤقتًا المعرف الداخلي (OID) للجدول الذي تم حله في وقت Parse، وقد تؤدي إعادة تشغيله ضمن مخطط آخر إلى إرجاع بيانات من مستأجر خاطئ بدلاً من خطأ بسيط.

ينشر مستودع Aurabase PgBouncer كـ pool_mode=transaction أمام مستوى البيانات المشتركة (deploy/helm/aurabase/templates/infra/pgbouncer.yaml)، وPooler CNPG الذي تم تكوينه بشكل مماثل أمام كل مثيل Postgres مخصص للمستأجر (deploy/cnpg/tenant-pooler.yaml). يطبق كلا المسارين نفس الانضباط الموصوف أعلاه.

يوثق الكود المصدري سببًا أمنيًا محددًا لهذا الاختيار، وليس مجرد سبب استقرار. تجمعات Postgres المشتركة بين المستأجرين تضع search_path مختلفًا لكل مشروع على الاتصالات المعاد استخدامها. يقوم البيان المجهز المخزن مؤقتًا بتجميد معرف الكائن (OID) الخاص بالجدول الذي تم حله في وقت Parse؛ سيؤدي إعادة تشغيله لمستأجر آخر على نفس الاتصال إلى تشغيل الاستعلام مقابل مخطط المستأجر الأول، وهو تجاوز عزل، وليس مجرد خطأ في التطبيق. ولذلك يتم تطبيق statement_cache_capacity(0) بدون استثناء، بما في ذلك على المثيلات المخصصة التي تمر أيضًا عبر مجمع CNPG في وضع المعاملة.

الإجراء الصحي للجلسة الثانية: عندما يعود كل اتصال إلى التجمع، يتم تنفيذ خطاف DISCARD ALL (إعادة ضبط الإعدادات، وإلغاء تخصيص البيانات المعدة من جانب الخادم، وتحرير الأقفال الاستشارية، وتطهير المؤشرات والجداول المؤقتة). بدون هذا الخطاف، يمكن أن تتسرب بقايا الجلسة الناتجة عن طلب سابق عند الطلب التالي من مستأجر مختلف يعيد استخدام نفس الاتصال المعاد تدويره.

تم قبول الاستثناء: تظل مثيلات PostgREST المخصصة على اتصال مباشر بالمثيل الأساسي، دون المرور عبر المجمع. تعتمد إعادة تحميل مخطط PostgREST على LISTEN/NOTIFY، الذي يفترض وجود اتصال مستمر، وهو بالضبط الوظيفة التي يكسرها وضع المعاملة (التفاصيل موثقة بالفعل في مقالتنا عن توافق PostgREST في Aurabase). يتم تمرير إعدادات RLS لكل طلب إلى SET LOCAL ضمن معاملة صريحة، وهي الطريقة الوحيدة للبقاء متوافقة مع مجموعة يمكنها تغيير اتصالات الخادم في أي COMMIT (راجع مقالتنا حولعزل RLS متعدد المستأجرين).

قائمة مرجعية قصيرة تنطبق على أي واجهة خلفية تنتقل من اتصال Postgres المباشر إلى PgBouncer في وضع المعاملة.

1. تدقيق كود التطبيق. ابحث عن SETغير المتعلقة بالمعاملات، LISTEN/NOTIFY، الأقفال الاستشارية للجلسة، WITH HOLD المؤشرات والجداول المؤقتة المعاد استخدامها بين الاستعلامات.
2. استبدل مجموعات الجلسة بمجموعات المحلية ضمن معاملة صريحة. هذا هو الإعداد الوحيد الذي ينجو بشكل صحيح من إعادة تدوير الاتصال، لأنه يتم تنظيفه في COMMIT/ROLLBACK بدلاً من التسرب في الاتصال التالي.
3. قم بتعطيل ذاكرة التخزين المؤقت للبيانات المعدة من جانب برنامج التشغيل إذا كان مجموعتك تجتاز المجمع ويتغير المخطط أو الدور من طلب إلى آخر. إن تكلفة الأداء حقيقية ولكنها قابلة للقياس، وأقل بكثير من خطر التسرب بين المستأجرين.
4. عزل الاتصالات التي تحتاج بالفعل إلى وضع جلسة (عمليات الترحيل، البرامج النصية للمسؤول، أي شيء يعتمد على الاستماع/الإخطار) إلى اتصال مباشر غير مجمّع، بدلاً من التخلي عن وضع المعاملة لجميع حركات المرور الأخرى.
5. الحجم default_pool_size و max_client_conn نسبة إلى max_connectionsالفعلي لـ Postgres، وليس برقم عشوائي منسوخ من مشروع آخر.
6. اختبار تحت الحمل الحقيقي، وليس فقط اختبار الدخان. لا تظهر أخطاء البيانات المعدة وتسريبات إعدادات الجلسة أبدًا على اتصال محلي واحد.
7. قم بمراقبة SHOW POOLS وSHOW STATS من وحدة تحكم إدارة PgBouncer مرة واحدة في الإنتاج، لاكتشاف تشبع التجمع قبل أن يصبح مرئيًا على جانب العميل.

لا، ولكنه الخيار الافتراضي الصحيح للأغلبية العظمى من واجهات برمجة تطبيقات REST. يظل وضع الجلسة مفضلاً للتطبيق القديم الذي يعتمد بشكل كبير على وظائف الجلسة التي لا يمكنك إعادة هيكلتها بسرعة، أو لحركة المرور المنخفضة حيث لا يعوض كسب التجميع عن جهد الترحيل.

PgBouncer ليس التطبيق الوحيد لنموذج التجميع هذا أيضًا: Supavisor (Supabase) وPgCat هما بديلان حديثان، مع مقايضات مختلفة بشأن توزيع الأحمال والتجميع. راجع مقارنتنا التفصيلية، PgBouncer vs Supavisor vs PgCat، للاختيار من بين الثلاثة اعتمادًا على طوبولوجيتك.

الأسئلة التي تطرح في أغلب الأحيان بمجرد تنشيط وضع المعاملة في الإنتاج.