PGBOUNCER(1) Databases PGBOUNCER(1)

pgbouncer - ابزار سبک‌وزن مدیریت استخر اتصال برای PostgreSQL

pgbouncer [-d][-R][-v][-u user] <pgbouncer.ini>
pgbouncer -V|-h

در ویندوز، گزینه‌ها عبارتند از:

pgbouncer.exe [-v][-u user] <pgbouncer.ini>
pgbouncer.exe -V|-h

گزینه‌های بیشتر برای راه‌اندازی به عنوان یک سرویس ویندوز:

pgbouncer.exe --regservice   <pgbouncer.ini>
pgbouncer.exe --unregservice <pgbouncer.ini>

pgbouncer یک استخر اتصال (connection pooler) برای PostgreSQL است. هر برنامه مقصدی می‌تواند به گونه‌ای به pgbouncer متصل شود که گویی مستقیماً به یک سرور PostgreSQL وصل شده است، و pgbouncer یک اتصال جدید به سرور واقعی برقرار کرده یا از یکی از اتصالات موجود خود مجدداً استفاده می‌کند.

هدف pgbouncer کاهش بار و افت کارایی ناشی از باز کردن اتصالات جدید در PostgreSQL است.

برای جلوگیری از به خطر افتادن مفاهیم و قواعد تراکنش‌ها هنگام اشتراک‌گذاری اتصالات، pgbouncer از چندین روش تجمیع (pooling) در زمان چرخش اتصالات پشتیبانی می‌کند:

محتاطانه‌ترین و سازگارترین روش. هنگامی که یک کلاینت متصل می‌شود، یک اتصال سرور برای تمام مدتی که کلاینت متصل باقی می‌ماند به آن اختصاص داده می‌شود. زمانی که کلاینت ارتباط خود را قطع کند، اتصال سرور به استخر بازگردانده می‌شود. این روش، حالت پیش‌فرض است.
یک اتصال سرور تنها در طول مدت یک تراکنش به کلاینت اختصاص می‌یابد. هنگامی که PgBouncer متوجه پایان تراکنش شود، اتصال سرور به استخر بازگردانده خواهد شد.
تهاجمی‌ترین روش. اتصال سرور بلافاصله پس از تکمیل یک پرس‌وجو (query) به استخر بازگردانده می‌شود. تراکنش‌های چنددستوری (Multi-statement) در این حالت مجاز نیستند زیرا دچار شکست می‌شوند.

رابط مدیریتی pgbouncer شامل چند دستور جدید SHOW است که هنگام اتصال به یک پایگاه داده‌ی “مجازی” ویژه به نام pgbouncer در دسترس قرار می‌گیرند.

پیکربندی پایه و نحوه استفاده به شرح زیر است:

1.
یک فایل pgbouncer.ini ایجاد کنید. جزئیات در pgbouncer(5) آمده است. مثال ساده:
[databases]
template1 = host=localhost port=5432 dbname=template1
[pgbouncer]
listen_port = 6432
listen_addr = localhost
auth_type = md5
auth_file = userlist.txt
logfile = pgbouncer.log
pidfile = pgbouncer.pid
admin_users = someuser
2.
یک فایل userlist.txt ایجاد کنید که حاوی کاربران مجاز باشد:
"someuser" "same_password_as_in_server"
3.
اجرای pgbouncer:
$ pgbouncer -d pgbouncer.ini
4.
برنامه کاربردی خود (یا کلاینت psql) را به جای اتصال مستقیم به سرور PostgreSQL، به pgbouncer متصل کنید:
$ psql -p 6432 -U someuser template1
5.
با اتصال به پایگاه داده مدیریتی ویژه pgbouncer و اجرای دستور SHOW HELP; کار مدیریت pgbouncer را آغاز کنید:
$ psql -p 6432 -U someuser pgbouncer
pgbouncer=# SHOW HELP;
NOTICE:  Console usage
DETAIL:
  SHOW [HELP|CONFIG|DATABASES|FDS|POOLS|CLIENTS|SERVERS|SOCKETS|LISTS|VERSION|...]
  SET key = arg
  RELOAD
  PAUSE
  SUSPEND
  RESUME
  SHUTDOWN
  [...]
6.
اگر تغییراتی در فایل pgbouncer.ini اعمال کردید، می‌توانید آن را با دستور زیر مجدداً بارگذاری کنید:
pgbouncer=# RELOAD;
اجرا در پس‌زمینه. بدون این گزینه، فرآیند در پیش‌زمینه اجرا خواهد شد.

در حالت دیمن (daemon)، تنظیم pidfile و همچنین logfile یا syslog الزامی است. پس از رفتن به پس‌زمینه، هیچ پیام گزارشی در stderr نوشته نخواهد شد.

