المستوى: متوسط إلى محترف — هذا المقال يفترض إنك بتشتغل على PostgreSQL في إنتاج وعندك خلفية أساسية بإعداد قاعدة البيانات وقراءة logs.

لو السيرفر بيتجمّد لما الاتصالات يوصلوا لـ 300 ومش قادر يخدم زبون جديد، PostgreSQL مش بطيء — كل اتصال بياكل بين 8 و 12MB رام، وفتح اتصال جديد بياخد 3 إلى 5ms في الـ handshake والـ authentication. PgBouncer بيخدم 10,000 عميل من 25 إلى 100 اتصال DB فقط، بدون لمس كود التطبيق.

PgBouncer: تخفيف ضغط الاتصالات على PostgreSQL بدون توسيع الهاردوير

المشكلة باختصار

PostgreSQL بيستخدم process مستقل لكل اتصال — مش thread خفيف. process معناها fork() جديد على مستوى الـ kernel، كومة ذاكرة منفصلة، file descriptors خاصة، وسجل في scheduler الـ Linux. على متوسط workload، الاتصال الخامل بياكل 8 إلى 12MB رام بدون ما ينفّذ أي query.

الإعداد الافتراضي max_connections = 100 مش رقم عشوائي — هو رقم معايرة محافظ. لما العدد ده يتعدّى، أي طلب جديد بيرجع بـ FATAL: sorry, too many clients already، وأسوأ من كده، الـ context switching بين 1000 process بياكل CPU في scheduling مش في تنفيذ queries.

الحل اللي معظم المطورين بيلجأوا له هو رفع max_connections لـ 1000 — وده غلط مكلف. عند 1000 اتصال خامل، PostgreSQL بيستهلك 10GB رام بدون أي طلب فعلي، والـ shared_buffers بتفقد مساحتها، والأداء بينهار قبل ما يتحسّن.

تخيّل الموضوع كأنه سوبر ماركت

قبل ما ندخل في التعريف العلمي، خد المثال ده عشان توصل الفكرة بسرعة:

متصوّر سوبر ماركت كبير فيه 100 ماكينة دفع. لو كل زبون يدخل المحل ياخد ماكينة خاصة بيه ويفضل ماسكها طول ما هو بيتسوّق ويتمشى ويفكّر — أول 100 زبون بس هيقدروا يدخلوا المحل، والباقي هيقفوا برة ينتظروا. ده اللي بيحصل في PostgreSQL بدون pooler.

دلوقتي تخيّل نفس المحل بنظام طوابير ذكي: الزبون يدخل، يتسوّق وهو حر، ولما يجي يدفع نظام الطابور بيوزّعه على أول ماكينة فاضية. الماكينة بتخدمه في 30 ثانية وترجع جاهزة لزبون تاني. نفس الـ 100 ماكينة دلوقتي تقدر تخدم آلاف الزبائن في الساعة، لأن وقت الإمساك الفعلي للماكينة قصير جداً مقارنة بوقت التسوّق.

هذا بالظبط دور Connection Pooling: طبقة وسيطة بتمسك مجموعة محدودة من الاتصالات الحقيقية مع PostgreSQL، وبتأجّر الاتصال للعميل في اللحظة اللي محتاج فيها يبعت query فعلي، وبترجعه للـ pool فور انتهائه. العميل ما يحسّش بفرق، لكن قاعدة البيانات بتشتغل على عدد processes أقل بكثير.

التعريف العلمي الدقيق

PgBouncer هو middleware خفيف (binary أقل من 1MB، single-threaded event-driven باستخدام libevent) بيقف بين التطبيق وPostgreSQL على بورت مختلف (افتراضياً 6432 بدل 5432). من جهة العميل بيقبل آلاف الاتصالات لأن كل اتصال معاه عبارة عن file descriptor + buffer صغير. من جهة الـ DB بيمسك pool محدود من اتصالات حقيقية ومعاد استخدامها.

التطبيق بيتصل بـ PgBouncer كأنه بيتصل بـ PostgreSQL مباشرة — نفس wire protocol، نفس الكود، نفس الـ driver. الفرق الوحيد: البورت اللي بيتصل عليه.

الأوضاع الثلاثة — الفرق بينهم متى يرجع الاتصال للـ pool

1. Session Mode: الاتصال بيرجع للـ pool لما العميل يقفل الـ session بالكامل. ده الوضع الأكثر توافقاً — بيدعم prepared statements و temporary tables و LISTEN/NOTIFY و session variables، لكنه الأقل كفاءة لأنه قريب من السلوك الافتراضي بدون pooler.
2. Transaction Mode: الاتصال بيرجع بعد كل COMMIT أو ROLLBACK. ده الوضع الأكثر استخداماً مع تطبيقات الويب لأن متوسط الـ transaction قصير (10-50ms). الـ trade-off: مش بيدعم session-level features خارج transaction. PgBouncer 1.21+ أضاف دعم prepared statements في الوضع ده.
3. Statement Mode: الاتصال بيرجع بعد كل query واحد. الأعلى كفاءة لكن بيمنع تماماً transactions متعددة الـ statements — مفيد بس في sharding scenarios أو read-only analytics.

إعداد شغّال — جرّبه على staging

الـ config التالي بيخدم 1000 عميل من 25 اتصال DB في وضع transaction:

; /etc/pgbouncer/pgbouncer.ini
[databases]
mydb = host=127.0.0.1 port=5432 dbname=mydb

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt

