.\" Automatically generated by Pandoc 3.6
.\"
.TH "PGBOUNCER" "1" "" "1.25.2" "Databases"
.SH "نام (NAME)"
pgbouncer \- ابزار سبک‌وزن مدیریت استخر اتصال برای PostgreSQL
.SH "خلاصه دستور (SYNOPSIS)"
.IP
.EX
pgbouncer [\-d][\-R][\-v][\-u user] <pgbouncer.ini>
pgbouncer \-V|\-h
.EE
.PP
در ویندوز، گزینه‌ها عبارتند از:
.IP
.EX
pgbouncer.exe [\-v][\-u user] <pgbouncer.ini>
pgbouncer.exe \-V|\-h
.EE
.PP
گزینه‌های بیشتر برای راه‌اندازی به عنوان یک سرویس ویندوز:
.IP
.EX
pgbouncer.exe \-\-regservice   <pgbouncer.ini>
pgbouncer.exe \-\-unregservice <pgbouncer.ini>
.EE
.SH "توضیحات (DESCRIPTION)"
\f[B]pgbouncer\f[R] یک استخر اتصال (connection pooler) برای PostgreSQL است.
هر برنامه مقصدی می‌تواند به گونه‌ای به \f[B]pgbouncer\f[R] متصل شود که گویی
مستقیماً به یک سرور PostgreSQL وصل شده است، و \f[B]pgbouncer\f[R] یک اتصال
جدید به سرور واقعی برقرار کرده یا از یکی از اتصالات موجود خود مجدداً استفاده می‌کند.
.PP
هدف \f[B]pgbouncer\f[R] کاهش بار و افت کارایی ناشی از باز کردن اتصالات جدید
در PostgreSQL است.
.PP
برای جلوگیری از به خطر افتادن مفاهیم و قواعد تراکنش‌ها هنگام اشتراک‌گذاری اتصالات،
\f[B]pgbouncer\f[R] از چندین روش تجمیع (pooling) در زمان چرخش اتصالات پشتیبانی می‌کند:
.TP
Session pooling
محتاطانه‌ترین و سازگارترین روش.
هنگامی که یک کلاینت متصل می‌شود، یک اتصال سرور برای تمام مدتی که کلاینت
متصل باقی می‌ماند به آن اختصاص داده می‌شود.
زمانی که کلاینت ارتباط خود را قطع کند، اتصال سرور به استخر بازگردانده می‌شود.
این روش، حالت پیش‌فرض است.
.TP
Transaction pooling
یک اتصال سرور تنها در طول مدت یک تراکنش به کلاینت اختصاص می‌یابد.
هنگامی که PgBouncer متوجه پایان تراکنش شود، اتصال سرور به استخر
بازگردانده خواهد شد.
.TP
Statement pooling
تهاجمی‌ترین روش.
اتصال سرور بلافاصله پس از تکمیل یک پرس‌وجو (query) به استخر بازگردانده می‌شود.
تراکنش‌های چنددستوری (Multi\-statement) در این حالت مجاز نیستند زیرا
دچار شکست می‌شوند.
.PP
رابط مدیریتی \f[B]pgbouncer\f[R] شامل چند دستور جدید \f[CR]SHOW\f[R] است
که هنگام اتصال به یک پایگاه داده‌ی \[lq]مجازی\[rq] ویژه به نام \f[B]pgbouncer\f[R]
در دسترس قرار می‌گیرند.
.SH "شروع سریع (QUICK-START)"
پیکربندی پایه و نحوه استفاده به شرح زیر است:
.IP "1." 3
یک فایل pgbouncer.ini ایجاد کنید.
جزئیات در \f[B]pgbouncer(5)\f[R] آمده است.
مثال ساده:
.RS 4
.IP
.EX
 [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
.EE
.RE
.IP "2." 3
یک فایل \f[CR]userlist.txt\f[R] ایجاد کنید که حاوی کاربران مجاز باشد:
.RS 4
.IP
.EX
 \[dq]someuser\[dq] \[dq]same_password_as_in_server\[dq]
.EE
.RE
.IP "3." 3
اجرای \f[B]pgbouncer\f[R]:
.RS 4
.IP
.EX
 $ pgbouncer \-d pgbouncer.ini
.EE
.RE
.IP "4." 3
برنامه کاربردی خود (یا کلاینت \f[B]psql\f[R]) را به جای اتصال مستقیم به سرور
PostgreSQL، به \f[B]pgbouncer\f[R] متصل کنید:
.RS 4
.IP
.EX
 $ psql \-p 6432 \-U someuser template1
.EE
.RE
.IP "5." 3
با اتصال به پایگاه داده مدیریتی ویژه \f[B]pgbouncer\f[R] و اجرای دستور
\f[CR]SHOW HELP;\f[R] کار مدیریت \f[B]pgbouncer\f[R] را آغاز کنید:
.RS 4
.IP
.EX
 $ 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
   [...]
.EE
.RE
.IP "6." 3
اگر تغییراتی در فایل pgbouncer.ini اعمال کردید، می‌توانید آن را با دستور زیر
مجدداً بارگذاری کنید:
.RS 4
.IP
.EX
 pgbouncer=# RELOAD;
.EE
.RE.SH "گزینه‌های خط فرمان (COMMAND LINE SWITCHES)"
.TP
\f[CR]\-d\f[R], \f[CR]\-\-daemon\f[R]
اجرا در پس‌زمینه.
بدون این گزینه، فرآیند در پیش‌زمینه اجرا خواهد شد.
.RS
.PP
در حالت دیمن (daemon)، تنظیم \f[CR]pidfile\f[R] و همچنین \f[CR]logfile\f[R]
یا \f[CR]syslog\f[R] الزامی است.
پس از رفتن به پس‌زمینه، هیچ پیام گزارشی در stderr نوشته نخواهد شد.
.PP
نکته: در ویندوز کار نمی‌کند؛ \f[B]pgbouncer\f[R] در آنجا باید به عنوان یک
سرویس اجرا شود.
.RE
.TP
\f[CR]\-R\f[R], \f[CR]\-\-reboot\f[R]
\f[B]منسوخ شده: به‌جای این گزینه، از راه‌اندازی مجدد تدریجی (rolling restart) با
چندین فرآیند pgbouncer که با استفاده از so_reuseport روی یک پورت گوش می‌دهند
استفاده کنید\f[R] یک راه‌اندازی مجدد برخط (online restart) انجام می‌دهد.
این به معنی اتصال به فرآیند در حال اجرا، بارگذاری سوکت‌های باز از آن،
و سپس استفاده از آن‌ها است.
اگر فرآیند فعالی وجود نداشته باشد، به طور عادی راه‌اندازی می‌شود.
نکته: تنها در صورتی کار می‌کند که سیستم‌عامل از سوکت‌های یونیکس پشتیبانی کند و
\f[CR]unix_socket_dir\f[R] در پیکربندی غیرفعال نشده باشد.
روی ویندوز کار نمی‌کند.
با اتصالات TLS کار نمی‌کند و این اتصالات قطع می‌شوند.
.TP
\f[CR]\-u\f[R] \f[I]USERNAME\f[R], \f[CR]\-\-user=\f[R]\f[I]USERNAME\f[R]
تغییر به کاربر مشخص‌شده در هنگام راه‌اندازی.
.TP
\f[CR]\-v\f[R], \f[CR]\-\-verbose\f[R]
افزایش پرگویی (verbosity).
می‌تواند چندین بار استفاده شود.
.TP
\f[CR]\-q\f[R], \f[CR]\-\-quiet\f[R]
حالت بی‌صدا: در stderr چیزی ثبت نمی‌کند.
این گزینه تأثیری بر سطح پرگویی لاگ‌ها ندارد، فقط stderr استفاده
نخواهد شد.
برای استفاده در اسکریپت‌های init.d.
.TP
\f[CR]\-V\f[R], \f[CR]\-\-version\f[R]
نمایش نسخه.
.TP
\f[CR]\-h\f[R], \f[CR]\-\-help\f[R]
نمایش راهنمای کوتاه.
.TP
\f[CR]\-\-regservice\f[R]
در Win32: ثبت PgBouncer برای اجرا به عنوان سرویس ویندوز.
مقدار پارامتر پیکربندی \f[B]service_name\f[R] به عنوان نام ثبت سرویس
استفاده می‌شود.
.TP
\f[CR]\-\-unregservice\f[R]
در Win32: لغو ثبت سرویس ویندوز.
.SH "کنسول مدیریت (ADMIN CONSOLE)"
کنسول با اتصال عادی به پایگاه داده \f[B]pgbouncer\f[R] در دسترس است:
.IP
.EX
$ psql \-p 6432 pgbouncer
.EE
.PP
تنها کاربرانی که در پارامترهای پیکربندی \f[B]admin_users\f[R] یا
\f[B]stats_users\f[R] فهرست شده‌اند مجاز به ورود به کنسول هستند.
(به جز هنگامی که \f[CR]auth_type=any\f[R] باشد، که در این صورت هر کاربری
به عنوان stats_user مجاز به ورود است.)
.PP
علاوه بر این، در صورتی که اتصال از طریق سوکت یونیکس برقرار شود و کلاینت
دارای همان UID کاربر یونیکسِ فرآیند در حال اجرا باشد، نام کاربری \f[B]pgbouncer\f[R]
مجاز است بدون گذرواژه وارد شود.
.PP
کنسول مدیریت در حال حاضر تنها از پروتکل پرس‌وجوی ساده (simple query protocol) پشتیبانی
می‌کند. برخی از درایورها برای همه دستورها از پروتکل پرس‌وجوی گسترده (extended query protocol)
استفاده می‌کنند؛ این درایورها برای این کار عمل نخواهند کرد.
.SS "دستورهای نمایش (Show commands)"
دستورهای \f[B]SHOW\f[R] اطلاعات را نمایش می‌دهند.
هر دستور در ادامه شرح داده شده است.
.SS SHOW STATS
آمار را نمایش می‌دهد.
در این دستور و دستورهای مرتبط، ارقام کلی از زمان شروع فرآیند محاسبه می‌شوند،
و میانگین‌ها در هر \f[CR]stats_period\f[R] به‌روزرسانی می‌گردند.
.TP
database
آمار به تفکیک هر پایگاه داده نمایش داده می‌شود.
.TP
total_xact_count
تعداد کل تراکنش‌های SQL مدیریت‌شده در استخر (pooled) توسط \f[B]pgbouncer\f[R].
.TP
total_query_count
تعداد کل دستورهای SQL مدیریت‌شده در استخر توسط \f[B]pgbouncer\f[R].
.TP
total_server_assignment_count
تعداد کل دفعاتی که یک سرور به یک کلاینت اختصاص یافته است.
.TP
total_received
حجم کل ترافیک شبکه دریافت شده توسط \f[B]pgbouncer\f[R] بر حسب بایت.
.TP
total_sent
حجم کل ترافیک شبکه ارسال شده توسط \f[B]pgbouncer\f[R] بر حسب بایت.
.TP
total_xact_time
تعداد کل میکروثانیه‌هایی که \f[B]pgbouncer\f[R] هنگام اتصال به PostgreSQL
در یک تراکنش صرف کرده است، چه در وضعیت idle in transaction و چه در حال اجرای پرس‌وجوها.
.TP
total_query_time
تعداد کل میکروثانیه‌هایی که \f[B]pgbouncer\f[R] هنگام اتصال فعال به PostgreSQL،
در حال اجرای پرس‌وجوها صرف کرده است.
.TP
total_wait_time
مدت زمانی که کلاینت‌ها در انتظار یک سرور سپری کرده‌اند، بر حسب میکروثانیه.
هنگامی که یک اتصال بک‌اند به اتصال کلاینت تخصیص داده می‌شود، به‌روزرسانی می‌گردد.
.TP
total_client_parse_count
تعداد کل عبارت‌های آماده‌شده (prepared statements) ایجادشده توسط کلاینت‌ها.
تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به
\f[CR]max_prepared_statements\f[R] مراجعه کنید.
.TP
total_server_parse_count
تعداد کل عبارت‌های آماده‌شده ایجادشده توسط \f[B]pgbouncer\f[R] روی یک سرور.
تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به
\f[CR]max_prepared_statements\f[R] مراجعه کنید.
.TP
total_bind_count
تعداد کل عبارت‌های آماده‌شده که توسط کلاینت‌ها برای اجرا آماده (bind) شده
و توسط \f[B]pgbouncer\f[R] به PostgreSQL ارسال گردیده‌اند.
تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به
\f[CR]max_prepared_statements\f[R] مراجعه کنید.
.TP
avg_xact_count
میانگین تراکنش‌ها در هر ثانیه در آخرین دوره آماری.
.TP
avg_query_count
میانگین پرس‌وجوها در هر ثانیه در آخرین دوره آماری.
.TP
avg_server_assignment_count
میانگین دفعاتی که یک سرور در هر ثانیه در آخرین دوره آماری به یک کلاینت
اختصاص یافته است.
.TP
avg_recv
میانگین بایت‌های دریافت‌شده (از کلاینت‌ها) در هر ثانیه.
.TP
avg_sent
میانگین بایت‌های ارسال‌شده (به کلاینت‌ها) در هر ثانیه.
.TP
avg_xact_time
میانگین مدت زمان تراکنش، بر حسب میکروثانیه.
.TP
avg_query_time
میانگین مدت زمان پرس‌وجو، بر حسب میکروثانیه.
.TP
avg_wait_time
زمان سپری‌شده توسط کلاینت‌ها در انتظار یک سرور، بر حسب میکروثانیه (میانگین
زمان‌های انتظار برای کلاینت‌هایی که در طول \f[CR]stats_period\f[R] فعلی یک بک‌اند به آن‌ها
اختصاص یافته است).
.TP
avg_client_parse_count
میانگین تعداد عبارت‌های آماده‌شده ایجادشده توسط کلاینت‌ها.
تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به
\f[CR]max_prepared_statements\f[R] مراجعه کنید.
.TP
avg_server_parse_count
میانگین تعداد عبارت‌های آماده‌شده ایجادشده توسط \f[B]pgbouncer\f[R] روی
یک سرور.
تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به
\f[CR]max_prepared_statements\f[R] مراجعه کنید.
.TP
avg_bind_count
میانگین تعداد عبارت‌های آماده‌شده که توسط کلاینت‌ها برای اجرا آماده (bind) شده
و توسط \f[B]pgbouncer\f[R] به PostgreSQL ارسال گردیده‌اند.
تنها در حالت ردیابی عبارت‌های آماده نام‌گذاری‌شده کاربرد دارد، به
\f[CR]max_prepared_statements\f[R] مراجعه کنید..SS SHOW STATS_TOTALS
زیرمجموعه‌ای از \f[B]SHOW STATS\f[R] که مقادیر کل
(\f[B]total_\f[R]) را نشان می‌دهد.
.SS SHOW STATS_AVERAGES
زیرمجموعه‌ای از \f[B]SHOW STATS\f[R] که مقادیر میانگین
(\f[B]avg_\f[R]) را نشان می‌دهد.
.SS SHOW TOTALS
مشابه \f[B]SHOW STATS\f[R] اما به‌صورت تجمیع‌شده در تمام پایگاه‌های داده.
.SS SHOW SERVERS
.TP
type
مقدار S، برای سرور.
.TP
user
نام کاربری که \f[B]pgbouncer\f[R] برای اتصال به سرور استفاده می‌کند.
.TP
database
نام پایگاه داده.
.TP
replication
مشخص می‌کند که آیا اتصال سرور از همانندسازی استفاده می‌کند یا خیر.
می‌تواند \f[B]none\f[R]، \f[B]logical\f[R] یا \f[B]physical\f[R] باشد.
.TP
state
وضعیت اتصال سرور PgBouncer؛ یکی از موارد \f[B]active\f[R]،
\f[B]idle\f[R]، \f[B]used\f[R]، \f[B]tested\f[R]، \f[B]new\f[R]،
\f[B]active_cancel\f[R] یا \f[B]being_canceled\f[R].
.TP
addr
نشانی IP سرور PostgreSQL.
.TP
port
پورت سرور PostgreSQL.
.TP
local_addr
نشانی مبدا اتصال روی ماشین محلی.
.TP
local_port
پورت مبدا اتصال روی ماشین محلی.
.TP
connect_time
زمان برقراری اتصال.
.TP
request_time
زمان ارسال آخرین درخواست.
.TP
wait
برای اتصالات سرور استفاده نمی‌شود.
.TP
wait_us
برای اتصالات سرور استفاده نمی‌شود.
.TP
close_needed
مقدار ۱ اگر اتصال در اسرع وقت بسته خواهد شد، به این دلیل که
بارگذاری مجدد فایل پیکربندی یا به‌روزرسانی DNS اطلاعات اتصال را
تغییر داده است یا دستور \f[B]RECONNECT\f[R] صادر شده است.
.TP
ptr
نشانی شیء داخلی برای این اتصال.
.TP
link
نشانی اتصال کلاینتی که سرور با آن جفت شده است.
.TP
remote_pid
شناسه فرآیند (PID) مربوط به فرآیند سرور backend.
در صورتی که اتصال از طریق سوکت Unix برقرار شده باشد و سیستم‌عامل از
دریافت اطلاعات شناسه فرآیند پشتیبانی کند، PID سیستم‌عامل آن خواهد بود.
در غیر این صورت، از بسته لغو (cancel packet) ارسالی سرور استخراج می‌شود
که در صورتی که سرور PostgreSQL باشد همان PID است، اما اگر سرور یک PgBouncer
دیگر باشد، عددی تصادفی است.
.TP
tls
رشته‌ای شامل اطلاعات اتصال TLS، یا در صورت عدم استفاده از TLS، خالی است.
.TP
application_name
رشته‌ای شامل \f[CR]application_name\f[R] تنظیم‌شده روی اتصال کلاینت
پیوندیافته، یا در صورت عدم تنظیم یا عدم وجود اتصال پیوندیافته، خالی است.
.TP
prepared_statements
تعداد دستورهای آماده‌سازی‌شده (prepared statements) که روی سرور آماده شده‌اند.
این عدد توسط تنظیمات \f[CR]max_prepared_statements\f[R]
محدود می‌شود.
.TP
id
شناسه یکتا برای سرور.
.SS SHOW CLIENTS
.TP
type
مقدار C، برای کلاینت.
.TP
user
کاربر متصل‌شده کلاینت.
.TP
database
نام پایگاه داده.
.TP
replication
مشخص می‌کند که آیا اتصال کلاینت از همانندسازی استفاده می‌کند یا خیر.
می‌تواند \f[B]none\f[R]، \f[B]logical\f[R] یا \f[B]physical\f[R] باشد.
.TP
state
وضعیت اتصال کلاینت؛ یکی از موارد \f[B]active\f[R] (اتصالات کلاینتی
که به اتصالات سرور پیوند دارند)، \f[B]idle\f[R]
(اتصالات کلاینتی بدون پرس‌وجوی در انتظار پردازش)،
\f[B]waiting\f[R]، \f[B]active_cancel_req\f[R] یا
\f[B]waiting_cancel_req\f[R].
.TP
addr
نشانی IP کلاینت.
.TP
port
پورت مبدا کلاینت.
.TP
local_addr
نشانی مقصد اتصال روی ماشین محلی.
.TP
local_port
پورت مقصد اتصال روی ماشین محلی.
.TP
connect_time
برچسب زمانی زمان برقراری اتصال.
.TP
request_time
برچسب زمانی آخرین درخواست کلاینت.
.TP
wait
زمان انتظار فعلی به ثانیه.
.TP
wait_us
بخش میکروثانیه‌ای زمان انتظار فعلی.
.TP
close_needed
برای کلاینت‌ها استفاده نمی‌شود.
.TP
ptr
نشانی شیء داخلی برای این اتصال.
.TP
link
نشانی اتصال سروری که کلاینت با آن جفت شده است.
.TP
remote_pid
شناسه فرآیند (PID)، در صورتی که کلاینت از طریق سوکت Unix متصل شده باشد
و سیستم‌عامل از دریافت آن پشتیبانی کند.
.TP
tls
رشته‌ای شامل اطلاعات اتصال TLS، یا در صورت عدم استفاده از TLS، خالی است.
.TP
application_name
رشته‌ای شامل \f[CR]application_name\f[R] تنظیم‌شده توسط کلاینت
برای این اتصال، یا در صورت عدم تنظیم، خالی است.
.TP
prepared_statements
تعداد دستورهای آماده‌سازی‌شده‌ای (prepared statements) که کلاینت آماده کرده است.
.TP
id
شناسه یکتا برای کلاینت..SS SHOW POOLS
برای هر جفت از (database, user) یک مدخل استخر جدید ایجاد می‌شود.
.TP
database
نام پایگاه‌داده.
.TP
user
نام کاربر.
.TP
cl_active
اتصال‌های کلاینتی که یا به اتصال‌های سرور پیوند دارند یا بدون هیچ پرس‌وجوی در انتظار پردازش، در حالت آماده‌به‌کار (idle) هستند.
.TP
cl_waiting
اتصال‌های کلاینتی که پرس‌وجوهایی ارسال کرده‌اند اما هنوز اتصال سروری دریافت نکرده‌اند.
.TP
cl_active_cancel_req
اتصال‌های کلاینتی که درخواست‌های لغو پرس‌وجو را به سرور هدایت کرده‌اند و منتظر پاسخ سرور هستند.
.TP
cl_waiting_cancel_req
اتصال‌های کلاینتی که هنوز درخواست‌های لغو پرس‌وجو را به سرور هدایت نکرده‌اند.
.TP
sv_active
اتصال‌های سروری که به یک کلاینت پیوند خورده‌اند.
.TP
sv_active_cancel
اتصال‌های سروری که در حال حاضر در حال هدایت یک درخواست لغو هستند.
.TP
sv_being_canceled
سرورهایی که در حالت عادی می‌توانستند آماده‌به‌کار شوند، اما تا اتمام تمامی درخواست‌های لغو در جریان که برای لغو یک پرس‌وجو روی این سرور ارسال شده بودند، منتظر می‌مانند.
.TP
sv_idle
اتصال‌های سروری که استفاده نشده‌اند و بلافاصله برای پرس‌وجوهای کلاینت قابل استفاده هستند.
.TP
sv_used
اتصال‌های سروری که برای مدتی بیش از
\f[CR]server_check_delay\f[R] آماده‌به‌کار بوده‌اند، بنابراین پیش از استفادهٔ مجدد، لازم است
\f[CR]server_check_query\f[R] روی آن‌ها اجرا شود.
.TP
sv_tested
اتصال‌های سروری که در حال حاضر مشغول اجرای
\f[CR]server_reset_query\f[R] یا \f[CR]server_check_query\f[R] هستند.
.TP
sv_login
اتصال‌های سروری که در حال حاضر در فرآیند ورود به سیستم (login) هستند.
.TP
maxwait
مدت زمانی که اولین (قدیمی‌ترین) کلاینت در صف منتظر مانده است، بر حسب ثانیه.
اگر این مقدار رو به افزایش بگذارد، نشان‌دهندهٔ آن است که استخر فعلی سرورها درخواست‌ها را با سرعت کافی پاسخ نمی‌دهد.
دلیل این امر می‌تواند سربار بیش از حد سرور یا کوچک بودن بیش از حد تنظیم
\f[B]pool_size\f[R] باشد.
.TP
maxwait_us
بخش میکروثانیه‌ایِ حداکثر زمان انتظار.
.TP
pool_mode
حالت استخرسازی (pooling mode) در حال استفاده.
.TP
load_balance_hosts
مقدار load_balance_hosts مورد استفاده در صورتی که میزبان استخر شامل فهرستی جداشده با کاما باشد.
.SS SHOW PEER_POOLS
برای هر همتای (peer) پیکربندی‌شده، یک مدخل peer_pool جدید ایجاد می‌شود.
.TP
database
شناسهٔ (ID) مدخل همتای پیکربندی‌شده.
.TP
cl_active_cancel_req
اتصال‌های کلاینتی که درخواست‌های لغو پرس‌وجو را به سرور هدایت کرده‌اند و منتظر پاسخ سرور هستند.
.TP
cl_waiting_cancel_req
اتصال‌های کلاینتی که هنوز درخواست‌های لغو پرس‌وجو را به سرور هدایت نکرده‌اند.
.TP
sv_active_cancel
اتصال‌های سروری که در حال حاضر در حال هدایت یک درخواست لغو هستند.
.TP
sv_login
اتصال‌های سروری که در حال حاضر در فرآیند ورود به سیستم هستند.
.SS SHOW LISTS
نمایش اطلاعات داخلی زیر، در ستون‌ها (نه سطرها):
.TP
databases
تعداد پایگاه‌های داده.
.TP
users
تعداد کاربران.
.TP
pools
تعداد استخرها.
.TP
free_clients
تعداد کلاینت‌های آزاد.
این‌ها کلاینت‌هایی هستند که اتصالشان قطع شده است، اما PgBouncer حافظهٔ تخصیص‌یافته به آن‌ها را نگه می‌دارد تا برای کلاینت‌های بعدی دوباره استفاده شود و از تخصیص‌های مکرر جلوگیری به عمل آید.
.TP
used_clients
تعداد کلاینت‌های در حال استفاده.
.TP
login_clients
تعداد کلاینت‌ها در وضعیت \f[B]login\f[R].
.TP
free_servers
تعداد سرورهای آزاد.
این‌ها سرورهایی هستند که اتصالشان قطع شده است، اما PgBouncer حافظهٔ تخصیص‌یافته به آن‌ها را نگه می‌دارد تا برای سرورهای بعدی دوباره استفاده شود و از تخصیص‌های مکرر جلوگیری به عمل آید.
.TP
used_servers
تعداد سرورهای در حال استفاده.
.TP
dns_names
تعداد نام‌های DNS در حافظهٔ موقت (cache).
.TP
dns_zones
تعداد ناحیه‌های DNS در حافظهٔ موقت.
.TP
dns_queries
تعداد پرس‌وجوهای DNS در جریان (in\-flight).
.TP
dns_pending
استفاده نمی‌شود..SS SHOW USERS
.TP
name
نام کاربر.
.TP
pool_size
مقدار بازنویسی‌شده‌ی pool_size کاربر،
یا در صورت تنظیم نشدن NULL.
.TP
reserve_pool_size
مقدار بازنویسی‌شده‌ی reserve_pool_size کاربر،
یا در صورت تنظیم نشدن NULL.
.TP
pool_mode
مقدار بازنویسی‌شده‌ی pool_mode کاربر، یا در صورت تنظیم نشدن NULL.
.TP
max_user_connections
تنظیم max_user_connections کاربر.
اگر این تنظیم برای این کاربر خاص تعیین نشده باشد، آن‌گاه مقدار
پیش‌فرض نمایش داده خواهد شد.
.TP
current_connections
تعداد فعلی اتصالات سرور که این کاربر به تمام
سرورها باز دارد.
.TP
max_user_client_connections
تنظیم max_user_client_connections کاربر.
اگر این تنظیم برای این کاربر خاص تعیین نشده باشد، آن‌گاه مقدار
پیش‌فرض نمایش داده خواهد شد.
.TP
current_client_connections
تعداد فعلی اتصالات کلاینت که این کاربر به
PgBouncer باز دارد.
.SS SHOW DATABASES
.TP
name
نام مدخل پایگاه‌داده‌ی پیکربندی‌شده.
.TP
host
میزبانی که PgBouncer به آن متصل می‌شود.
.TP
port
درگاهی که PgBouncer به آن متصل می‌شود.
.TP
database
نام واقعی پایگاه‌داده‌ای که PgBouncer به آن متصل می‌شود.
.TP
force_user
هنگامی که کاربر بخشی از رشته‌ی اتصال باشد، اتصال میان
PgBouncer و PostgreSQL بدون توجه به کاربر کلاینت، به این کاربر مشخص
تحمیل می‌شود.
.TP
pool_size
حداکثر تعداد اتصالات سرور.
.TP
min_pool_size
حداقل تعداد اتصالات سرور.
.TP
reserve_pool_size
حداکثر تعداد اتصالات اضافی برای این پایگاه‌داده.
.TP
server_lifetime
حداکثر طول عمر یک اتصال سرور برای این پایگاه‌داده.
.TP
pool_mode
مقدار بازنویسی‌شده‌ی pool_mode پایگاه‌داده، یا NULL در صورتی که به‌جای آن
از مقدار پیش‌فرض استفاده شود.
.TP
load_balance_hosts
مقدار load_balance_hosts پایگاه‌داده، در صورتی که host شامل فهرستی
جداشده با کاما باشد.
.TP
max_connections
حداکثر تعداد مجاز اتصالات سرور برای این پایگاه‌داده، همان‌طور که توسط
\f[B]max_db_connections\f[R] به‌صورت سراسری یا به‌ازای پایگاه‌داده تنظیم شده است.
.TP
current_connections
تعداد فعلی اتصالات سرور برای این پایگاه‌داده.
.TP
max_client_connections
حداکثر تعداد مجاز اتصالات کلاینت برای این نمونه‌ی PgBouncer،
همان‌طور که توسط max_db_client_connections به‌ازای پایگاه‌داده تنظیم شده است.
.TP
current_client_connections
تعداد فعلی اتصالات کلاینت برای این پایگاه‌داده.
.TP
paused
1 اگر این پایگاه‌داده در حال حاضر متوقف شده باشد، در غیر این صورت 0.
.TP
disabled
1 اگر این پایگاه‌داده در حال حاضر غیرفعال باشد، در غیر این صورت 0.
.SS SHOW PEERS
.TP
peer_id
شناسه‌ی مدخل همتای پیکربندی‌شده.
.TP
host
میزبانی که PgBouncer به آن متصل می‌شود.
.TP
port
درگاهی که PgBouncer به آن متصل می‌شود.
.TP
pool_size
حداکثر تعداد اتصالات سرور که می‌توان با این همتا برقرار کرد.
.SS SHOW FDS
دستور درونی \- نمایش فهرست توصیف‌کننده‌های فایل در حال استفاده به همراه وضعیت
درونی متصل به آن‌ها.
.PP
هنگامی که کاربر متصل، نام کاربری \[lq]pgbouncer\[rq] را داشته باشد، از
طریق سوکت Unix متصل شود و UID یکسانی با فرایند در حال اجرا داشته باشد،
FDهای واقعی از طریق این اتصال منتقل می‌شوند.
این سازوکار برای انجام بازراه‌اندازی برخط (online restart) به کار می‌رود.
نکته: این ویژگی در Windows کار نمی‌کند.
.PP
این دستور همچنین حلقه‌ی رویداد درونی را مسدود می‌کند، بنابراین نباید
در حین استفاده از PgBouncer به کار گرفته شود.
.TP
fd
مقدار عددی توصیف‌کننده‌ی فایل.
.TP
task
یکی از گزینه‌های \f[B]pooler\f[R]، \f[B]client\f[R] یا \f[B]server\f[R].
.TP
user
کاربر اتصالی که از FD استفاده می‌کند.
.TP
database
پایگاه‌داده‌ی اتصالی که از FD استفاده می‌کند.
.TP
addr
نشانی IP اتصالی که از FD استفاده می‌کند، یا \f[B]unix\f[R] اگر از یک سوکت
Unix استفاده شده باشد.
.TP
port
درگاه مورد استفاده توسط اتصالی که از FD استفاده می‌کند.
.TP
cancel
کلید لغو (cancel key) برای این اتصال.
.TP
link
مقدار fd برای سرور/کلاینت متناظر.
در صورت بی‌کار بودن NULL..SS SHOW SOCKETS, SHOW ACTIVE_SOCKETS
اطلاعات سطح پایینی را دربارهٔ سوکت‌ها یا تنها سوکت‌های فعال نشان می‌دهد.
این شامل اطلاعات نشان‌داده‌شده در \f[B]SHOW CLIENTS\f[R] و
\f[B]SHOW SERVERS\f[R] و همچنین اطلاعات سطح پایین‌تر دیگر است.
.SS SHOW CONFIG
تنظیمات پیکربندی فعلی را سطر به سطر با ستون‌های زیر نشان می‌دهد:
.TP
key
نام متغیر پیکربندی
.TP
value
مقدار پیکربندی
.TP
default
مقدار پیش‌فرض پیکربندی
.TP
changeable
یا \f[B]yes\f[R] یا \f[B]no\f[R]؛ نشان می‌دهد که آیا متغیر در حین اجرا قابل تغییر است یا خیر.
اگر \f[B]no\f[R] باشد، متغیر تنها در زمان راه‌اندازی قابل تغییر است.
برای تغییر یک متغیر در زمان اجرا از \f[B]SET\f[R] استفاده کنید.
.SS SHOW MEM
اطلاعات سطح پایینی دربارهٔ اندازه‌های فعلی تخصیص‌های گوناگون حافظهٔ داخلی نشان می‌دهد.
اطلاعات ارائه‌شده ممکن است تغییر کنند.
.SS SHOW DNS_HOSTS
نام‌های میزبان موجود در حافظهٔ موقت DNS را نشان می‌دهد.
.TP
hostname
نام میزبان.
.TP
ttl
چند ثانیه تا جستجوی بعدی باقی مانده است.
.TP
addrs
فهرست نشانی‌های جداشده با کاما.
.SS SHOW DNS_ZONES
منطقه‌های DNS موجود در حافظهٔ موقت را نشان می‌دهد.
.TP
zonename
نام منطقه.
.TP
serial
شماره سریال فعلی.
.TP
count
نام‌های میزبان متعلق به این منطقه.
.SS SHOW VERSION
رشتهٔ نگارش PgBouncer را نشان می‌دهد.
.SS SHOW STATE
تنظیمات وضعیت PgBouncer را نشان می‌دهد.
وضعیت‌های فعلی عبارتند از active، paused و suspended.
.SS دستورهای مهار فرایند (Process controlling commands)
.SS PAUSE [db]
PgBouncer تلاش می‌کند اتصال خود را از همهٔ سرورها قطع کند.
قطع شدن هر اتصال سرور، منتظر آزاد شدن آن اتصال با توجه به حالت تجمیع (pooling mode) استخر سرور می‌ماند (در حالت تجمیع تراکنش، تراکنش باید کامل شود؛ در حالت عبارت، عبارت باید کامل شود؛ و در حالت تجمیع نشست، کلاینت باید اتصال را قطع کند).
این دستور تا قبل از قطع شدن تمام اتصالات سرور پایان نخواهد یافت.
کاربرد این دستور در زمان راه‌اندازی مجدد پایگاه‌داده است.
.PP
اگر نام پایگاه‌داده مشخص شده باشد، تنها همان پایگاه‌داده متوقف خواهد شد.
.PP
اتصالات جدید کلاینت به یک پایگاه‌دادهٔ متوقف‌شده تا زمان فراخوانی
\f[B]RESUME\f[R] به انتظار خواهند ماند.
.SS DISABLE db
رد کردن تمام اتصالات جدید کلاینت در پایگاه‌دادهٔ مشخص‌شده.
.SS ENABLE db
اجازه دادن به اتصالات جدید کلاینت پس از اجرای یک دستور پیشین \f[B]DISABLE\f[R].
.SS RECONNECT [db]
بستن هر اتصالِ باز سرور برای پایگاه‌دادهٔ ارائه‌شده، یا تمام پایگاه‌های داده، پس از آزاد شدن آن (با توجه به حالت تجمیع)، حتی اگر طول عمر آن هنوز به پایان نرسیده باشد.
اتصالات سرور جدید می‌توانند بلافاصله برقرار شوند و در صورت نیاز بر اساس تنظیمات اندازهٔ استخر متصل خواهند شد.
.PP
این دستور زمانی سودمند است که پیکربندی اتصال سرور تغییر کرده باشد، برای نمونه هنگام انتقال تدریجی به یک سرور جدید.
زمانی که رشتهٔ اتصال در pgbouncer.ini تغییر کرده و بازخوانی شده باشد (نگاه کنید به
\f[B]RELOAD\f[R]) یا زمانی که تفکیک نام DNS تغییر کرده باشد، اجرای این دستور لازم \f[I]نیست\f[R]، چرا که در این حالت معادل این دستور به صورت خودکار اجرا خواهد شد.
این دستور تنها زمانی لازم است که چیزی در پایین‌دست PgBouncer اتصالات را مسیریابی کند.
.PP
پس از اجرای این دستور، ممکن است یک دورهٔ طولانی پیش آید که در آن برخی اتصالات سرور به مقصد قدیمی و برخی اتصالات سرور به مقصد جدید بروند.
این معمولاً تنها هنگام جابه‌جایی ترافیک فقط‌خواندنی میان نسخه‌های رونوشت فقط‌خواندنی، یا هنگام جابه‌جایی میان گره‌های یک پیکربندی همانندسازی چنداربابی معقول است.
اگر لازم است تمام اتصالات هم‌زمان جابه‌جا شوند، در عوض استفاده از \f[B]PAUSE\f[R]
توصیه می‌شود.
برای بستن اتصالات سرور بدون انتظار (برای نمونه در سناریوهای بازگردانی پس از خرابی اضطراری به‌جای انتقال تدریجی)، دستور
\f[B]KILL\f[R] را نیز در نظر بگیرید.
.SS KILL [db]
قطع فوری تمام اتصالات کلاینت و سرور روی پایگاه‌دادهٔ مشخص‌شده یا تمام پایگاه‌های داده، به جز پایگاه‌دادهٔ admin.
.PP
اتصالات جدید کلاینت به پایگاه‌داده‌ای که اتصالات آن قطع شده است، تا زمان فراخوانی
\f[B]RESUME\f[R] در انتظار خواهند ماند.
.SS KILL_CLIENT id
قطع فوری اتصال کلاینت مشخص‌شده به همراه هرگونه اتصال سرور برای آن کلاینت.
کلاینتی که باید اتصالش قطع شود، با مقدار \f[CR]id\f[R] که با استفاده از دستور \f[CR]SHOW CLIENTS\f[R] قابل یافتن است، شناسایی می‌شود.
.PP
یک دستور نمونه چیزی شبیه به \f[CR]KILL_CLIENT 1234\f[R] خواهد بود.
.SS SUSPEND
تمام بافرهای سوکت تخلیه می‌شوند و PgBouncer گوش دادن به داده‌ها روی آن‌ها را متوقف می‌کند.
این دستور تا پیش از خالی شدن تمام بافرها به پایان نخواهد رسید.
برای استفاده در هنگام راه‌اندازی مجدد برخط PgBouncer.
.PP
اتصالات جدید کلاینت به یک پایگاه‌دادهٔ تعلیق‌شده تا زمان فراخوانی
\f[B]RESUME\f[R] در انتظار خواهند ماند..SS RESUME [db]
از سرگیری کار متوقف‌شده از دستور پیشین \f[B]KILL\f[R]، \f[B]PAUSE\f[R] یا
\f[B]SUSPEND\f[R].
.SS SHUTDOWN
فرایند PgBouncer خارج خواهد شد.
.SS SHUTDOWN WAIT_FOR_SERVERS
توقف پذیرش اتصال‌های جدید و خاموش شدن پس از آزاد شدن تمام سرورها.
این دستور اساساً مشابه اجرای \f[B]PAUSE\f[R] و
\f[B]SHUTDOWN\f[R] است، با این تفاوت که هم‌زمان با انتظار برای \f[B]PAUSE\f[R]،
پذیرش اتصال‌های جدید را نیز متوقف می‌کند و همچنین کلاینت‌هایی را که در انتظار
دریافت اتصال سرور هستند، فوراً قطع می‌نماید.
لطفاً توجه داشته باشید که سوکت‌های UNIX در طول فرایند خاموش شدن باز باقی خواهند ماند
اما تنها اتصال‌ها به کنسول مدیریتی PgBouncer را خواهند پذیرفت.
.SS SHUTDOWN WAIT_FOR_CLIENTS
توقف پذیرش اتصال‌های جدید و خاموش کردن فرایند به محض قطع اتصال تمام
کلاینت‌های موجود.
لطفاً توجه داشته باشید که سوکت‌های UNIX در طول فرایند خاموش شدن باز باقی می‌مانند
اما تنها اتصال‌ها به کنسول مدیریتی pgbouncer را می‌پذیرند.
از این دستور می‌توان برای راه‌اندازی مجدد چرخشیِ بدون توقف (zero\-downtime rolling restart)
دو فرایند PgBouncer با استفاده از مراحل زیر استفاده کرد:
.IP "1." 3
اجرای دو یا چند فرایند PgBouncer روی یک درگاه یکسان با استفاده از
\f[CR]so_reuseport\f[R] (پیکربندی peering توصیه می‌شود، اما
الزامی نیست).
برای دستیابی به عدم قطعی سرویس هنگام راه‌اندازی مجدد، این فرایندها را
یکی‌یکی راه‌اندازی مجدد می‌کنیم؛ بنابراین در حالی که یکی در حال راه‌اندازی مجدد است،
سایرین برای پذیرش اتصال‌ها در حال اجرا باقی می‌مانند.
.IP "2." 3
یک فرایند را برای شروع راه‌اندازی مجدد انتخاب کنید، بیایید آن را A بنامیم.
.IP "3." 3
دستور \f[CR]SHUTDOWN WAIT_FOR_CLIENTS\f[R] را برای فرایند A اجرا کنید
(یا به آن سیگنال \f[CR]SIGTERM\f[R] بفرستید).
.IP "4." 3
کاری کنید که همه کلاینت‌ها دوباره متصل شوند.
احتمالاً با مدتی صبر کردن تا استخر اتصال سمت کلاینت به دلیل
\f[CR]server_idle_timeout\f[R] خود (یا پیکربندی مشابه) اتصال‌های مجدد برقرار کند.
یا در صورتی که از استخر اتصال سمت کلاینت استفاده نمی‌شود، احتمالاً با راه‌اندازی مجدد کلاینت‌ها.
پس از اتصال مجدد همه کلاینت‌ها،
فرایند A به‌طور خودکار خارج خواهد شد، زیرا دیگر هیچ کلاینتی به آن
متصل نیست.
.IP "5." 3
فرایند A را دوباره آغاز کنید.
.IP "6." 3
مراحل ۳، ۴ و ۵ را برای هر یک از فرایندهای باقیمانده، یکی پس از دیگری
تکرار کنید تا زمانی که تمام فرایندها را مجدداً راه‌اندازی کرده باشید.
.SS RELOAD
فرایند PgBouncer فایل‌های پیکربندی خود را دوباره بارگذاری کرده و
تنظیمات قابل‌تغییر را به‌روزرسانی می‌کند.
این شامل فایل پیکربندی اصلی و همچنین فایل‌های مشخص‌شده توسط
تنظیمات \f[CR]auth_file\f[R] و \f[CR]auth_hba_file\f[R] می‌شود.
.PP
PgBouncer متوجه می‌شود که بارگذاری مجدد فایل پیکربندی، پارامترهای
اتصال یک تعریف پایگاه داده را تغییر داده است.
اتصال موجود سرور به مقصد قدیمی، در آزادسازی بعدی اتصال سرور (مطابق با حالت pooling)
بسته خواهد شد، و اتصال‌های سرور جدید فوراً از پارامترهای اتصال
به‌روزرسانی‌شده استفاده خواهند کرد.
.SS WAIT_CLOSE [db]
صبر می‌کند تا تمام اتصال‌های سرور، چه برای پایگاه داده مشخص‌شده یا
تمام پایگاه‌های داده، وضعیت \[lq]close_needed\[rq] را پاک کنند (ببینید
\f[B]SHOW SERVERS\f[R]).
این دستور را می‌توان پس از \f[B]RECONNECT\f[R] یا \f[B]RELOAD\f[R] فراخوانی کرد تا
تا زمان اعمال کامل تغییر پیکربندی مربوطه منتظر ماند؛
به عنوان مثال در اسکریپت‌های switchover.
.SS دستورهای دیگر (Other commands)
.SS SET key = arg
یک تنظیم پیکربندی را تغییر می‌دهد (همچنین ببینید \f[B]SHOW CONFIG\f[R]).
برای مثال:
.IP
.EX
SET log_connections = 1;
SET server_check_query = \[aq]select 2\[aq];
.EE
.PP
(توجه داشته باشید که این دستور در کنسول مدیریتی PgBouncer اجرا می‌شود و
تنظیمات PgBouncer را مشخص می‌کند.
دستور \f[B]SET\f[R] اجرا شده روی پایگاه داده‌ای دیگر، مانند هر دستور SQL دیگر
به بک‌اند PostgreSQL ارسال خواهد شد.)
.SS سیگنال‌ها (Signals)
.TP
SIGHUP
بارگذاری مجدد پیکربندی.
مشابه اجرای دستور \f[B]RELOAD\f[R] در کنسول.
.TP
SIGTERM
خاموش شدن فوق‌العاده امن (Super safe shutdown).
صبر می‌کند تا تمام کلاینت‌های موجود قطع شوند، اما اتصال‌های جدید را
نمی‌پذیرد.
این سیگنال معادل اجرای \f[B]SHUTDOWN WAIT_FOR_CLIENTS\f[R] در
کنسول است.
اگر این سیگنال زمانی دریافت شود که فرایند خاموش‌شدن از قبل در
جریان است، آن‌گاه به جای \[lq]خاموش شدن فوق‌العاده امن\[rq] یک \[lq]خاموش شدن فوری\[rq]
فعال می‌شود.
در نسخه‌های PgBouncer قدیمی‌تر از 1.23.0، این سیگنال باعث یک
\[lq]خاموش شدن فوری\[rq] می‌شد.
.TP
SIGINT
خاموش شدن امن (Safe shutdown).
مشابه اجرای \f[B]SHUTDOWN WAIT_FOR_SERVERS\f[R] در کنسول.
اگر این سیگنال زمانی دریافت شود که فرایند خاموش‌شدن از قبل در
جریان است، آن‌گاه به جای \[lq]خاموش شدن امن\[rq] یک \[lq]خاموش شدن فوری\[rq]
فعال می‌شود.
.TP
SIGQUIT
خاموش شدن فوری (Immediate shutdown).
مشابه اجرای \f[B]SHUTDOWN\f[R] در کنسول.
.TP
SIGUSR1
مشابه اجرای \f[B]PAUSE\f[R] در کنسول.
.TP
SIGUSR2
مشابه اجرای \f[B]RESUME\f[R] در کنسول.
.SS تنظیمات Libevent (Libevent settings)
از مستندات Libevent:
.RS
.PP
غیرفعال کردن پشتیبانی از epoll، kqueue، devpoll، poll یا
select به ترتیب با تنظیم متغیر محیطی EVENT_NOEPOLL،
EVENT_NOKQUEUE، EVENT_NODEVPOLL، EVENT_NOPOLL یا EVENT_NOSELECT
امکان‌پذیر است.
.PP
با تنظیم متغیر محیطی EVENT_SHOW_METHOD، کتابخانه libevent روش
اعلان کرنل مورد استفاده خود را نمایش می‌دهد.
.RE.SH "همچنین ببینید (SEE ALSO)"
pgbouncer(5) \- صفحه راهنمای توضیحات تنظیمات پیکربندی
.PP
\c
.UR https://www.pgbouncer.org
.UE \c