نکته: در ویندوز کار نمی‌کند؛ pgbouncer در آنجا باید به عنوان یک سرویس اجرا شود.

منسوخ شده: به‌جای این گزینه، از راه‌اندازی مجدد تدریجی (rolling restart) با چندین فرآیند pgbouncer که با استفاده از so_reuseport روی یک پورت گوش می‌دهند استفاده کنید یک راه‌اندازی مجدد برخط (online restart) انجام می‌دهد. این به معنی اتصال به فرآیند در حال اجرا، بارگذاری سوکت‌های باز از آن، و سپس استفاده از آن‌ها است. اگر فرآیند فعالی وجود نداشته باشد، به طور عادی راه‌اندازی می‌شود. نکته: تنها در صورتی کار می‌کند که سیستم‌عامل از سوکت‌های یونیکس پشتیبانی کند و unix_socket_dir در پیکربندی غیرفعال نشده باشد. روی ویندوز کار نمی‌کند. با اتصالات TLS کار نمی‌کند و این اتصالات قطع می‌شوند.
تغییر به کاربر مشخص‌شده در هنگام راه‌اندازی.
افزایش پرگویی (verbosity). می‌تواند چندین بار استفاده شود.
حالت بی‌صدا: در stderr چیزی ثبت نمی‌کند. این گزینه تأثیری بر سطح پرگویی لاگ‌ها ندارد، فقط stderr استفاده نخواهد شد. برای استفاده در اسکریپت‌های init.d.
نمایش نسخه.
نمایش راهنمای کوتاه.
در Win32: ثبت PgBouncer برای اجرا به عنوان سرویس ویندوز. مقدار پارامتر پیکربندی service_name به عنوان نام ثبت سرویس استفاده می‌شود.
در Win32: لغو ثبت سرویس ویندوز.

کنسول با اتصال عادی به پایگاه داده pgbouncer در دسترس است:

$ psql -p 6432 pgbouncer

تنها کاربرانی که در پارامترهای پیکربندی admin_users یا stats_users فهرست شده‌اند مجاز به ورود به کنسول هستند. (به جز هنگامی که auth_type=any باشد، که در این صورت هر کاربری به عنوان stats_user مجاز به ورود است.)

علاوه بر این، در صورتی که اتصال از طریق سوکت یونیکس برقرار شود و کلاینت دارای همان UID کاربر یونیکسِ فرآیند در حال اجرا باشد، نام کاربری pgbouncer مجاز است بدون گذرواژه وارد شود.

کنسول مدیریت در حال حاضر تنها از پروتکل پرس‌وجوی ساده (simple query protocol) پشتیبانی می‌کند. برخی از درایورها برای همه دستورها از پروتکل پرس‌وجوی گسترده (extended query protocol) استفاده می‌کنند؛ این درایورها برای این کار عمل نخواهند کرد.

دستورهای SHOW اطلاعات را نمایش می‌دهند. هر دستور در ادامه شرح داده شده است.

آمار را نمایش می‌دهد. در این دستور و دستورهای مرتبط، ارقام کلی از زمان شروع فرآیند محاسبه می‌شوند، و میانگین‌ها در هر stats_period به‌روزرسانی می‌گردند.