pool_mode = transaction
max_client_conn = 1000
default_pool_size = 25
reserve_pool_size = 5
reserve_pool_timeout = 3
server_idle_timeout = 600
server_lifetime = 3600
log_connections = 0
log_disconnections = 0

التطبيق بيتصل على البورت 6432 بدل 5432، الباقي شفاف:

import psycopg2

# نفس الكود — البورت بس اللي اتغيّر
conn = psycopg2.connect(
    host="127.0.0.1",
    port=6432,
    dbname="mydb",
    user="app",
    password="..."
)

with conn.cursor() as cur:
    cur.execute("SELECT id, name FROM users WHERE active = true LIMIT 10")
    rows = cur.fetchall()
conn.commit()

أرقام مقاسة على بيئة إنتاج

قياس فعلي على سيرفر 4 vCPU + 8GB RAM، PostgreSQL 16، حمل ويب نموذجي (متوسط الـ query 12ms، تطبيق Django + gunicorn بـ 8 workers لكل instance، 12 instance):

• قبل PgBouncer: 280 اتصال متزامن قبل بداية الـ failures، ذاكرة DB مستهلكة 3.1GB، p99 latency = 380ms، CPU steal بسبب context switching = 18%.
• بعد PgBouncer (transaction mode، pool_size=25): 4,200 اتصال عميل متزامن بدون أي failures، ذاكرة DB مستهلكة 280MB، p99 latency = 42ms، CPU steal = 3%.
• تكلفة إضافية: 0.4ms latency لكل query بسبب الـ hop الزائد، و 64MB رام لـ PgBouncer نفسه.

الفرق مش سحر — هو إن PostgreSQL بقى يشغّل 25 process بدل 280، فالـ context switching اتقلّل 91%، والذاكرة الفاضية بقت متاحة للـ shared_buffers بدل ما تكون مهدورة في processes خاملة.

Trade-offs لازم تعرفها قبل ما تنشر

• Single point of failure إضافي. لو PgBouncer وقع، التطبيق بيقع. الحل العملي: تشغيل 2-3 instances من PgBouncer خلف HAProxy أو AWS NLB، أو استخدام Patroni في حالة الـ HA الكامل.
• Latency إضافية بين 0.3 و 1ms لكل query. على شبكة سحابية بين Availability Zones ممكن توصل 2ms. ضع PgBouncer في نفس الـ zone بتاعت الـ DB.
• Prepared Statements في transaction mode. PostgreSQL بيخزّنها على مستوى الـ session — مع pool sharing، الـ statement اللي تجهّز على اتصال مش هيتلاقى على اتصال تاني. PgBouncer 1.21+ حلّها بـ max_prepared_statements وبيعمل tracking لها على مستوى العميل.
• SET / LISTEN / NOTIFY / Advisory Locks. أوامر بتعتمد على session مش هتشتغل بشكل صحيح في transaction mode. لو محتاجها افتح اتصال مباشر منفصل (bypass للـ pooler) أو استخدم session mode لجزء معيّن من التطبيق.
• التشخيص بقى أصعب. pg_stat_activity هيوريك اتصالات PgBouncer مش العميل الفعلي. لازم تستخدم SHOW POOLS و SHOW CLIENTS داخل PgBouncer admin console.

متى لا تستخدم PgBouncer

مش كل تطبيق محتاج connection pooler خارجي. تجاهله في الحالات دي:

• التطبيق عنده max 50 عميل متزامن (مثلاً API داخلي بـ 5 instances كل واحد بـ pool محلي 10 — مجموع 50 اتصال).
• بتستخدم driver فيه pooling قوي (HikariCP في Java أو pgx pool في Go) مع pool size محدود ومضبوط.
• التطبيق بيعتمد بشكل أساسي على LISTEN/NOTIFY في الزمن الحقيقي.
• عندك analytical workload فيه queries بتاخد ثواني — هنا PgBouncer مش هيفيدك، المشكلة في الـ queries نفسها مش في عدد الاتصالات.
• بتستخدم خدمة managed زي AWS RDS Proxy أو Azure Database مع built-in pooler — مش محتاج تضيف طبقة تانية.

الخطوة التالية

افتح logs PostgreSQL الحالية وابحث عن "FATAL: sorry, too many clients already". لو موجودة، أنت بتفقد طلبات فعلاً. شغّل الاستعلام ده لمدة ساعة كل 5 دقائق:

SELECT state, COUNT(*) 
FROM pg_stat_activity 
WHERE datname = 'mydb' 
GROUP BY state;

لو شفت اتصالات في حالة idle أكتر من 60% من الوقت، PgBouncer هيخفّضها بحوالي 80%. ابدأ بوضع transaction على بيئة staging مع pool_size=25، قس p99 قبل وبعد، وبعدها انقل للإنتاج. ولو ظهرت مشاكل في prepared statements، فعّل max_prepared_statements=100 في الـ config.

المصادر

• PgBouncer Official Documentation — pgbouncer.org/config.html
• PostgreSQL 16 Documentation — Connection Limits (postgresql.org/docs/16/runtime-config-connection.html)
• PgBouncer 1.21 Release Notes — Prepared Statements support in transaction mode
• Citus Data Engineering Blog — "Why PostgreSQL Connection Pooling Matters"
• "PostgreSQL High Performance" — Gregory Smith, 2nd edition
• AWS RDS Proxy Documentation — Connection pooling concepts