آمار به تفکیک هر پایگاه داده نمایش داده می‌شود.
تعداد کل تراکنش‌های SQL مدیریت‌شده در استخر (pooled) توسط pgbouncer.
تعداد کل دستورهای SQL مدیریت‌شده در استخر توسط pgbouncer.
تعداد کل دفعاتی که یک سرور به یک کلاینت اختصاص یافته است.
حجم کل ترافیک شبکه دریافت شده توسط pgbouncer بر حسب بایت.
حجم کل ترافیک شبکه ارسال شده توسط pgbouncer بر حسب بایت.
تعداد کل میکروثانیه‌هایی که pgbouncer هنگام اتصال به PostgreSQL در یک تراکنش صرف کرده است، چه در وضعیت idle in transaction و چه در حال اجرای پرس‌وجوها.
تعداد کل میکروثانیه‌هایی که pgbouncer هنگام اتصال فعال به PostgreSQL، در حال اجرای پرس‌وجوها صرف کرده است.
مدت زمانی که کلاینت‌ها در انتظار یک سرور سپری کرده‌اند، بر حسب میکروثانیه. هنگامی که یک اتصال بک‌اند به اتصال کلاینت تخصیص داده می‌شود، به‌روزرسانی می‌گردد.
تعداد کل عبارت‌های آماده‌شده (prepared statements) ایجادشده توسط کلاینت‌ها. تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به max_prepared_statements مراجعه کنید.
تعداد کل عبارت‌های آماده‌شده ایجادشده توسط pgbouncer روی یک سرور. تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به max_prepared_statements مراجعه کنید.
تعداد کل عبارت‌های آماده‌شده که توسط کلاینت‌ها برای اجرا آماده (bind) شده و توسط pgbouncer به PostgreSQL ارسال گردیده‌اند. تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به max_prepared_statements مراجعه کنید.
میانگین تراکنش‌ها در هر ثانیه در آخرین دوره آماری.
میانگین پرس‌وجوها در هر ثانیه در آخرین دوره آماری.
میانگین دفعاتی که یک سرور در هر ثانیه در آخرین دوره آماری به یک کلاینت اختصاص یافته است.
میانگین بایت‌های دریافت‌شده (از کلاینت‌ها) در هر ثانیه.
میانگین بایت‌های ارسال‌شده (به کلاینت‌ها) در هر ثانیه.
میانگین مدت زمان تراکنش، بر حسب میکروثانیه.
میانگین مدت زمان پرس‌وجو، بر حسب میکروثانیه.
زمان سپری‌شده توسط کلاینت‌ها در انتظار یک سرور، بر حسب میکروثانیه (میانگین زمان‌های انتظار برای کلاینت‌هایی که در طول stats_period فعلی یک بک‌اند به آن‌ها اختصاص یافته است).
میانگین تعداد عبارت‌های آماده‌شده ایجادشده توسط کلاینت‌ها. تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به max_prepared_statements مراجعه کنید.
میانگین تعداد عبارت‌های آماده‌شده ایجادشده توسط pgbouncer روی یک سرور. تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به max_prepared_statements مراجعه کنید.
میانگین تعداد عبارت‌های آماده‌شده که توسط کلاینت‌ها برای اجرا آماده (bind) شده و توسط pgbouncer به PostgreSQL ارسال گردیده‌اند. تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به max_prepared_statements مراجعه کنید..SS SHOW STATS_TOTALS زیرمجموعه‌ای از SHOW STATS که مقادیر کل (total_) را نشان می‌دهد.

زیرمجموعه‌ای از SHOW STATS که مقادیر میانگین (avg_) را نشان می‌دهد.

مشابه SHOW STATS اما به‌صورت تجمیع‌شده در تمام پایگاه‌های داده.

مقدار S، برای سرور.
نام کاربری که pgbouncer برای اتصال به سرور استفاده می‌کند.
نام پایگاه داده.
مشخص می‌کند که آیا اتصال سرور از همانندسازی استفاده می‌کند یا خیر. می‌تواند none، logical یا physical باشد.
وضعیت اتصال سرور PgBouncer؛ یکی از موارد active، idle، used، tested، new، active_cancel یا being_canceled.
نشانی IP سرور PostgreSQL.
پورت سرور PostgreSQL.
نشانی مبدا اتصال روی ماشین محلی.
پورت مبدا اتصال روی ماشین محلی.
زمان برقراری اتصال.
زمان ارسال آخرین درخواست.
برای اتصالات سرور استفاده نمی‌شود.
برای اتصالات سرور استفاده نمی‌شود.
مقدار ۱ اگر اتصال در اسرع وقت بسته خواهد شد، به این دلیل که بارگذاری مجدد فایل پیکربندی یا به‌روزرسانی DNS اطلاعات اتصال را تغییر داده است یا دستور RECONNECT صادر شده است.
نشانی شیء داخلی برای این اتصال.
نشانی اتصال کلاینتی که سرور با آن جفت شده است.
شناسه فرآیند (PID) مربوط به فرآیند سرور backend. در صورتی که اتصال از طریق سوکت Unix برقرار شده باشد و سیستم‌عامل از دریافت اطلاعات شناسه فرآیند پشتیبانی کند، PID سیستم‌عامل آن خواهد بود. در غیر این صورت، از بسته لغو (cancel packet) ارسالی سرور استخراج می‌شود که در صورتی که سرور PostgreSQL باشد همان PID است، اما اگر سرور یک PgBouncer دیگر باشد، عددی تصادفی است.
رشته‌ای شامل اطلاعات اتصال TLS، یا در صورت عدم استفاده از TLS، خالی است.
رشته‌ای شامل application_name تنظیم‌شده روی اتصال کلاینت پیوندیافته، یا در صورت عدم تنظیم یا عدم وجود اتصال پیوندیافته، خالی است.
تعداد دستورهای آماده‌سازی‌شده (prepared statements) که روی سرور آماده شده‌اند. این عدد توسط تنظیمات max_prepared_statements محدود می‌شود.
شناسه یکتا برای سرور.

مقدار C، برای کلاینت.
کاربر متصل‌شده کلاینت.
نام پایگاه داده.
مشخص می‌کند که آیا اتصال کلاینت از همانندسازی استفاده می‌کند یا خیر. می‌تواند none، logical یا physical باشد.
وضعیت اتصال کلاینت؛ یکی از موارد active (اتصالات کلاینتی که به اتصالات سرور پیوند دارند)، idle (اتصالات کلاینتی بدون پرس‌وجوی در انتظار پردازش)، waiting، active_cancel_req یا waiting_cancel_req.
نشانی IP کلاینت.
پورت مبدا کلاینت.
نشانی مقصد اتصال روی ماشین محلی.
پورت مقصد اتصال روی ماشین محلی.
برچسب زمانی زمان برقراری اتصال.
برچسب زمانی آخرین درخواست کلاینت.
زمان انتظار فعلی به ثانیه.
بخش میکروثانیه‌ای زمان انتظار فعلی.
برای کلاینت‌ها استفاده نمی‌شود.
نشانی شیء داخلی برای این اتصال.
نشانی اتصال سروری که کلاینت با آن جفت شده است.
شناسه فرآیند (PID)، در صورتی که کلاینت از طریق سوکت Unix متصل شده باشد و سیستم‌عامل از دریافت آن پشتیبانی کند.
رشته‌ای شامل اطلاعات اتصال TLS، یا در صورت عدم استفاده از TLS، خالی است.
رشته‌ای شامل application_name تنظیم‌شده توسط کلاینت برای این اتصال، یا در صورت عدم تنظیم، خالی است.
تعداد دستورهای آماده‌سازی‌شده‌ای (prepared statements) که کلاینت آماده کرده است.
شناسه یکتا برای کلاینت..SS SHOW POOLS برای هر جفت از (database, user) یک مدخل استخر جدید ایجاد می‌شود.
نام پایگاه‌داده.
نام کاربر.
اتصال‌های کلاینتی که یا به اتصال‌های سرور پیوند دارند یا بدون هیچ پرس‌وجوی در انتظار پردازش، در حالت آماده‌به‌کار (idle) هستند.
اتصال‌های کلاینتی که پرس‌وجوهایی ارسال کرده‌اند اما هنوز اتصال سروری دریافت نکرده‌اند.
اتصال‌های کلاینتی که درخواست‌های لغو پرس‌وجو را به سرور هدایت کرده‌اند و منتظر پاسخ سرور هستند.
اتصال‌های کلاینتی که هنوز درخواست‌های لغو پرس‌وجو را به سرور هدایت نکرده‌اند.
اتصال‌های سروری که به یک کلاینت پیوند خورده‌اند.
اتصال‌های سروری که در حال حاضر در حال هدایت یک درخواست لغو هستند.
سرورهایی که در حالت عادی می‌توانستند آماده‌به‌کار شوند، اما تا اتمام تمامی درخواست‌های لغو در جریان که برای لغو یک پرس‌وجو روی این سرور ارسال شده بودند، منتظر می‌مانند.
اتصال‌های سروری که استفاده نشده‌اند و بلافاصله برای پرس‌وجوهای کلاینت قابل استفاده هستند.
اتصال‌های سروری که برای مدتی بیش از server_check_delay آماده‌به‌کار بوده‌اند، بنابراین پیش از استفادهٔ مجدد، لازم است server_check_query روی آن‌ها اجرا شود.
اتصال‌های سروری که در حال حاضر مشغول اجرای server_reset_query یا server_check_query هستند.
اتصال‌های سروری که در حال حاضر در فرآیند ورود به سیستم (login) هستند.
مدت زمانی که اولین (قدیمی‌ترین) کلاینت در صف منتظر مانده است، بر حسب ثانیه. اگر این مقدار رو به افزایش بگذارد، نشان‌دهندهٔ آن است که استخر فعلی سرورها درخواست‌ها را با سرعت کافی پاسخ نمی‌دهد. دلیل این امر می‌تواند سربار بیش از حد سرور یا کوچک بودن بیش از حد تنظیم pool_size باشد.
بخش میکروثانیه‌ایِ حداکثر زمان انتظار.
حالت استخرسازی (pooling mode) در حال استفاده.
مقدار load_balance_hosts مورد استفاده در صورتی که میزبان استخر شامل فهرستی جداشده با کاما باشد.

برای هر همتای (peer) پیکربندی‌شده، یک مدخل peer_pool جدید ایجاد می‌شود.

شناسهٔ (ID) مدخل همتای پیکربندی‌شده.
اتصال‌های کلاینتی که درخواست‌های لغو پرس‌وجو را به سرور هدایت کرده‌اند و منتظر پاسخ سرور هستند.
اتصال‌های کلاینتی که هنوز درخواست‌های لغو پرس‌وجو را به سرور هدایت نکرده‌اند.
اتصال‌های سروری که در حال حاضر در حال هدایت یک درخواست لغو هستند.
اتصال‌های سروری که در حال حاضر در فرآیند ورود به سیستم هستند.

نمایش اطلاعات داخلی زیر، در ستون‌ها (نه سطرها):

تعداد پایگاه‌های داده.
تعداد کاربران.
تعداد استخرها.
تعداد کلاینت‌های آزاد. این‌ها کلاینت‌هایی هستند که اتصالشان قطع شده است، اما PgBouncer حافظهٔ تخصیص‌یافته به آن‌ها را نگه می‌دارد تا برای کلاینت‌های بعدی دوباره استفاده شود و از تخصیص‌های مکرر جلوگیری به عمل آید.
تعداد کلاینت‌های در حال استفاده.
تعداد کلاینت‌ها در وضعیت login.
تعداد سرورهای آزاد. این‌ها سرورهایی هستند که اتصالشان قطع شده است، اما PgBouncer حافظهٔ تخصیص‌یافته به آن‌ها را نگه می‌دارد تا برای سرورهای بعدی دوباره استفاده شود و از تخصیص‌های مکرر جلوگیری به عمل آید.
تعداد سرورهای در حال استفاده.
تعداد نام‌های DNS در حافظهٔ موقت (cache).
تعداد ناحیه‌های DNS در حافظهٔ موقت.
تعداد پرس‌وجوهای DNS در جریان (in-flight).
استفاده نمی‌شود..SS SHOW USERS
نام کاربر.
مقدار بازنویسی‌شده‌ی pool_size کاربر، یا در صورت تنظیم نشدن NULL.
مقدار بازنویسی‌شده‌ی reserve_pool_size کاربر، یا در صورت تنظیم نشدن NULL.
مقدار بازنویسی‌شده‌ی pool_mode کاربر، یا در صورت تنظیم نشدن NULL.
تنظیم max_user_connections کاربر. اگر این تنظیم برای این کاربر خاص تعیین نشده باشد، آن‌گاه مقدار پیش‌فرض نمایش داده خواهد شد.
تعداد فعلی اتصالات سرور که این کاربر به تمام سرورها باز دارد.
تنظیم max_user_client_connections کاربر. اگر این تنظیم برای این کاربر خاص تعیین نشده باشد، آن‌گاه مقدار پیش‌فرض نمایش داده خواهد شد.
تعداد فعلی اتصالات کلاینت که این کاربر به PgBouncer باز دارد.

نام مدخل پایگاه‌داده‌ی پیکربندی‌شده.
میزبانی که PgBouncer به آن متصل می‌شود.
درگاهی که PgBouncer به آن متصل می‌شود.
نام واقعی پایگاه‌داده‌ای که PgBouncer به آن متصل می‌شود.
هنگامی که کاربر بخشی از رشته‌ی اتصال باشد، اتصال میان PgBouncer و PostgreSQL بدون توجه به کاربر کلاینت، به این کاربر مشخص تحمیل می‌شود.
حداکثر تعداد اتصالات سرور.
حداقل تعداد اتصالات سرور.
حداکثر تعداد اتصالات اضافی برای این پایگاه‌داده.
حداکثر طول عمر یک اتصال سرور برای این پایگاه‌داده.
مقدار بازنویسی‌شده‌ی pool_mode پایگاه‌داده، یا NULL در صورتی که به‌جای آن از مقدار پیش‌فرض استفاده شود.
مقدار load_balance_hosts پایگاه‌داده، در صورتی که host شامل فهرستی جداشده با کاما باشد.
حداکثر تعداد مجاز اتصالات سرور برای این پایگاه‌داده، همان‌طور که توسط max_db_connections به‌صورت سراسری یا به‌ازای پایگاه‌داده تنظیم شده است.
تعداد فعلی اتصالات سرور برای این پایگاه‌داده.
حداکثر تعداد مجاز اتصالات کلاینت برای این نمونه‌ی PgBouncer، همان‌طور که توسط max_db_client_connections به‌ازای پایگاه‌داده تنظیم شده است.
تعداد فعلی اتصالات کلاینت برای این پایگاه‌داده.
1 اگر این پایگاه‌داده در حال حاضر متوقف شده باشد، در غیر این صورت 0.
1 اگر این پایگاه‌داده در حال حاضر غیرفعال باشد، در غیر این صورت 0.

شناسه‌ی مدخل همتای پیکربندی‌شده.
میزبانی که PgBouncer به آن متصل می‌شود.
درگاهی که PgBouncer به آن متصل می‌شود.
حداکثر تعداد اتصالات سرور که می‌توان با این همتا برقرار کرد.

دستور درونی - نمایش فهرست توصیف‌کننده‌های فایل در حال استفاده به همراه وضعیت درونی متصل به آن‌ها.

هنگامی که کاربر متصل، نام کاربری “pgbouncer” را داشته باشد، از طریق سوکت Unix متصل شود و UID یکسانی با فرایند در حال اجرا داشته باشد، FDهای واقعی از طریق این اتصال منتقل می‌شوند. این سازوکار برای انجام بازراه‌اندازی برخط (online restart) به کار می‌رود. نکته: این ویژگی در Windows کار نمی‌کند.

این دستور همچنین حلقه‌ی رویداد درونی را مسدود می‌کند، بنابراین نباید در حین استفاده از PgBouncer به کار گرفته شود.

مقدار عددی توصیف‌کننده‌ی فایل.
یکی از گزینه‌های pooler، client یا server.
کاربر اتصالی که از FD استفاده می‌کند.
پایگاه‌داده‌ی اتصالی که از FD استفاده می‌کند.
نشانی IP اتصالی که از FD استفاده می‌کند، یا unix اگر از یک سوکت Unix استفاده شده باشد.
درگاه مورد استفاده توسط اتصالی که از FD استفاده می‌کند.
کلید لغو (cancel key) برای این اتصال.
مقدار fd برای سرور/کلاینت متناظر. در صورت بی‌کار بودن NULL..SS SHOW SOCKETS, SHOW ACTIVE_SOCKETS اطلاعات سطح پایینی را دربارهٔ سوکت‌ها یا تنها سوکت‌های فعال نشان می‌دهد. این شامل اطلاعات نشان‌داده‌شده در SHOW CLIENTS و SHOW SERVERS و همچنین اطلاعات سطح پایین‌تر دیگر است.

تنظیمات پیکربندی فعلی را سطر به سطر با ستون‌های زیر نشان می‌دهد:

نام متغیر پیکربندی
مقدار پیکربندی
مقدار پیش‌فرض پیکربندی
یا yes یا no؛ نشان می‌دهد که آیا متغیر در حین اجرا قابل تغییر است یا خیر. اگر no باشد، متغیر تنها در زمان راه‌اندازی قابل تغییر است. برای تغییر یک متغیر در زمان اجرا از SET استفاده کنید.

اطلاعات سطح پایینی دربارهٔ اندازه‌های فعلی تخصیص‌های گوناگون حافظهٔ داخلی نشان می‌دهد. اطلاعات ارائه‌شده ممکن است تغییر کنند.

نام‌های میزبان موجود در حافظهٔ موقت DNS را نشان می‌دهد.

نام میزبان.
چند ثانیه تا جستجوی بعدی باقی مانده است.
فهرست نشانی‌های جداشده با کاما.

منطقه‌های DNS موجود در حافظهٔ موقت را نشان می‌دهد.

نام منطقه.
شماره سریال فعلی.
نام‌های میزبان متعلق به این منطقه.

رشتهٔ نگارش PgBouncer را نشان می‌دهد.

تنظیمات وضعیت PgBouncer را نشان می‌دهد. وضعیت‌های فعلی عبارتند از active، paused و suspended.

PgBouncer تلاش می‌کند اتصال خود را از همهٔ سرورها قطع کند. قطع شدن هر اتصال سرور، منتظر آزاد شدن آن اتصال با توجه به حالت تجمیع (pooling mode) استخر سرور می‌ماند (در حالت تجمیع تراکنش، تراکنش باید کامل شود؛ در حالت عبارت، عبارت باید کامل شود؛ و در حالت تجمیع نشست، کلاینت باید اتصال را قطع کند). این دستور تا قبل از قطع شدن تمام اتصالات سرور پایان نخواهد یافت. کاربرد این دستور در زمان راه‌اندازی مجدد پایگاه‌داده است.

اگر نام پایگاه‌داده مشخص شده باشد، تنها همان پایگاه‌داده متوقف خواهد شد.

اتصالات جدید کلاینت به یک پایگاه‌دادهٔ متوقف‌شده تا زمان فراخوانی RESUME به انتظار خواهند ماند.

رد کردن تمام اتصالات جدید کلاینت در پایگاه‌دادهٔ مشخص‌شده.

اجازه دادن به اتصالات جدید کلاینت پس از اجرای یک دستور پیشین DISABLE.

بستن هر اتصالِ باز سرور برای پایگاه‌دادهٔ ارائه‌شده، یا تمام پایگاه‌های داده، پس از آزاد شدن آن (با توجه به حالت تجمیع)، حتی اگر طول عمر آن هنوز به پایان نرسیده باشد. اتصالات سرور جدید می‌توانند بلافاصله برقرار شوند و در صورت نیاز بر اساس تنظیمات اندازهٔ استخر متصل خواهند شد.

این دستور زمانی سودمند است که پیکربندی اتصال سرور تغییر کرده باشد، برای نمونه هنگام انتقال تدریجی به یک سرور جدید. زمانی که رشتهٔ اتصال در pgbouncer.ini تغییر کرده و بازخوانی شده باشد (نگاه کنید به RELOAD) یا زمانی که تفکیک نام DNS تغییر کرده باشد، اجرای این دستور لازم نیست، چرا که در این حالت معادل این دستور به صورت خودکار اجرا خواهد شد. این دستور تنها زمانی لازم است که چیزی در پایین‌دست PgBouncer اتصالات را مسیریابی کند.

پس از اجرای این دستور، ممکن است یک دورهٔ طولانی پیش آید که در آن برخی اتصالات سرور به مقصد قدیمی و برخی اتصالات سرور به مقصد جدید بروند. این معمولاً تنها هنگام جابه‌جایی ترافیک فقط‌خواندنی میان نسخه‌های رونوشت فقط‌خواندنی، یا هنگام جابه‌جایی میان گره‌های یک پیکربندی همانندسازی چنداربابی معقول است. اگر لازم است تمام اتصالات هم‌زمان جابه‌جا شوند، در عوض استفاده از PAUSE توصیه می‌شود. برای بستن اتصالات سرور بدون انتظار (برای نمونه در سناریوهای بازگردانی پس از خرابی اضطراری به‌جای انتقال تدریجی)، دستور KILL را نیز در نظر بگیرید.

قطع فوری تمام اتصالات کلاینت و سرور روی پایگاه‌دادهٔ مشخص‌شده یا تمام پایگاه‌های داده، به جز پایگاه‌دادهٔ admin.

اتصالات جدید کلاینت به پایگاه‌داده‌ای که اتصالات آن قطع شده است، تا زمان فراخوانی RESUME در انتظار خواهند ماند.

قطع فوری اتصال کلاینت مشخص‌شده به همراه هرگونه اتصال سرور برای آن کلاینت. کلاینتی که باید اتصالش قطع شود، با مقدار id که با استفاده از دستور SHOW CLIENTS قابل یافتن است، شناسایی می‌شود.

یک دستور نمونه چیزی شبیه به KILL_CLIENT 1234 خواهد بود.

تمام بافرهای سوکت تخلیه می‌شوند و PgBouncer گوش دادن به داده‌ها روی آن‌ها را متوقف می‌کند. این دستور تا پیش از خالی شدن تمام بافرها به پایان نخواهد رسید. برای استفاده در هنگام راه‌اندازی مجدد برخط PgBouncer.

اتصالات جدید کلاینت به یک پایگاه‌دادهٔ تعلیق‌شده تا زمان فراخوانی RESUME در انتظار خواهند ماند..SS RESUME [db] از سرگیری کار متوقف‌شده از دستور پیشین KILL، PAUSE یا SUSPEND.

فرایند PgBouncer خارج خواهد شد.

توقف پذیرش اتصال‌های جدید و خاموش شدن پس از آزاد شدن تمام سرورها. این دستور اساساً مشابه اجرای PAUSE و SHUTDOWN است، با این تفاوت که هم‌زمان با انتظار برای PAUSE، پذیرش اتصال‌های جدید را نیز متوقف می‌کند و همچنین کلاینت‌هایی را که در انتظار دریافت اتصال سرور هستند، فوراً قطع می‌نماید. لطفاً توجه داشته باشید که سوکت‌های UNIX در طول فرایند خاموش شدن باز باقی خواهند ماند اما تنها اتصال‌ها به کنسول مدیریتی PgBouncer را خواهند پذیرفت.

توقف پذیرش اتصال‌های جدید و خاموش کردن فرایند به محض قطع اتصال تمام کلاینت‌های موجود. لطفاً توجه داشته باشید که سوکت‌های UNIX در طول فرایند خاموش شدن باز باقی می‌مانند اما تنها اتصال‌ها به کنسول مدیریتی pgbouncer را می‌پذیرند. از این دستور می‌توان برای راه‌اندازی مجدد چرخشیِ بدون توقف (zero-downtime rolling restart) دو فرایند PgBouncer با استفاده از مراحل زیر استفاده کرد:

1.
اجرای دو یا چند فرایند PgBouncer روی یک درگاه یکسان با استفاده از so_reuseport (پیکربندی peering توصیه می‌شود، اما الزامی نیست). برای دستیابی به عدم قطعی سرویس هنگام راه‌اندازی مجدد، این فرایندها را یکی‌یکی راه‌اندازی مجدد می‌کنیم؛ بنابراین در حالی که یکی در حال راه‌اندازی مجدد است، سایرین برای پذیرش اتصال‌ها در حال اجرا باقی می‌مانند.
2.
یک فرایند را برای شروع راه‌اندازی مجدد انتخاب کنید، بیایید آن را A بنامیم.
3.
دستور SHUTDOWN WAIT_FOR_CLIENTS را برای فرایند A اجرا کنید (یا به آن سیگنال SIGTERM بفرستید).
4.
کاری کنید که همه کلاینت‌ها دوباره متصل شوند. احتمالاً با مدتی صبر کردن تا استخر اتصال سمت کلاینت به دلیل server_idle_timeout خود (یا پیکربندی مشابه) اتصال‌های مجدد برقرار کند. یا در صورتی که از استخر اتصال سمت کلاینت استفاده نمی‌شود، احتمالاً با راه‌اندازی مجدد کلاینت‌ها. پس از اتصال مجدد همه کلاینت‌ها، فرایند A به‌طور خودکار خارج خواهد شد، زیرا دیگر هیچ کلاینتی به آن متصل نیست.
5.
فرایند A را دوباره آغاز کنید.
6.
مراحل ۳، ۴ و ۵ را برای هر یک از فرایندهای باقیمانده، یکی پس از دیگری تکرار کنید تا زمانی که تمام فرایندها را مجدداً راه‌اندازی کرده باشید.

فرایند PgBouncer فایل‌های پیکربندی خود را دوباره بارگذاری کرده و تنظیمات قابل‌تغییر را به‌روزرسانی می‌کند. این شامل فایل پیکربندی اصلی و همچنین فایل‌های مشخص‌شده توسط تنظیمات auth_file و auth_hba_file می‌شود.

PgBouncer متوجه می‌شود که بارگذاری مجدد فایل پیکربندی، پارامترهای اتصال یک تعریف پایگاه داده را تغییر داده است. اتصال موجود سرور به مقصد قدیمی، در آزادسازی بعدی اتصال سرور (مطابق با حالت pooling) بسته خواهد شد، و اتصال‌های سرور جدید فوراً از پارامترهای اتصال به‌روزرسانی‌شده استفاده خواهند کرد.

صبر می‌کند تا تمام اتصال‌های سرور، چه برای پایگاه داده مشخص‌شده یا تمام پایگاه‌های داده، وضعیت “close_needed” را پاک کنند (ببینید SHOW SERVERS). این دستور را می‌توان پس از RECONNECT یا RELOAD فراخوانی کرد تا تا زمان اعمال کامل تغییر پیکربندی مربوطه منتظر ماند؛ به عنوان مثال در اسکریپت‌های switchover.

یک تنظیم پیکربندی را تغییر می‌دهد (همچنین ببینید SHOW CONFIG). برای مثال:

SET log_connections = 1;
SET server_check_query = 'select 2';

(توجه داشته باشید که این دستور در کنسول مدیریتی PgBouncer اجرا می‌شود و تنظیمات PgBouncer را مشخص می‌کند. دستور SET اجرا شده روی پایگاه داده‌ای دیگر، مانند هر دستور SQL دیگر به بک‌اند PostgreSQL ارسال خواهد شد.)

بارگذاری مجدد پیکربندی. مشابه اجرای دستور RELOAD در کنسول.
خاموش شدن فوق‌العاده امن (Super safe shutdown). صبر می‌کند تا تمام کلاینت‌های موجود قطع شوند، اما اتصال‌های جدید را نمی‌پذیرد. این سیگنال معادل اجرای SHUTDOWN WAIT_FOR_CLIENTS در کنسول است. اگر این سیگنال زمانی دریافت شود که فرایند خاموش‌شدن از قبل در جریان است، آن‌گاه به جای “خاموش شدن فوق‌العاده امن” یک “خاموش شدن فوری” فعال می‌شود. در نسخه‌های PgBouncer قدیمی‌تر از 1.23.0، این سیگنال باعث یک “خاموش شدن فوری” می‌شد.
خاموش شدن امن (Safe shutdown). مشابه اجرای SHUTDOWN WAIT_FOR_SERVERS در کنسول. اگر این سیگنال زمانی دریافت شود که فرایند خاموش‌شدن از قبل در جریان است، آن‌گاه به جای “خاموش شدن امن” یک “خاموش شدن فوری” فعال می‌شود.
خاموش شدن فوری (Immediate shutdown). مشابه اجرای SHUTDOWN در کنسول.
مشابه اجرای PAUSE در کنسول.
مشابه اجرای RESUME در کنسول.

از مستندات Libevent:

غیرفعال کردن پشتیبانی از epoll، kqueue، devpoll، poll یا select به ترتیب با تنظیم متغیر محیطی EVENT_NOEPOLL، EVENT_NOKQUEUE، EVENT_NODEVPOLL، EVENT_NOPOLL یا EVENT_NOSELECT امکان‌پذیر است.

با تنظیم متغیر محیطی EVENT_SHOW_METHOD، کتابخانه libevent روش اعلان کرنل مورد استفاده خود را نمایش می‌دهد. pgbouncer(5) - صفحه راهنمای توضیحات تنظیمات پیکربندی

https://www.pgbouncer.org

1.25.2