.\" Automatically generated by Pandoc 3.6
.\"
.TH "PGBOUNCER.INI" "5" "" "1.25.2" "Databases"
.SH "نام (NAME)"
pgbouncer \- فایل پیکربندی pgbouncer
.SH "توضیحات (DESCRIPTION)"
این فایل پیکربندی در قالب \[lq]ini\[rq] است.
نام بخش‌ها درون \[lq][\[rq] و \[rq]]\[rq] قرار می‌گیرند.
خطوطی که با \[lq];\[rq] یا \[lq]#\[rq] آغاز می‌شوند به عنوان کامنت در نظر گرفته شده و
نادیده گرفته می‌شوند.
نویسه‌های \[lq];\[rq] و \[lq]#\[rq] اگر در ادامه خط ظاهر شوند،
به عنوان نویسه ویژه شناخته نمی‌شوند.
.SH "تنظیمات عمومی (GENERIC SETTINGS)"
.SS logfile
فایل گزارش (log file) را مشخص می‌کند.
برای اجرای دیمن (\f[CR]\-d\f[R])، باید این گزینه یا \f[CR]syslog\f[R]
تنظیم شده باشد.
.PP
فایل لاگ باز نگه داشته می‌شود، بنابراین پس از چرخش لاگ‌ها (log rotation)، باید از دستور
\f[CR]kill \-HUP\f[R] یا در کنسول از \f[CR]RELOAD;\f[R] استفاده شود.
در ویندوز، سرویس باید متوقف شده و مجدداً راه‌اندازی گردد.
.PP
توجه داشته باشید که تنظیم \f[CR]logfile\f[R] به خودی خود ارسال لاگ‌ها به
stderr را متوقف نمی‌کند.
برای این کار از گزینه خط فرمان \f[CR]\-q\f[R] یا \f[CR]\-d\f[R] استفاده کنید.
.PP
پیش‌فرض: تنظیم نشده
.SS pidfile
فایل PID را مشخص می‌کند.
بدون تنظیم \f[CR]pidfile\f[R]، اجرای دیمن (\f[CR]\-d\f[R]) مجاز
نیست.
.PP
پیش‌فرض: تنظیم نشده
.SS listen_addr
فهرستی (جداشده با کاما) از نشانی‌هایی را مشخص می‌کند که باید برای اتصالات TCP
شنود شوند.
همچنین می‌توانید از \f[CR]*\f[R] به معنای \[lq]شنود روی تمام نشانی‌ها\[rq] استفاده کنید.
در صورت عدم تنظیم، تنها اتصالات سوکت یونیکس پذیرفته می‌شوند.
.PP
نشانی‌ها را می‌توان به صورت عددی (IPv4/IPv6) یا با نام مشخص کرد.
.PP
پیش‌فرض: تنظیم نشده
.SS listen_port
پورتی که باید روی آن شنود انجام شود.
هم برای TCP و هم سوکت‌های یونیکس اعمال می‌شود.
.PP
پیش‌فرض: 6432
.SS unix_socket_dir
محل قرارگیری سوکت‌های یونیکس را مشخص می‌کند.
هم برای سوکت شنود و هم برای اتصالات سرور اعمال می‌شود.
اگر روی یک رشته خالی تنظیم شود، سوکت‌های یونیکس غیرفعال می‌شوند.
مقداری که با \f[CR]\[at]\f[R] آغاز شود، مشخص می‌کند که باید یک سوکت یونیکس
در فضای نام انتزاعی (abstract namespace) ایجاد شود (در حال حاضر در
لینوکس و ویندوز پشتیبانی می‌شود).
.PP
برای اینکه راه‌اندازی مجدد برخط (\f[CR]\-R\f[R]) کار کند، یک سوکت یونیکس باید
پیکربندی شده باشد و در فضای نام فایل‌سیستم قرار داشته باشد.
.PP
پیش‌فرض: \f[CR]/tmp\f[R] (در ویندوز خالی)
.SS unix_socket_mode
حالت دسترسی فایل‌سیستم برای سوکت یونیکس.
برای سوکت‌های موجود در فضای نام انتزاعی نادیده گرفته می‌شود.
در ویندوز پشتیبانی نمی‌شود.
.PP
پیش‌فرض: 0777
.SS unix_socket_group
نام گروه مورد استفاده برای سوکت یونیکس.
برای سوکت‌های موجود در فضای نام انتزاعی نادیده گرفته می‌شود.
در ویندوز پشتیبانی نمی‌شود.
.PP
پیش‌فرض: تنظیم نشده
.SS user
در صورت تنظیم، کاربر یونیکس را برای تغییر هویت پس از راه‌اندازی مشخص می‌کند.
تنها در صورتی کار می‌کند که PgBouncer به عنوان ریشه (root) آغاز شده باشد یا از قبل
با کاربر مشخص‌شده در حال اجرا باشد.
در ویندوز پشتیبانی نمی‌شود.
.PP
پیش‌فرض: تنظیم نشده
.SS pool_mode
مشخص می‌کند که چه زمانی یک اتصال سرور می‌تواند توسط کلاینت‌های دیگر مجدداً استفاده شود.
.TP
session
اتصال سرور پس از قطع اتصال کلاینت، به استخر بازگردانده می‌شود.
پیش‌فرض.
.TP
transaction
اتصال سرور پس از پایان تراکنش، به استخر بازگردانده می‌شود.
.TP
statement
اتصال سرور پس از پایان پرس‌وجو، به استخر بازگردانده می‌شود.
تراکنش‌هایی که شامل چندین عبارت دستوری هستند در این حالت مجاز نیستند.
.SS max_client_conn
حداکثر تعداد مجاز اتصالات کلاینت.
.PP
هنگامی که این تنظیم افزایش می‌یابد، ممکن است محدودیت توصیف‌گرهای فایل (file descriptor) در
سیستم‌عامل نیز نیاز به افزایش داشته باشد.
توجه داشته باشید که تعداد توصیف‌گرهای فایل بالقوه مورد استفاده بیش از
\f[CR]max_client_conn\f[R] است.
اگر هر کاربر با نام کاربری خود به سرور متصل شود،
حداکثر نظری استفاده‌شده برابر است با:
.IP
.EX
max_client_conn + (max pool_size * total databases * total users)
.EE
.PP
اگر یک کاربر پایگاه‌داده در رشته اتصال مشخص شده باشد (تمام کاربران
با یک نام کاربری یکسان متصل شوند)، حداکثر نظری برابر است با:
.IP
.EX
max_client_conn + (max pool_size * total databases)
.EE
.PP
حداکثر مقدار نظری هرگز نباید رخ دهد، مگر اینکه شخصی
عمداً بار کاری ویژه‌ای برای آن ایجاد کرده باشد.
با این وجود، به این معنی است که باید تعداد توصیف‌گرهای فایل را روی مقداری
به اندازه کافی بالا و ایمن تنظیم کنید.
.PP
برای اطلاعات بیشتر، \f[CR]ulimit\f[R] را در صفحه راهنمای پوسته مورد علاقه خود جستجو کنید.
نکته: دستور \f[CR]ulimit\f[R] در محیط ویندوز اعمال نمی‌شود.
.PP
پیش‌فرض: 100
.SS default_pool_size
حداکثر تعداد اتصالات سرور مجاز به ازای هر جفت کاربر/پایگاه‌داده.
می‌تواند توسط \f[CR]pool_size\f[R] در پیکربندی به ازای هر پایگاه‌داده و
به ازای هر کاربر بازنویسی شود؛ این مقدار پیش‌فرضی است که در صورت عدم تعیین مشخص
\f[CR]pool_size\f[R] برای یک پایگاه‌داده یا کاربر معین، استفاده می‌شود.
.PP
پیش‌فرض: 20
.SS min_pool_size
اگر تعداد اتصالات سرور کمتر از این مقدار باشد، اتصالات بیشتری به استخر اضافه می‌کند.
رفتار سیستم را زمانی که بار کاری عادی پس از دوره‌ای از عدم فعالیت کامل ناگهان بازمی‌گردد،
بهبود می‌بخشد.
این مقدار عملاً در سقف اندازه استخر (pool size) محدود می‌شود.
.PP
تنها برای استخرهایی اعمال می‌شود که حداقل یکی از موارد زیر برقرار باشد:
.IP \[bu] 2
مدخل مربوطه در بخش \f[CR][database]\f[R] برای آن استخر، مقداری برای کلید
\f[CR]user\f[R] تنظیم کرده باشد (کاربر اجباری).
.IP \[bu] 2
حداقل یک کلاینت به استخر متصل باشد.
.PP
پیش‌فرض: 0 (غیرفعال)
.SS reserve_pool_size
چه تعداد اتصال اضافی به یک استخر مجاز است (گزینه
\f[CR]reserve_pool_timeout\f[R] را ببینید).
مقدار 0 آن را غیرفعال می‌کند.
.PP
پیش‌فرض: 0 (غیرفعال)
.SS reserve_pool_timeout
اگر کلاینتی در این مدت سرویس دریافت نکند، از اتصالات اضافی
استخر ذخیره استفاده می‌شود.
مقدار 0 آن را غیرفعال می‌کند.
[ثانیه]
.PP
پیش‌فرض: 5.0
.SS max_db_connections
اجازه ندهید تعداد اتصالات سرور به ازای هر پایگاه‌داده بیش از این مقدار شود
(صرف‌نظر از کاربر).
این گزینه پایگاه‌داده PgBouncer را که کلاینت به آن متصل شده در نظر می‌گیرد،
نه پایگاه‌داده PostgreSQL اتصال خروجی را.
.PP
این گزینه را می‌توان به ازای هر پایگاه‌داده در بخش \f[CR][databases]\f[R] نیز تنظیم کرد.
.PP
توجه داشته باشید که با رسیدن به این محدودیت، بستن اتصال یک کلاینت به یک
استخر بلافاصله اجازه برقراری اتصال سرور برای استخر دیگری را نمی‌دهد،
زیرا اتصال سرور برای استخر اول همچنان باز است.
به محض اینکه اتصال سرور (به دلیل مهلت عدم فعالیت) بسته شود، بلافاصله یک اتصال سرور
جدید برای استخر در حال انتظار باز خواهد شد.
.PP
پیش‌فرض: 0 (نامحدود)
.SS max_db_client_connections
اجازه ندهید اتصالات کلاینت به PgBouncer به ازای هر پایگاه‌داده بیش از این مقدار شود
(صرف‌نظر از کاربر).
این گزینه پایگاه‌داده PgBouncer را که کلاینت به آن متصل شده در نظر می‌گیرد،
نه پایگاه‌داده PostgreSQL اتصال خروجی را.
.PP
این مقدار باید روی عددی بزرگ‌تر یا مساوی با
max_db_connections تنظیم شود.
تفاوت بین این دو عدد را می‌توان به عنوان تعداد اتصالاتی در نظر گرفت که می‌توانند در صف
یک پایگاه‌داده مشخص در انتظار اتمام اتصالات فعال باقی بمانند.
.PP
این گزینه را می‌توان به ازای هر پایگاه‌داده در بخش \f[CR][databases]\f[R] نیز تنظیم کرد.
.PP
پیش‌فرض: 0 (نامحدود)
.SS max_user_connections
اجازه ندهید تعداد اتصالات سرور به ازای هر کاربر بیش از این مقدار شود (صرف‌نظر
از پایگاه‌داده).
این گزینه کاربر PgBouncer مرتبط با یک استخر را در نظر می‌گیرد که یا
کاربر مشخص‌شده برای اتصال سرور است یا در غیاب آن، کاربری است که کلاینت با آن متصل شده است.
.PP
این گزینه را می‌توان به ازای هر کاربر در بخش \f[CR][users]\f[R] نیز تنظیم کرد.
.PP
توجه داشته باشید که با رسیدن به این محدودیت، بستن اتصال یک کلاینت به یک
استخر بلافاصله اجازه برقراری اتصال سرور برای استخر دیگری را نمی‌دهد،
زیرا اتصال سرور برای استخر اول همچنان باز است.
به محض اینکه اتصال سرور (به دلیل مهلت عدم فعالیت) بسته شود، بلافاصله یک اتصال سرور
جدید برای استخر در حال انتظار باز خواهد شد.
.PP
پیش‌فرض: 0 (نامحدود)
.SS max_user_client_connections
اجازه ندهید اتصالات کلاینت به ازای هر کاربر بیش از این مقدار شود (صرف‌نظر
از پایگاه‌داده).
این مقدار باید روی عددی بزرگ‌تر از max_user_connections تنظیم شود.
تفاوت بین max_user_connections و
max_user_client_connections را می‌توان به عنوان حداکثر
اندازه صف برای کاربر در نظر گرفت.
.PP
این گزینه را می‌توان به ازای هر کاربر در بخش \f[CR][users]\f[R] نیز تنظیم کرد.
.PP
پیش‌فرض: 0 (نامحدود)
.SS server_round_robin
به طور پیش‌فرض، PgBouncer از اتصالات سرور به روش LIFO (آخرین ورودی،
اولین خروجی) مجدداً استفاده می‌کند تا اتصالات کمتری بیشترین بار کاری را دریافت کنند.
این روش در صورتی که یک سرور منفرد سرویس‌دهنده به پایگاه‌داده داشته باشید،
بهترین کارایی را به همراه دارد.
اما اگر سیستم نوبت‌گردشی (round\-robin) در پشت نشانی پایگاه‌داده وجود داشته باشد (TCP،
DNS یا فهرستی از میزبان‌ها)، بهتر است PgBouncer نیز اتصالات را به همین شیوه
استفاده کند تا بار کاری یکنواختی حاصل شود.
.PP
پیش‌فرض: 0
.SS track_extra_parameters
به طور پیش‌فرض، PgBouncer پارامترهای \f[CR]client_encoding\f[R]،
\f[CR]datestyle\f[R]، \f[CR]timezone\f[R]،
\f[CR]standard_conforming_strings\f[R] و \f[CR]application_name\f[R]
را به ازای هر کلاینت رهگیری می‌کند.
برای اینکه امکان رهگیری سایر پارامترها نیز فراهم شود، می‌توان آن‌ها را در اینجا مشخص کرد تا
PgBouncer بداند که باید در حافظه نهان متغیرهای کلاینت نگهداری شده و هر زمان که کلاینت
فعال شد در سرور بازیابی شوند.
.PP
اگر نیاز به تعیین چندین مقدار دارید، از یک فهرست جداشده با کاما استفاده کنید
(مانند
\f[CR]default_transaction_read_only, IntervalStyle\f[R])
.PP
نکته: بیشتر پارامترها را نمی‌توان از این طریق رهگیری کرد.
تنها پارامترهایی قابل رهگیری هستند که Postgres به کلاینت گزارش می‌دهد.
پستگرس \c
.UR https://www.postgresql.org/docs/15/protocol-flow.html#PROTOCOL-ASYNC
فهرست رسمی از پارامترهایی که به کلاینت گزارش می‌دهد
.UE \c
\& دارد.
با این حال، افزونه‌های Postgres می‌توانند این فهرست را تغییر دهند؛ آن‌ها می‌توانند پارامترهایی
را خودشان اضافه کرده و گزارش دهند، و می‌توانند شروع به گزارش پارامترهای از قبل
موجودی کنند که Postgres گزارش نمی‌دهد.
به ویژه Citus 12.0+ باعث می‌شود Postgres پارامتر
\f[CR]search_path\f[R] را نیز گزارش دهد.
.PP
پروتکل Postgres امکان تعیین تنظیمات پارامترها را فراهم می‌کند؛ هم
مستقیماً به عنوان یک پارامتر در بسته راه‌اندازی (startup packet)، و هم درون بسته راه‌اندازی \c
.UR https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-OPTIONS
\f[CR]options\f[R]
.UE \c
\&.
پارامترهایی که با استفاده از هر دو روش مشخص شده‌اند توسط
\f[CR]track_extra_parameters\f[R] پشتیبانی می‌شوند.
با این وجود، گنجاندن خود \f[CR]options\f[R] در
\f[CR]track_extra_parameters\f[R] امکان‌پذیر نیست و فقط پارامترهای موجود در
\f[CR]options\f[R] مجاز هستند.
.PP
پیش‌فرض: IntervalStyle
.SS ignore_startup_parameters
به طور پیش‌فرض، PgBouncer تنها به پارامترهایی در بسته‌های راه‌اندازی اجازه می‌دهد که بتواند
آن‌ها را رهگیری کند: \f[CR]client_encoding\f[R]، \f[CR]datestyle\f[R]،
\f[CR]timezone\f[R] و \f[CR]standard_conforming_strings\f[R].
تمام پارامترهای دیگر خطایی ایجاد خواهند کرد.
برای مجاز کردن پارامترهای دیگر، می‌توان آن‌ها را در اینجا مشخص کرد تا
PgBouncer بداند توسط مدیر سیستم مدیریت می‌شوند و می‌تواند آن‌ها را
نادیده بگیرد.
.PP
اگر نیاز به تعیین چندین مقدار دارید، از یک فهرست جداشده با کاما استفاده کنید
(مانند
\f[CR]options,extra_float_digits\f[R])
.PP
پروتکل Postgres امکان تعیین تنظیمات پارامترها را فراهم می‌کند؛ هم
مستقیماً به عنوان یک پارامتر در بسته راه‌اندازی، و هم درون بسته راه‌اندازی \c
.UR https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-OPTIONS
\f[CR]options\f[R]
.UE \c
\&.
پارامترهایی که با استفاده از هر دو روش مشخص شده‌اند توسط
\f[CR]ignore_startup_parameters\f[R] پشتیبانی می‌شوند.
حتی امکان گنجاندن خود \f[CR]options\f[R] در
\f[CR]track_extra_parameters\f[R] نیز وجود دارد که باعث می‌شود هر پارامتر ناشناخته
موجود در \f[CR]options\f[R] نادیده گرفته شود.
.PP
پیش‌فرض: خالی
.SS peer_id
شناسه همتا (peer id) برای شناسایی این فرآیند PgBouncer در گروهی از
فرآیندهای همتای PgBouncer استفاده می‌شود.
مقدار \f[CR]peer_id\f[R] باید درون یک گروه از فرآیندهای همتای
PgBouncer یکتا باشد.
هنگامی که روی 0 تنظیم شود، قابلیت همتایی PgBouncer غیرفعال است.
برای اطلاعات بیشتر، اسناد بخش \f[CR][peers]\f[R] را ببینید.
حداکثر مقداری که می‌تواند برای \f[CR]peer_id\f[R] استفاده شود 16383 است.
.PP
پیش‌فرض: 0
.SS disable_pqexec
غیرفعال کردن پروتکل پرس‌وجوی ساده (Simple Query protocol یا PQexec).
برخلاف پروتکل پرس‌وجوی گسترده (Extended Query protocol)، پروتکل پرس‌وجوی ساده اجازه اجرای چندین پرس‌وجو
در یک بسته را می‌دهد که امکان برخی از انواع حملات تزریق SQL (SQL-injection) را فراهم می‌کند.
غیرفعال کردن آن می‌تواند امنیت را بهبود ببخشد.
بدیهی است این به این معنی است که تنها کلاینت‌هایی که منحصراً از پروتکل پرس‌وجوی گسترده
استفاده می‌کنند به کار خود ادامه خواهند داد.
.PP
پیش‌فرض: 0
.SS application_name_add_host
افزودن نشانی میزبان و پورت کلاینت به تنظیم application name که در
ابتدای برقراری اتصال تعیین می‌شود.
این کار به شناسایی منبع پرس‌وجوهای نامناسب و مواردی از این دست کمک می‌کند.
این منطق تنها در ابتدای اتصال اعمال می‌شود.
اگر \f[CR]application_name\f[R] بعداً با دستور \f[CR]SET\f[R] تغییر کند،
PgBouncer مجدداً آن را تغییر نمی‌دهد.
.PP
پیش‌فرض: 0
.SS conffile
محل فایل پیکربندی فعلی را نشان می‌دهد.
تغییر آن باعث می‌شود PgBouncer در دستور بعدی \f[CR]RELOAD\f[R] یا \f[CR]SIGHUP\f[R] از
فایل پیکربندی دیگری استفاده کند.
.PP
پیش‌فرض: فایل مشخص‌شده از خط فرمان
.SS service_name
مورد استفاده در ثبت سرویس در سیستم‌های win32.
.PP
پیش‌فرض: \f[CR]pgbouncer\f[R]
.SS job_name
نام مستعار برای \f[CR]service_name\f[R].
.SS stats_period
مشخص می‌کند که میانگین‌های نمایش‌داده‌شده در دستورات مختلف \f[CR]SHOW\f[R]
هر چند وقت یک‌بار به‌روزرسانی شوند و آمار تجمیعی هر چند وقت یک‌بار در لاگ نوشته شوند
(اما گزینه \f[CR]log_stats\f[R] را نیز ببینید).
[ثانیه]
.PP
پیش‌فرض: 60
.SS max_prepared_statements
هنگامی که این مقدار روی یک مقدار غیر صفر تنظیم شود، PgBouncer دستورات مرتبط با عبارات آماده‌شده
(prepared statements) نام‌گذاری‌شده در سطح پروتکل را که توسط کلاینت در حالت‌های استخربندی
تراکنش (transaction) و عبارت (statement) ارسال می‌شوند، رهگیری می‌کند.
PgBouncer اطمینان حاصل می‌کند که هر عبارت آماده‌شده توسط کلاینت،
روی اتصال سرور پشتیبان در دسترس باشد؛
حتی زمانی که عبارت در ابتدا روی اتصال سرور دیگری آماده شده باشد.
.PP
PgBouncer به صورت داخلی تمام پرس‌وجوهایی را که توسط کلاینت‌ها به عنوان یک عبارت آماده‌شده
ارسال می‌شوند بررسی می‌کند و به هر رشته پرس‌وجوی یکتا، یک نام داخلی
با قالب \f[CR]PGBOUNCER_{unique_id}\f[R] اختصاص می‌دهد.
اگر همان رشته پرس‌وجو چندین بار آماده شود (احتمالاً توسط کلاینت‌های مختلف)،
این پرس‌وجوها نام داخلی یکسانی را به اشتراک می‌گذارند.
PgBouncer عبارت را تنها روی سرور واقعی PostgreSQL با استفاده از نام داخلی
(و نه نام ارائه‌شده توسط کلاینت) آماده می‌کند.
PgBouncer نامی را که کلاینت به هر عبارت آماده‌شده داده است رهگیری می‌کند.
سپس هر دستوری را که از یک عبارت آماده‌شده استفاده می‌کند، با جایگزین کردن
نام سمت کلاینت با نام داخلی (برای مثال
جایگزینی \f[CR]my_prepared_statement\f[R] با
\f[CR]PGBOUNCER_123\f[R]) پیش از ارسال آن دستور به سرور، بازنویسی می‌کند.
مهم‌تر از همه، اگر عبارت آماده‌شده‌ای که کلاینت می‌خواهد اجرا کند هنوز روی سرور آماده
نشده باشد (مثلاً به این دلیل که سرور متفاوتی نسبت به زمان آماده‌سازی عبارت به کلاینت
اختصاص یافته است)، PgBouncer پیش از اجرای عبارت، آن را به طور شفاف آماده می‌کند.
.PP
نکته: این رهگیری و بازنویسی دستورات عبارت آماده‌شده برای دستورات عبارت آماده‌شده در
سطح SQL کار نمی‌کند، بنابراین دستورات
\f[CR]PREPARE\f[R]، \f[CR]EXECUTE\f[R] و \f[CR]DEALLOCATE\f[R] مستقیماً
به Postgres ارسال می‌شوند.
استثنای این قاعده دستورات \f[CR]DEALLOCATE ALL\f[R] و
\f[CR]DISCARD ALL\f[R] هستند؛ این دستورات مطابق انتظار عمل کرده و عبارات
آماده‌شده‌ای را که PgBouncer برای کلاینت ارسال‌کننده رهگیری کرده است، پاک می‌کنند.
.PP
مقدار واقعی این تنظیم تعداد عبارات آماده‌شده‌ای را کنترل می‌کند که در یک حافظه نهان LRU
روی یک اتصال سرور منفرد فعال نگه داشته می‌شوند.
هنگامی که این تنظیم روی 0 باشد، پشتیبانی از عبارت آماده‌شده برای استخربندی تراکنش
و عبارت غیرفعال است.
برای دستیابی به بهترین کارایی، باید سعی کنید مطمئن شوید که این تنظیم بزرگ‌تر از
تعداد عبارات آماده‌شده متداول مورد استفاده در برنامه شما است.
به خاطر داشته باشید که هر چه این مقدار بالاتر باشد، ردپای حافظه هر اتصال
PgBouncer روی سرور PostgreSQL شما بزرگ‌تر خواهد بود، زیرا پرس‌وجوهای بیشتری را
روی آن اتصالات آماده نگه می‌دارد.
همچنین ردپای حافظه خود PgBouncer را افزایش می‌دهد، زیرا اکنون نیاز به رهگیری
رشته‌های پرس‌وجو دارد.
.PP
با این حال، تأثیر آن بر مصرف حافظه PgBouncer چندان زیاد نیست: \- هر
پرس‌وجوی یکتا یک بار در حافظه نهان سراسری پرس‌وجو ذخیره می‌شود.
\- هر اتصال کلاینت بافری را نگه می‌دارد که از آن برای بازنویسی بسته‌ها
استفاده می‌کند.
این مقدار حداکثر ۴ برابر اندازه \f[CR]pkt_buf\f[R] است.
این حد معمولاً پر نمی‌شود، مگر زمانی که پرس‌وجوهای موجود در عبارات آماده‌شده شما
بین ۲ تا ۴ برابر اندازه \f[CR]pkt_buf\f[R] باشند.
.PP
بنابراین اگر سناریوی زیر را به عنوان مثال در نظر بگیرید: \- ۱۰۰۰ کلاینت
فعال وجود دارد \- کلاینت‌ها ۲۰۰ پرس‌وجوی یکتا آماده می‌کنند \- میانگین
اندازه یک پرس‌وجو ۵ کیلوبایت است \- پارامتر \f[CR]pkt_buf\f[R] روی مقدار
پیش‌فرض 4096 (۴ کیلوبایت) تنظیم شده است
.PP
در این حالت، PgBouncer حداکثر به مقدار حافظه زیر برای مدیریت این عبارات آماده نیاز دارد:
.PP
200 x 5kB + 1000 x 4 x 4kB = \[ti]17MB حافظه.
.PP
رهگیری عبارات آماده‌شده نه تنها هزینه حافظه دارد، بلکه مصرف CPU را نیز
افزایش می‌دهد، زیرا PgBouncer باید پرس‌وجوها را بررسی و بازنویسی کند.
چندین نمونه PgBouncer می‌توانند روی یک پورت مشترک شنود کنند تا از بیش از
یک هسته پردازشی استفاده شود؛ برای جزئیات به اسناد گزینه
\f[CR]so_reuseport\f[R] مراجعه کنید.
.PP
اما مسلماً عبارات آماده‌شده مزایای کارایی نیز دارند.
درست همانند اتصال مستقیم به PostgreSQL، آماده‌سازی پرس‌وجویی که بارها اجرا می‌شود،
میزان کلی پارس کردن و برنامه‌ریزی اجرایی مورد نیاز را کاهش می‌دهد.
روشی که PgBouncer عبارات آماده را رهگیری می‌کند، به‌ویژه زمانی که چندین کلاینت
پرس‌وجوهای یکسانی را آماده می‌کنند، برای کارایی بسیار سودمند است؛
زیرا اتصالات کلاینت به طور خودکار از یک عبارت آماده‌شده روی یک اتصال سرور مجدداً استفاده می‌کنند،
حتی اگر توسط کلاینت دیگری آماده شده باشد.
به عنوان مثال، اگر \f[CR]pool_size\f[R] برابر با 20 داشته باشید و ۱۰۰ کلاینت
داشته باشید که همگی دقیقاً یک پرس‌وجوی یکسان را آماده می‌کنند، پرس‌وجو تنها ۲۰ بار روی
سرور PostgreSQL آماده (و بنابراین پارس) می‌شود.
.PP
استفاده مجدد از عبارات آماده‌شده یک جنبه منفی دارد.
اگر نوع داده‌های برگشتی یا آرگومان‌های یک عبارت آماده در طول اجراها تغییر کند،
PostgreSQL در حال حاضر خطایی مانند زیر صادر می‌کند:
.IP
.EX
ERROR:  cached plan must not change result type
.EE
.PP
می‌توانید با پرهیز از داشتن چندین کلاینت که از یک رشته پرس‌وجوی دقیقاً یکسان
در یک عبارت آماده استفاده می‌کنند اما انتظار انواع آرگومان یا نتیجه متفاوتی دارند، از چنین خطاهایی جلوگیری کنید.
یکی از رایج‌ترین راه‌های مواجهه با این مشکل در طول مهاجرت‌های DDL است که در آن ستون جدیدی
اضافه می‌کنید یا نوع یک ستون را در یک جدول موجود تغییر می‌دهید.
در این موارد می‌توانید پس از انجام مهاجرت، دستور \f[CR]RECONNECT\f[R] را روی کنسول
مدیریتی PgBouncer اجرا کنید تا آماده‌سازی مجدد پرس‌وجو اجباری شده و خطا برطرف شود.
.PP
پیش‌فرض: 200
.SS scram_iterations
تعداد تکرارهای محاسباتی که باید هنگام رمزگذاری گذرواژه با استفاده از
SCRAM\-SHA\-256 انجام شود.
تعداد تکرار بالاتر، محافظت بیشتری در برابر حملات جستجوی فراگیر (brute-force) روی
گذرواژه‌های ذخیره‌شده فراهم می‌کند، اما احراز هویت را کندتر می‌سازد.
.PP
پیش‌فرض: 4096
.SH "تنظیمات احراز هویت (AUTHENTICATION SETTINGS)"
PgBouncer احراز هویت کلاینت‌های خود را مستقلاً مدیریت می‌کند و پایگاه‌داده
کاربران مخصوص به خود را دارد.
این تنظیمات این بخش را کنترل می‌کنند.
.SS auth_type
نحوه احراز هویت کاربران.
.TP
cert
کلاینت باید از طریق اتصال TLS با یک گواهی کلاینت معتبر متصل شود.
سپس نام کاربری از فیلد CommonName گواهی گرفته می‌شود.
.TP
md5
استفاده از بررسی گذرواژه مبتنی بر MD5.
این روش پیش‌فرض احراز هویت است.
فایل \f[CR]auth_file\f[R] می‌تواند شامل گذرواژه‌های رمزگذاری‌شده با MD5 و متن ساده باشد.
اگر \f[CR]md5\f[R] پیکربندی شده باشد و کاربر دارای یک رمز امن SCRAM باشد، احراز هویت
SCRAM به طور خودکار به جای آن استفاده می‌شود.
.TP
scram\-sha\-256
استفاده از بررسی گذرواژه با SCRAM\-SHA\-256.
فایل \f[CR]auth_file\f[R] باید شامل مقادیر محرمانه SCRAM یا گذرواژه‌های متن ساده باشد.
.TP
plain
گذرواژه با متن ساده از طریق شبکه ارسال می‌شود.
منسوخ شده است.
.TP
trust
هیچ احراز هویتی انجام نمی‌شود.
نام کاربری همچنان باید در \f[CR]auth_file\f[R] وجود داشته باشد.
.TP
any
مانند روش \f[CR]trust\f[R] است، اما نام کاربری ارائه‌شده نادیده گرفته می‌شود.
مستلزم آن است که تمام پایگاه‌های داده برای ورود به عنوان یک کاربر خاص پیکربندی شده باشند.
علاوه بر این، پایگاه‌داده کنسول به هر کاربری اجازه می‌دهد به عنوان مدیر وارد شود.
.TP
hba
نوع واقعی احراز هویت از \f[CR]auth_hba_file\f[R] بارگیری می‌شود.
این امکان استفاده از روش‌های مختلف احراز هویت را برای مسیرهای دسترسی مختلف فراهم می‌کند،
برای مثال: اتصالات از طریق سوکت یونیکس از روش احراز هویت \f[CR]peer\f[R] استفاده کنند،
اتصالات از طریق TCP باید از TLS استفاده کنند.
.TP
ldap
کاربران در برابر یک سرور LDAP احراز هویت می‌شوند، مشابه PostgreSQL (برای جزئیات \c
.UR https://www.postgresql.org/docs/current/auth-ldap.html
.UE \c
\ را ببینید).
گزینه‌های اتصال LDAP با استفاده از تنظیم \f[CR]auth_ldap_options\f[R]، یا
به عنوان جایگزین در \f[CR]auth_hba_file\f[R] پیکربندی می‌شوند.
.TP
pam
از PAM برای احراز هویت کاربران استفاده می‌شود، \f[CR]auth_file\f[R] نادیده گرفته می‌شود.
این روش با پایگاه‌های داده‌ای که از گزینه \f[CR]auth_user\f[R] استفاده می‌کنند
سازگار نیست.
نام سرویس گزارش‌شده به PAM برابر با \[lq]pgbouncer\[rq] است.
گزینه \f[CR]pam\f[R] در فایل پیکربندی HBA پشتیبانی نمی‌شود.
.SS auth_hba_file
فایل پیکربندی HBA مورد استفاده هنگامی که \f[CR]auth_type\f[R] برابر با
\f[CR]hba\f[R] باشد.
برای جزئیات به بخش قالب فایل HBA در زیر مراجعه کنید.
.PP
پیش‌فرض: تنظیم نشده
.SS auth_ident_file
فایل نگاشت هویت (identity map) مورد استفاده هنگامی که \f[CR]auth_type\f[R] برابر با
\f[CR]hba\f[R] باشد و نگاشت کاربر تعریف شده باشد.
برای جزئیات به بخش قالب فایل نگاشت Ident در زیر مراجعه کنید.
.PP
پیش‌فرض: تنظیم نشده
.SS auth_file
نام فایلی که نام‌های کاربری و گذرواژه‌ها از آن بارگیری می‌شوند.
برای جزئیات به بخش قالب فایل احراز هویت در زیر مراجعه کنید.
.PP
بیشتر انواع احراز هویت (به موارد بالا نگاه کنید) نیازمند تنظیم
\f[CR]auth_file\f[R] یا \f[CR]auth_user\f[R] هستند؛ در غیر این صورت هیچ کاربری
تعریف نخواهد شد.
.PP
پیش‌فرض: تنظیم نشده
.SS auth_user
اگر \f[CR]auth_user\f[R] تنظیم شود، هر کاربری که در
\f[CR]auth_file\f[R] مشخص نشده باشد، از طریق پرس‌وجوی \f[CR]auth_query\f[R]
از جدول \f[CR]pg_authid\f[R] در پایگاه‌داده و با استفاده از
\f[CR]auth_user\f[R] واکشی می‌شود.
گذرواژه \f[CR]auth_user\f[R] از
\f[CR]auth_file\f[R] گرفته خواهد شد.
(اگر \f[CR]auth_user\f[R] نیازی به گذرواژه نداشته باشد، نیازی به
تعریف آن در \f[CR]auth_file\f[R] نیست.)
.PP
دسترسی مستقیم به \f[CR]pg_authid\f[R] نیازمند دسترسی‌های مدیریتی (admin) است.
ترجیح داده می‌شود از یک کاربر غیر ارشد استفاده شود که تابعی با مشخصه SECURITY
DEFINER را فراخوانی می‌کند.
.PP
پیش‌فرض: تنظیم نشده
.SS auth_query
پرس‌وجو برای بارگیری گذرواژه کاربر از پایگاه‌داده.
.PP
دسترسی مستقیم به \f[CR]pg_authid\f[R] نیازمند دسترسی‌های مدیریتی است.
ترجیح داده می‌شود از یک کاربر غیر ارشد استفاده شود که تابعی با مشخصه SECURITY
DEFINER را فراخوانی می‌کند.
.PP
توجه داشته باشید که این پرس‌وجو در داخل پایگاه‌داده مقصد اجرا می‌شود.
بنابراین اگر از تابعی استفاده می‌شود، باید در هر پایگاه‌داده نصب شده باشد.
.PP
پیش‌فرض:
\f[CR]SELECT rolname, CASE WHEN rolvaliduntil < now() THEN NULL ELSE rolpassword END FROM pg_authid WHERE rolname=$1 AND rolcanlogin\f[R]
.SS auth_dbname
نام پایگاه‌داده در بخش \f[CR][database]\f[R] که برای اهداف
احراز هویت استفاده می‌شود.
این گزینه می‌تواند سراسری باشد یا در صورت تعیین در رشته اتصال، بازنویسی شود.
.SS auth_ldap_options
گزینه‌های اتصال LDAP برای استفاده در صورتی که \f[CR]auth_type\f[R] برابر با
\f[CR]ldap\f[R] باشد.
(اگر احراز هویت از طریق \f[CR]auth_hba_file\f[R] پیکربندی شده باشد، استفاده نمی‌شود.)
مثال:
.IP
.EX
auth_ldap_options = ldapurl=\[dq]ldap://127.0.0.1:12345/dc=example,dc=net?uid?sub\[dq]
.EE
.SH "تنظیمات گزارش‌گیری (LOG SETTINGS)"
.SS syslog
فعال یا غیرفعال کردن syslog.
در ویندوز، به جای آن از event log استفاده می‌شود.
.PP
پیش‌فرض: 0
.SS syslog_ident
نامی که لاگ‌ها تحت آن به syslog ارسال می‌شوند.
.PP
پیش‌فرض: \f[CR]pgbouncer\f[R] (نام برنامه)
.SS syslog_facility
فسیلیتی (facility) مورد استفاده برای ارسال لاگ‌ها به syslog.
گزینه‌های ممکن: \f[CR]auth\f[R]، \f[CR]authpriv\f[R]، \f[CR]daemon\f[R]،
\f[CR]user\f[R]، \f[CR]local0\-7\f[R].
.PP
پیش‌فرض: \f[CR]daemon\f[R]
.SS log_connections
ثبت لاگ ورودهای موفقیت‌آمیز.
.PP
پیش‌فرض: 1
.SS log_disconnections
ثبت لاگ قطع اتصال‌ها همراه با دلیل.
.PP
پیش‌فرض: 1
.SS log_pooler_errors
ثبت لاگ پیام‌های خطایی که استخربند به کلاینت‌ها ارسال می‌کند.
.PP
پیش‌فرض: 1
.SS log_stats
نوشتن آمار تجمیعی در لاگ، در هر دوره \f[CR]stats_period\f[R].
اگر ابزارهای پایش خارجی برای دریافت همین داده‌ها از دستورات \f[CR]SHOW\f[R]
استفاده شوند، می‌توان این گزینه را غیرفعال کرد.
.PP
پیش‌فرض: 1
.SS verbose
افزایش سطح جزئیات لاگ‌ها (verbosity).
مشابه سوییچ \[lq]\-v\[rq] در خط فرمان عمل می‌کند.
برای مثال، استفاده از \[lq]\-v \-v\[rq] در خط فرمان همانند
\f[CR]verbose=2\f[R] است.
مقدار 3 بالاترین سطح جزئیات است که در حال حاضر پشتیبانی می‌شود.
.PP
پیش‌فرض: 0
.SH "کنترل دسترسی کنسول (CONSOLE ACCESS CONTROL)"
.SS admin_users
فهرست جداشده با کاما از کاربران پایگاه‌داده که مجاز به اتصال و
اجرای تمامی دستورات روی کنسول هستند.
هنگامی که \f[CR]auth_type\f[R] برابر با \f[CR]any\f[R] باشد نادیده گرفته می‌شود؛
در این حالت هر نام کاربری به عنوان مدیر پذیرفته می‌شود.
.PP
پیش‌فرض: خالی
.SS stats_users
فهرست جداشده با کاما از کاربران پایگاه‌داده که مجاز به اتصال و
اجرای پرس‌وجوهای فقط‌خواندنی روی کنسول هستند.
این شامل تمام دستورات \f[CR]SHOW\f[R] به جز \f[CR]SHOW FDS\f[R] است.
.PP
پیش‌فرض: خالی
.SH "بررسی‌های سلامت اتصال و مهلت‌های زمانی (CONNECTION SANITY CHECKS, TIMEOUTS)"
.SS server_reset_query
پرس‌وجویی که هنگام آزادسازی اتصال و پیش از در دسترس قرار دادن آن
برای کلاینت‌های دیگر، به سرور ارسال می‌شود.
در آن لحظه هیچ تراکنشی در حال انجام نیست، بنابراین این مقدار نباید شامل
\f[CR]ABORT\f[R] یا \f[CR]ROLLBACK\f[R] باشد.
.PP
این پرس‌وجو قرار است هرگونه تغییرات اعمال‌شده در نشست پایگاه‌داده را پاک کند
تا کلاینت بعدی اتصال را در یک وضعیت کاملاً مشخص و معین دریافت نماید.
مقدار پیش‌فرض \f[CR]DISCARD ALL\f[R] است که همه چیز را پاک می‌کند، اما این کار
هیچ وضعیت از پیش کش‌شده‌ای برای کلاینت بعدی باقی نمی‌گذارد.
می‌توان آن را سبک‌تر کرد، برای مثال \f[CR]DEALLOCATE ALL\f[R] تنها برای حذف
عبارات آماده، در صورتی که برنامه با حفظ برخی از وضعیت‌ها دچار اختلال نشود.
.PP
هنگامی که استخربندی تراکنش (transaction pooling) استفاده می‌شود، \f[CR]server_reset_query\f[R]
استفاده نمی‌شود، زیرا در این حالت، کلاینت‌ها نباید از هیچ‌یک از ویژگی‌های مبتنی بر
نشست استفاده کنند؛ چرا که هر تراکنش به یک اتصال متفاوت ختم شده و بنابراین
وضعیت نشست متفاوتی دریافت می‌کند.
.PP
پیش‌فرض: \f[CR]DISCARD ALL\f[R]
.SS server_reset_query_always
آیا \f[CR]server_reset_query\f[R] باید در تمام حالت‌های استخربندی
اجرا شود یا خیر.
هنگامی که این تنظیم خاموش است (پیش‌فرض)، دستور \f[CR]server_reset_query\f[R]
تنها در استخرهایی اجرا می‌شود که در حالت استخربندی نشست (session pooling) قرار دارند.
اتصالات در حالت استخربندی تراکنش نباید نیازی به پرس‌وجوی بازنشانی داشته باشند.
.PP
این تنظیم برای دور زدن پیکربندی‌های نامناسبی است که برنامه‌های استفاده‌کننده از ویژگی‌های نشست
را روی PgBouncer با استخربندی تراکنش اجرا می‌کنند.
این کار خطاهای غیر قطعی را به خطای قطعی تبدیل می‌کند:
کلاینت‌ها همیشه وضعیت خود را پس از هر تراکنش از دست می‌دهند.
.PP
پیش‌فرض: 0
.SS server_check_delay
مدت زمانی که اتصالات آزادشده بدون اجرای \f[CR]server_check_query\f[R] روی آن‌ها،
برای استفاده مجدد فوری در دسترس نگه داشته می‌شوند.
اگر 0 باشد، بررسی همیشه اجرا می‌شود.
.PP
پیش‌فرض: 30.0
.SS server_check_query
پرس‌وجوی ساده و بی‌اثر برای بررسی زنده بودن اتصال سرور.
.PP
اگر یک رشته خالی باشد، بررسی سلامت غیرفعال می‌شود.
.PP
اگر \f[CR]<empty>\f[R] باشد، یک پرس‌وجوی خالی به عنوان بررسی سلامت ارسال می‌شود.
.PP
پیش‌فرض: \f[CR]<empty>\f[R]
.SS server_fast_close
قطع اتصال فوری سرور در حالت استخربندی نشست یا پس از پایان تراکنش فعلی
در صورتی که در حالت \[lq]close_needed\[rq] باشد (تنظیم‌شده توسط
\f[CR]RECONNECT\f[R]، یا \f[CR]RELOAD\f[R] که تنظیمات اتصال را تغییر می‌دهد، یا تغییر DNS)،
به جای انتظار برای پایان نشست.
در حالت استخربندی عبارت یا تراکنش، این گزینه تاثیری ندارد زیرا رفتار پیش‌فرض در آنجا همین است.
.PP
اگر به دلیل این تنظیم یک اتصال سرور پیش از پایان نشست کلاینت بسته شود، اتصال کلاینت
نیز بسته خواهد شد.
این کار تضمین می‌کند که کلاینت متوجه قطع شدن نشست می‌شود.
.PP
این تنظیم باعث می‌شود اعمال تغییرات پیکربندی اتصال، در صورت استفاده از استخربندی نشست
و نشست‌های طولانی‌مدت، سریع‌تر اثر کند.
نقطه ضعف این است که نشست‌های کلاینت ممکن است با یک تغییر پیکربندی قطع شوند، بنابراین
برنامه‌های کلاینت نیاز به منطقی برای اتصال مجدد و برقراری مجدد وضعیت نشست خواهند داشت.
اما توجه داشته باشید که هیچ تراکنشی از بین نخواهد رفت، زیرا تراکنش‌های در حال اجرا قطع
نمی‌شوند، بلکه فقط نشست‌های بیکار قطع خواهند شد.
.PP
پیش‌فرض: 0
.SS server_lifetime
استخربند یک اتصال سرور استفاده‌نشده (که در حال حاضر به هیچ اتصال کلاینتی متصل نیست)
را که بیش از این مدت متصل بوده باشد می‌بندد.
تنظیم آن روی 0 به این معنی است که اتصال تنها یک بار استفاده شده و سپس بسته می‌شود.
[ثانیه]
.PP
این گزینه را می‌توان به ازای هر پایگاه‌داده در بخش \f[CR][databases]\f[R] نیز تنظیم کرد.
.PP
پیش‌فرض: 3600.0
.SS server_idle_timeout
اگر یک اتصال سرور بیش از این تعداد ثانیه بیکار بوده باشد، بسته خواهد شد.
اگر 0 باشد، این مهلت زمانی غیرفعال می‌شود.
[ثانیه]
.PP
پیش‌فرض: 600.0
.SS server_connect_timeout
اگر برقراری اتصال و ورود در این مدت زمان به پایان نرسد،
اتصال بسته خواهد شد.
[ثانیه]
.PP
پیش‌فرض: 15.0
.SS server_login_retry
اگر ورود به سرور به دلیل شکست در اتصال یا در احراز هویت با خطا مواجه شود،
استخربند پیش از تلاش مجدد برای اتصال، این مدت صبر می‌کند.
در طول بازه انتظار، کلاینت‌های جدیدی که سعی در اتصال به سرور ناموفق دارند، فوراً و
بدون تلاش مجدد برای اتصال، خطا دریافت خواهند کرد.
[ثانیه]
.PP
هدف از این رفتار این است که کلاینت‌ها در صورت عدم کارکرد سرور،
بی‌دلیل در صف انتظار برای در دسترس قرار گرفتن اتصال سرور معطل نشوند.
با این حال، به این معنی نیز هست که اگر سروری موقتاً با مشکل مواجه شود،
مثلاً در حین راه‌اندازی مجدد یا اگر پیکربندی نادرست بوده باشد، حداقل این مدت طول
خواهد کشید تا استخربند اتصال مجدد به آن را مد نظر قرار دهد.
رویدادهای برنامه‌ریزی‌شده مانند راه‌اندازی‌های مجدد باید به طور معمول با استفاده از دستور
\f[CR]PAUSE\f[R] مدیریت شوند تا از این وضعیت جلوگیری گردد.
.PP
پیش‌فرض: 15.0
.SS client_login_timeout
اگر کلاینتی متصل شود اما در این مدت زمان موفق به ورود نشود،
اتصال آن قطع خواهد شد.
عمدتاً برای جلوگیری از اتصالات مرده‌ای که مانع از اجرای \f[CR]SUSPEND\f[R] و
در نتیجه راه‌اندازی مجدد برخط می‌شوند مورد نیاز است.
[ثانیه]
.PP
پیش‌فرض: 60.0
.SS autodb_idle_timeout
اگر استخرهای پایگاه‌داده ایجادشده به صورت خودکار (از طریق \[lq]*\[lq]) به مدت این تعداد
ثانیه استفاده نشده باشند، آزاد می‌شوند.
جنبه منفی این کار این است که آمارهای آن‌ها نیز فراموش می‌شود.
[ثانیه]
.PP
پیش‌فرض: 3600.0
.SS dns_max_ttl
مدت زمانی که جستجوهای DNS می‌توانند در حافظه نهان ذخیره شوند.
مقدار واقعی TTL در DNS نادیده گرفته می‌شود.
[ثانیه]
.PP
پیش‌فرض: 15.0
.SS dns_nxdomain_ttl
مدت زمانی که خطاهای DNS و جستجوهای NXDOMAIN DNS می‌توانند در حافظه نهان ذخیره شوند.
[ثانیه]
.PP
پیش‌فرض: 15.0
.SS dns_zone_check_period
دوره زمانی برای بررسی اینکه آیا شماره سریال منطقه (zone serial) تغییر کرده است یا خیر.
.PP
PgBouncer می‌تواند مناطق DNS را از نام‌های میزبان (همه چیز بعد از اولین نقطه) جمع‌آوری کند
و سپس به صورت دوره‌ای بررسی کند که آیا سریال منطقه تغییر کرده است یا خیر.
اگر متوجه تغییراتی شود، تمام نام‌های میزبان تحت آن منطقه دوباره جستجو می‌شوند.
اگر IP هر میزبانی تغییر کند، اتصالات آن نامعتبر می‌شوند.
.PP
تنها با بک‌اند c\-ares (گزینه \f[CR]\-\-with\-cares\f[R] در \f[CR]configure\f[R])
کار می‌کند.
.PP
پیش‌فرض: 0.0 (غیرفعال)
.SS resolv_conf
محل فایل سفارشی \f[CR]resolv.conf\f[R].
این گزینه برای امکان تعیین سرورهای DNS سفارشی و احتمالاً سایر گزینه‌های
تفکیک نام، مستقل از پیکربندی سراسری سیستم‌عامل است.
.PP
نیازمند بک‌اند evdns (نسخه 2.0.3 یا بالاتر) یا c\-ares (نسخه 1.15.0 یا بالاتر) است.
.PP
تجزیه و پارس این فایل توسط کتابخانه بک‌اند DNS انجام می‌شود و نه
PgBouncer؛ بنابراین برای جزئیات مربوط به نحو و دستورات مجاز، به اسناد کتابخانه
مراجعه کنید.
.PP
پیش‌فرض: خالی (استفاده از پیش‌فرض‌های سیستم‌عامل)
.SS query_wait_notify
مدت زمانی که کلاینت در صف باقی می‌ماند پیش از اینکه PgBouncer یک
پیام اعلان مبنی بر در صف بودن ارسال کند.
[ثانیه]
.PP
مقدار 0 این پیام اعلان را غیرفعال می‌کند.
.PP
پیش‌فرض: 5
.SH "تنظیمات TLS (TLS SETTINGS)"
اگر محتوای هر یک از فایل‌های گواهی (cert) یا کلید (key) بدون تغییر نام فایل در
تنظیمات پیکربندی تغییر داده شود، محتوای فایل جدید برای اتصالات جدید پس از دستور RELOAD استفاده خواهد شد.
با این حال، اتصالات موجود بسته نخواهند شد.
اگر به دلایل امنیتی لازم باشد که تمام اتصالات در سریع‌ترین زمان ممکن از فایل‌های جدید
استفاده کنند، توصیه می‌شود پس از RELOAD دستور RECONNECT اجرا شود.
.PP
تغییر هر یک از تنظیمات TLS به دلایل امنیتی به طور خودکار دستور RECONNECT را
فعال می‌کند.
.SS client_tls_sslmode
حالت TLS مورد استفاده برای اتصالات کلاینت‌ها.
اتصالات TLS به طور پیش‌فرض غیرفعال هستند.
در صورت فعال بودن، گزینه‌های \f[CR]client_tls_key_file\f[R] و
\f[CR]client_tls_cert_file\f[R] نیز باید پیکربندی شوند تا کلید و
گواهی مورد استفاده PgBouncer برای پذیرش اتصالات کلاینت تنظیم شوند.
رایج‌ترین قالب فایل گواهی قابل استفاده توسط PgBouncer قالب PEM است.
.TP
disable
استفاده از TCP ساده.
اگر کلاینت درخواست TLS دهد، نادیده گرفته می‌شود.
پیش‌فرض.
.TP
allow
اگر کلاینت درخواست TLS دهد، استفاده می‌شود.
اگر نه، از TCP ساده استفاده می‌شود.
اگر کلاینت یک گواهی کلاینت ارائه دهد، اعتبارسنجی نمی‌شود.
.TP
prefer
مشابه \f[CR]allow\f[R].
.TP
require
کلاینت باید از TLS استفاده کند.
در غیر این صورت، اتصال کلاینت رد می‌شود.
اگر کلاینت گواهی کلاینت ارائه دهد، اعتبارسنجی نمی‌شود.
.TP
verify\-ca
کلاینت باید از TLS به همراه یک گواهی کلاینت معتبر استفاده کند.
.TP
verify\-full
مشابه \f[CR]verify\-ca\f[R].
.SS client_tls_key_file
کلید خصوصی برای PgBouncer جهت پذیرش اتصالات کلاینت.
.PP
پیش‌فرض: تنظیم نشده
.SS client_tls_cert_file
گواهی برای کلید خصوصی.
کلاینت‌ها می‌توانند آن را اعتبارسنجی کنند.
.PP
پیش‌فرض: تنظیم نشده
.SS client_tls_ca_file
فایل گواهی ریشه (Root CA) برای اعتبارسنجی گواهی‌های کلاینت.
.PP
پیش‌فرض: تنظیم نشده
.SS client_tls_protocols
کدام نسخه‌های پروتکل TLS مجاز هستند.
مقادیر مجاز: \f[CR]tlsv1.0\f[R]، \f[CR]tlsv1.1\f[R]،
\f[CR]tlsv1.2\f[R]، \f[CR]tlsv1.3\f[R].
میان‌برها: \f[CR]all\f[R] (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3)،
\f[CR]secure\f[R] (tlsv1.2,tlsv1.3).
.PP
پیش‌فرض: \f[CR]secure\f[R]
.SS client_tls_ciphers
رمزهای مجاز TLS، در نحو OpenSSL.
میان‌برها:
.IP \[bu] 2
\f[CR]default\f[R]/\f[CR]secure\f[R]/\f[CR]fast\f[R]/\f[CR]normal\f[R]
(همگی از پیش‌فرض‌های سرتاسری سیستم در OpenSSL استفاده می‌کنند)
.IP \[bu] 2
\f[CR]all\f[R] (تمامی رمزها را فعال می‌کند، توصیه نمی‌شود)
.PP
تنها اتصالات با نسخه TLS 1.2 و پایین‌تر تحت تأثیر قرار می‌گیرند.
برای نسخه 1.3 به گزینه \f[CR]client_tls13_ciphers\f[R] در زیر مراجعه کنید.
.PP
پیش‌فرض: \f[CR]default\f[R]
.SS client_tls13_ciphers
رمزهای مجاز TLS نسخه 1.3.
در صورت خالی بودن، از مقدار \f[CR]client_tls_ciphers\f[R] استفاده خواهد کرد.
مقادیر مجاز:
.IP \[bu] 2
TLS_AES_256_GCM_SHA384
.IP \[bu] 2
TLS_CHACHA20_POLY1305_SHA256
.IP \[bu] 2
TLS_AES_128_GCM_SHA256
.IP \[bu] 2
TLS_AES_128_CCM_8_SHA256
.IP \[bu] 2
TLS_AES_128_CCM_SHA256
.PP
تنها اتصالاتی که از نسخه TLS 1.3 و بالاتر استفاده می‌کنند تحت تأثیر قرار می‌گیرند.
برای نسخه 1.2 و پایین‌تر گزینه \f[CR]client_tls_ciphers\f[R] را ببینید.
.PP
پیش‌فرض: \f[CR]<empty>\f[R]
.SS client_tls_ecdhcurve
نام منحنی بیضوی مورد استفاده برای تبادل کلید ECDH.
.PP
مقادیر مجاز: \f[CR]none\f[R] (غیرفعال بودن DH)، \f[CR]auto\f[R]
(ECDH با ۲۵۶ بیت)، نام منحنی
.PP
پیش‌فرض: \f[CR]auto\f[R]
.SS client_tls_dheparams
نوع تبادل کلید DHE.
.PP
مقادیر مجاز: \f[CR]none\f[R] (غیرفعال بودن DH)، \f[CR]auto\f[R]
(DH با ۲۰۴۸ بیت)، \f[CR]legacy\f[R] (DH با ۱۰۲۴ بیت)
.PP
پیش‌فرض: \f[CR]auto\f[R]
.SS server_tls_sslmode
حالت TLS مورد استفاده برای اتصالات به سرورهای PostgreSQL.
حالت پیش‌فرض \f[CR]prefer\f[R] است.
.TP
disable
استفاده از TCP ساده.
حتی درخواست TLS از سرور داده نمی‌شود.
.TP
allow
در صورتی که سرور اتصال ساده را رد کند، TLS امتحان می‌شود.
.TP
prefer
همیشه در ابتدا درخواست اتصال TLS از PostgreSQL داده می‌شود.
در صورت رد شدن، اتصال از طریق TCP ساده برقرار خواهد شد.
گواهی سرور اعتبارسنجی نمی‌شود.
پیش‌فرض.
.TP
require
اتصال حتماً باید از طریق TLS انجام شود.
اگر سرور آن را رد کند، تلاشی برای اتصال ساده TCP انجام نمی‌شود.
گواهی سرور اعتبارسنجی نمی‌شود.
.TP
verify\-ca
اتصال باید از طریق TLS باشد و گواهی سرور طبق
\f[CR]server_tls_ca_file\f[R] معتبر باشد.
نام میزبان سرور با گواهی مطابقت داده نمی‌شود.
.TP
verify\-full
اتصال باید از طریق TLS باشد و گواهی سرور طبق
\f[CR]server_tls_ca_file\f[R] معتبر باشد.
نام میزبان سرور باید با اطلاعات گواهی مطابقت داشته باشد.
.SS server_tls_ca_file
فایل گواهی ریشه برای اعتبارسنجی گواهی‌های سرور PostgreSQL.
.PP
پیش‌فرض: تنظیم نشده
.SS server_tls_key_file
کلید خصوصی برای PgBouncer جهت احراز هویت در برابر سرور PostgreSQL.
.PP
پیش‌فرض: تنظیم نشده
.SS server_tls_cert_file
گواهی برای کلید خصوصی.
سرور PostgreSQL می‌تواند آن را اعتبارسنجی کند.
.PP
پیش‌فرض: تنظیم نشده
.SS server_tls_protocols
کدام نسخه‌های پروتکل TLS مجاز هستند.
مقادیر مجاز: \f[CR]tlsv1.0\f[R]، \f[CR]tlsv1.1\f[R]،
\f[CR]tlsv1.2\f[R]، \f[CR]tlsv1.3\f[R].
میان‌برها: \f[CR]all\f[R] (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3)،
\f[CR]secure\f[R] (tlsv1.2,tlsv1.3)، \f[CR]legacy\f[R] (همه).
.PP
پیش‌فرض: \f[CR]secure\f[R]
.SS server_tls_ciphers
رمزهای مجاز TLS، در نحو OpenSSL.
میان‌برها:
.IP \[bu] 2
\f[CR]default\f[R]/\f[CR]secure\f[R]/\f[CR]fast\f[R]/\f[CR]normal\f[R]
(همگی از پیش‌فرض‌های سرتاسری سیستم در OpenSSL استفاده می‌کنند)
.IP \[bu] 2
\f[CR]all\f[R] (تمامی رمزها را فعال می‌کند، توصیه نمی‌شود)
.PP
تنها اتصالات با نسخه TLS 1.2 و پایین‌تر تحت تأثیر قرار می‌گیرند.
برای نسخه 1.3 به گزینه \f[CR]server_tls13_ciphers\f[R] در زیر مراجعه کنید.
.PP
پیش‌فرض: \f[CR]default\f[R]
.SS server_tls13_ciphers
رمزهای مجاز TLS نسخه 1.3.
در صورت خالی بودن، از مقدار \f[CR]server_tls_ciphers\f[R] استفاده خواهد کرد.
مقادیر مجاز:
.IP \[bu] 2
TLS_AES_256_GCM_SHA384
.IP \[bu] 2
TLS_CHACHA20_POLY1305_SHA256
.IP \[bu] 2
TLS_AES_128_GCM_SHA256
.IP \[bu] 2
TLS_AES_128_CCM_8_SHA256
.IP \[bu] 2
TLS_AES_128_CCM_SHA256
.PP
تنها اتصالاتی که از نسخه TLS 1.3 و بالاتر استفاده می‌کنند تحت تأثیر قرار می‌گیرند.
برای نسخه 1.2 و پایین‌تر گزینه \f[CR]client_tls_ciphers\f[R] را ببینید.
.PP
پیش‌فرض: \f[CR]<empty>\f[R]
.SH "مهلت‌های زمانی خطرناک (DANGEROUS TIMEOUTS)"
تنظیم مهلت‌های زمانی زیر می‌تواند موجب خطاهای غیرمنتظره شود.
.SS query_timeout
پرس‌وجوهایی که اجرای آن‌ها بیشتر از این مقدار طول بکشد لغو می‌شوند.
این گزینه فقط باید همراه با یک \f[CR]statement_timeout\f[R] کمی کوچک‌تر در سمت سرور
استفاده شود تا فقط برای مشکلات شبکه اعمال گردد.
[ثانیه]
.PP
پیش‌فرض: 0.0 (غیرفعال)
.SS query_wait_timeout
حداکثر زمانی که پرس‌وجوها مجازند در انتظار اجرا سپری کنند.
اگر پرس‌وجو در طول این مدت به یک سرور اختصاص داده نشود، اتصال کلاینت
قطع می‌شود.
مقدار 0 آن را غیرفعال می‌کند.
اگر این گزینه غیرفعال باشد، کلاینت‌ها برای مدت نامحدود در صف باقی می‌مانند.
[ثانیه]
.PP
این تنظیم برای جلوگیری از تصاحب اتصالات توسط سرورهای پاسخ‌نداده استفاده می‌شود.
همچنین زمانی که سرور از کار افتاده باشد یا اتصالات را به هر دلیلی رد کند مفید است.
.PP
پیش‌فرض: 120.0
.SS cancel_wait_timeout
حداکثر زمانی که درخواست‌های لغو مجازند در انتظار اجرا سپری کنند.
اگر درخواست لغو در این مدت به سرور اختصاص داده نشود، اتصال کلاینت
قطع می‌شود.
مقدار 0 آن را غیرفعال می‌کند.
اگر این گزینه غیرفعال باشد، درخواست‌های لغو برای مدت نامحدود در صف باقی می‌مانند.
[ثانیه]
.PP
این تنظیم برای جلوگیری از قفل شدن کلاینت زمانی که درخواست لغو به دلیل از کار افتادن سرور
نمی‌تواند ارسال شود، استفاده می‌شود.
.PP
پیش‌فرض: 10.0
.SS client_idle_timeout
اتصالات کلاینتی که بیش از این تعداد ثانیه بیکار بمانند بسته می‌شوند.
این مقدار باید بزرگ‌تر از تنظیمات طول عمر اتصال در سمت کلاینت باشد و
فقط برای مشکلات شبکه مورد استفاده قرار گیرد.
[ثانیه]
.PP
پیش‌فرض: 0.0 (غیرفعال)
.SS idle_transaction_timeout
اگر کلاینتی بیش از این مدت در وضعیت \[lq]idle in transaction\[rq] (بیکار درون تراکنش)
باقی بماند، اتصال آن قطع خواهد شد.
[ثانیه]
.PP
پیش‌فرض: 0.0 (غیرفعال)
.SS transaction_timeout
اگر کلاینتی بیش از این مدت در وضعیت \[lq]in transaction\[rq] (درون تراکنش)
باقی بماند، اتصال آن قطع خواهد شد.
[ثانیه]
.PP
پیش‌فرض: 0.0 (غیرفعال)
.SS suspend_timeout
مدت زمان انتظار برای تخلیه بافر در طول \f[CR]SUSPEND\f[R] یا راه‌اندازی مجدد
(\f[CR]\-R\f[R]).
در صورتی که تخلیه بافر موفقیت‌آمیز نباشد، اتصال قطع می‌شود.
[ثانیه]
.PP
پیش‌فرض: 10
.SH "تنظیمات سطح پایین شبکه (LOW\-LEVEL NETWORK SETTINGS)"
.SS pkt_buf
اندازه بافر داخلی برای بسته‌ها.
بر اندازه بسته‌های TCP ارسالی و مصرف کلی حافظه تأثیر می‌گذارد.
بسته‌های واقعی libpq می‌توانند بزرگ‌تر از این باشند، بنابراین نیازی به
تنظیم آن روی مقادیر بزرگ نیست.
.PP
پیش‌فرض: 4096
.SS max_packet_size
حداکثر اندازه بسته‌های PostgreSQL که PgBouncer اجازه عبور آن‌ها را می‌دهد.
یک بسته یا یک پرس‌وجو است یا یک سطر از مجموعه نتایج.
کل مجموعه نتایج می‌تواند بزرگ‌تر باشد.
.PP
پیش‌فرض: 2147483647
.SS listen_backlog
آرگومان backlog برای listen(2).
مشخص می‌کند چه تعداد تلاش جدید و پاسخ‌داده‌نشده برای اتصال در صف
نگهداری شوند.
هنگامی که صف پر شود، اتصالات جدید بعدی رد می‌شوند.
.PP
پیش‌فرض: 128
.SS sbuf_loopcnt
تعداد دفعات پردازش داده‌ها روی یک اتصال، پیش از رفتن به اتصال بعدی.
بدون این محدودیت، یک اتصال با مجموعه نتایج بزرگ می‌تواند PgBouncer را برای مدت
طولانی متوقف کند.
یک حلقه به اندازه یک \f[CR]pkt_buf\f[R] داده را پردازش می‌کند.
مقدار 0 به معنای عدم محدودیت است.
.PP
پیش‌فرض: 5
.SS so_reuseport
مشخص می‌کند که آیا گزینه سوکت \f[CR]SO_REUSEPORT\f[R] روی
سوکت‌های شنود TCP تنظیم شود یا خیر.
در برخی سیستم‌عامل‌ها، این امکان اجرای چندین نمونه از PgBouncer را روی همان میزبان
با شنود روی یک پورت مشترک فراهم می‌کند و به هسته اجازه می‌دهد اتصالات را به طور خودکار توزیع کند.
این گزینه روشی است برای اینکه PgBouncer بتواند از هسته‌های پردازشی (CPU) بیشتری استفاده کند.
(PgBouncer تک‌نخی است و به ازای هر نمونه از یک هسته CPU استفاده می‌کند.)
.PP
رفتار دقیق بستگی به هسته سیستم‌عامل دارد.
در زمان نگارش این متن، این تنظیم تأثیر مورد نظر را در (نسخه‌های به اندازه کافی جدید)
لینوکس، DragonFlyBSD و FreeBSD دارد.
(در FreeBSD، گزینه سوکت \f[CR]SO_REUSEPORT_LB\f[R] را به جای آن
اعمال می‌کند.)
برخی سیستم‌عامل‌های دیگر از این گزینه سوکت پشتیبانی می‌کنند اما تأثیر مورد نظر را
نخواهد داشت: این گزینه به چندین فرآیند اجازه می‌دهد به یک پورت متصل شوند اما تنها یکی از آن‌ها
اتصالات را دریافت خواهد کرد.
برای جزئیات به اسناد setsockopt() سیستم‌عامل خود مراجعه کنید.
.PP
در سیستم‌هایی که به هیچ وجه از این گزینه سوکت پشتیبانی نمی‌کنند، روشن کردن این
تنظیم منجر به خطا خواهد شد.
.PP
هر نمونه PgBouncer روی یک میزبان مشابه، حداقل به تنظیمات متفاوتی برای
\f[CR]unix_socket_dir\f[R] و \f[CR]pidfile\f[R]، و همچنین
\f[CR]logfile\f[R] در صورت استفاده نیاز دارد.
همچنین توجه داشته باشید که در صورت استفاده از این گزینه، دیگر نمی‌توانید به یک نمونه
خاص از PgBouncer از طریق TCP/IP متصل شوید، که ممکن است پیامدهایی برای پایش و جمع‌آوری معیارها داشته باشد.
.PP
برای اطمینان از اینکه لغو پرس‌وجوها همچنان کار می‌کند، باید قابلیت همتایی PgBouncer
را بین فرآیندهای مختلف PgBouncer راه‌اندازی کنید.
برای جزئیات به اسناد گزینه پیکربندی \f[CR]peer_id\f[R] و
بخش پیکربندی \f[CR]peers\f[R] مراجعه فرمایید.
همچنین مثالی از به‌کارگیری همتایی و so_reuseport در بخش مثال‌های این اسناد آورده شده است.
.PP
پیش‌فرض: 0
.SS tcp_defer_accept
گزینه سوکت \f[CR]TCP_DEFER_ACCEPT\f[R] را تنظیم می‌کند؛ برای جزئیات
\f[CR]man 7 tcp\f[R] را ببینید.
(این یک گزینه بولی است: مقدار 1 به معنای فعال بودن است.
مقدار واقعی تنظیم‌شده در صورت فعال بودن در حال حاضر روی ۴۵ ثانیه ثابت است.)
.PP
در حال حاضر این گزینه فقط در لینوکس پشتیبانی می‌شود.
.PP
پیش‌فرض: 1 در لینوکس، در غیر این صورت 0
.SS tcp_socket_buffer
پیش‌فرض: تنظیم نشده
.SS tcp_keepalive
قابلیت پایه‌ای keepalive را با پیش‌فرض‌های سیستم‌عامل فعال می‌کند.
.PP
در لینوکس، پیش‌فرض‌های سیستم عبارتند از tcp_keepidle=7200، tcp_keepintvl=75،
tcp_keepcnt=9.
احتمالاً در سیستم‌عامل‌های دیگر نیز مشابه هستند.
.PP
پیش‌فرض: 1
.SS tcp_keepcnt
پیش‌فرض: تنظیم نشده
.SS tcp_keepidle
پیش‌فرض: تنظیم نشده
.SS tcp_keepintvl
پیش‌فرض: تنظیم نشده
.SS tcp_user_timeout
گزینه سوکت \f[CR]TCP_USER_TIMEOUT\f[R] را تنظیم می‌کند.
این گزینه حداکثر مدت زمانی را بر حسب میلی‌ثانیه مشخص می‌کند که داده‌های ارسال‌شده
می‌توانند پیش از بسته شدن اجباری اتصال TCP، بدون تأیید دریافت باقی بمانند.
در صورت تنظیم روی 0، از پیش‌فرض سیستم‌عامل استفاده می‌شود.
.PP
در حال حاضر این گزینه فقط در لینوکس پشتیبانی می‌شود.
.PP
پیش‌فرض: 0
.SH "بخش [DATABASES] (SECTION [DATABASES])"
بخش \f[CR][databases]\f[R] نام پایگاه‌های داده‌ای را تعریف می‌کند که
کلاینت‌های PgBouncer می‌توانند به آن‌ها متصل شوند و مشخص می‌کند که این
اتصالات به کجا هدایت خواهند شد.
این بخش شامل خطوطی به صورت key=value است مانند:
.IP
.EX
dbname = connection string
.EE
.PP
که در آن کلید به عنوان نام پایگاه‌داده و مقدار به عنوان یک رشته اتصال
در نظر گرفته می‌شود که متشکل از جفت‌های key=value از پارامترهای اتصال است که در
زیر شرح داده شده‌اند (مشابه libpq، اما از خود libpq استفاده نمی‌شود و مجموعه قابلیت‌های در دسترس متفاوت است).
مثال:
.IP
.EX
foodb = host=host1.example.com port=5432
bardb = host=localhost dbname=bazdb
.EE
.PP
نام پایگاه‌داده می‌تواند شامل نویسه‌های \f[CR]_0\-9A\-Za\-z\f[R] بدون
نیاز به نقل‌قول باشد.
نام‌هایی که شامل سایر نویسه‌ها هستند باید با نقل‌قول استاندارد شناسه‌های SQL
مشخص شوند: نقل‌قول دوتایی، با \[lq]\[rq] برای یک بار وقوع نقل‌قول دوتایی.
.PP
نام پایگاه‌داده \[lq]pgbouncer\[rq] برای کنسول مدیریتی رزرو شده است و
نمی‌توان از آن به عنوان یک کلید در اینجا استفاده کرد.
.PP
نویسه \[lq]*\[rq] به عنوان پایگاه‌داده جایگزین عمل می‌کند: اگر نام دقیق
وجود نداشته باشد، مقدار آن به عنوان رشته اتصال برای پایگاه‌داده درخواستی
در نظر گرفته می‌شود.
برای مثال، اگر مدخلی به شکل زیر وجود داشته باشد (و مدخل بازنویسی دیگری وجود نداشته باشد)
.IP
.EX
* = host=foo
.EE
.PP
آن‌گاه یک اتصال به PgBouncer با مشخص کردن پایگاه‌داده \[lq]bar\[rq]، عملاً
به گونه‌ای رفتار خواهد کرد که گویی مدخلی به شکل
.IP
.EX
bar = host=foo dbname=bar
.EE
.PP
وجود دارد (با استفاده از این مزیت که پیش‌فرض برای \f[CR]dbname\f[R] همان
نام پایگاه‌داده سمت کلاینت است؛ بخش زیر را ببینید).
.PP
چنین مدخل‌های پایگاه‌داده ایجادشده به صورت خودکار، در صورتی که بیشتر از زمان
مشخص‌شده توسط پارامتر \f[CR]autodb_idle_timeout\f[R] بیکار بمانند، پاکسازی می‌شوند.
.SS dbname
نام پایگاه‌داده مقصد.
.PP
پیش‌فرض: همان نام پایگاه‌داده سمت کلاینت
.SS host
نام میزبان یا نشانی IP برای اتصال به آن.
نام‌های میزبان در زمان اتصال حل (resolve) می‌شوند و نتیجه طبق
پارامتر \f[CR]dns_max_ttl\f[R] در حافظه نهان ذخیره می‌شود.
هنگامی که تفکیک نام یک میزبان تغییر می‌کند، اتصالات سرور موجود هنگامی که آزاد
می‌شوند (با توجه به حالت استخربندی) به طور خودکار بسته می‌شوند و اتصالات سرور جدید
بلافاصله از تفکیک نام جدید استفاده می‌کنند.
اگر DNS چندین نتیجه بازگرداند، آن‌ها به روش نوبت‌گردشی استفاده می‌شوند.
.PP
اگر مقدار با \f[CR]/\f[R] شروع شود، یک سوکت یونیکس در فضای نام
فایل‌سیستم استفاده می‌شود.
اگر مقدار با \f[CR]\[at]\f[R] شروع شود، یک سوکت یونیکس در فضای نام
انتزاعی استفاده می‌شود.
.PP
می‌توان فهرستی از نام‌های میزبان یا نشانی‌ها را که با کاما جدا شده‌اند مشخص کرد.
در این صورت، اتصالات به صورت نوبت‌گردشی برقرار می‌شوند.
(اگر یک فهرست میزبان شامل نام‌هایی باشد که به نوبه خود از طریق DNS به چندین نشانی
تفکیک می‌شوند، سیستم‌های نوبت‌گردشی مستقل از یکدیگر عمل می‌کنند.
این یک وابستگی به پیاده‌سازی است که ممکن است در آینده تغییر کند.)
توجه داشته باشید که در یک فهرست، تمام میزبان‌ها باید در همه زمان‌ها در دسترس باشند: هیچ
سازوکاری برای نادیده گرفتن میزبان‌های غیرقابل دسترس یا انتخاب میزبان‌های در دسترس از یک فهرست یا موارد مشابه وجود ندارد.
(این با مفهوم فهرست میزبان در libpq متفاوت است.)
همچنین توجه داشته باشید که این موضوع تنها بر نحوه انتخاب مقصد اتصالات جدید تأثیر می‌گذارد.
تنظیم \f[CR]server_round_robin\f[R] را نیز برای چگونگی انتساب کلاینت‌ها به اتصالات سرور
از قبل برقرار شده بررسی کنید.
.PP
مثال‌ها:
.IP
.EX
host=localhost
host=127.0.0.1
host=2001:0db8:85a3:0000:0000:8a2e:0370:7334
host=/var/run/postgresql
host=192.168.0.1,192.168.0.2,192.168.0.3
.EE
.PP
پیش‌فرض: تنظیم نشده، به معنی استفاده از یک سوکت یونیکس
.SS port
پیش‌فرض: 5432
.SS user
اگر \f[CR]user=\f[R] تنظیم شود، تمام اتصالات به پایگاه‌داده مقصد با کاربر
مشخص‌شده برقرار خواهند شد، به این معنی که تنها یک استخر برای این پایگاه‌داده وجود خواهد داشت.
.PP
در غیر این صورت، PgBouncer با نام کاربری کلاینت به پایگاه‌داده مقصد وارد می‌شود،
به این معنی که به ازای هر کاربر یک استخر وجود خواهد داشت.
.SS password
اگر هیچ گذرواژه‌ای در اینجا مشخص نشود، گذرواژه موجود در
\f[CR]auth_file\f[R] برای کاربری که در بالا مشخص شده است استفاده خواهد شد.
روش‌های پویای کشف گذرواژه مانند \f[CR]auth_query\f[R] در حال حاضر در اینجا
پشتیبانی نمی‌شوند.
.SS auth_user
بازنویسی تنظیم سراسری \f[CR]auth_user\f[R]، در صورت تعیین شدن.
.SS auth_query
بازنویسی تنظیم سراسری \f[CR]auth_query\f[R]، در صورت تعیین شدن.
کل دستور SQL باید در داخل نقل‌قول تکی (single quote) قرار گیرد.
.SS auth_dbname
بازنویسی تنظیم سراسری \f[CR]auth_dbname\f[R]، در صورت تعیین شدن.
.SS pool_size
تنظیم حداکثر اندازه استخرها برای این پایگاه‌داده.
در صورت عدم تنظیم، از \f[CR]default_pool_size\f[R] استفاده می‌شود.
.SS min_pool_size
تنظیم حداقل اندازه استخر برای این پایگاه‌داده.
در صورت عدم تنظیم، از \f[CR]min_pool_size\f[R] سراسری استفاده می‌شود.
.PP
تنها در صورتی اعمال می‌شود که حداقل یکی از موارد زیر برقرار باشد:
.IP \[bu] 2
این مدخل در بخش \f[CR][database]\f[R] مقداری برای کلید
\f[CR]user\f[R] تعیین کرده باشد (کاربر اجباری).
.IP \[bu] 2
حداقل یک کلاینت به استخر متصل باشد.
.SS reserve_pool_size
تعیین اتصالات اضافی برای این پایگاه‌داده.
در صورت عدم تنظیم، از \f[CR]reserve_pool_size\f[R] سراسری استفاده می‌شود.
به دلایل سازگاری با نسخه‌های پیشین، \f[CR]reserve_pool\f[R] یک نام مستعار برای
این گزینه است.
.SS connect_query
پرس‌وجویی که باید پس از برقراری یک اتصال، اما پیش از اجازه دادن به
استفاده از آن توسط هر کلاینتی، اجرا شود.
اگر پرس‌وجو خطایی ایجاد کند، خطاها لاگ می‌شوند اما در غیر این صورت نادیده گرفته خواهند شد.
.SS pool_mode
تنظیم حالت استخربندی مختص به این پایگاه‌داده.
در صورت عدم تنظیم، از \f[CR]pool_mode\f[R] پیش‌فرض استفاده می‌شود.
.SS load_balance_hosts
هنگامی که یک فهرست جداشده با کاما در \f[CR]host\f[R] مشخص شده باشد،
\f[CR]load_balance_hosts\f[R] کنترل می‌کند که کدام مدخل برای یک اتصال جدید انتخاب شود.
.PP
نکته: این تنظیم در حال حاضر تنها رفتار توزیع بار را هنگام ارائه چندین میزبان در رشته اتصال
کنترل می‌کند، اما زمانی که رکورد DNS یک میزبان منفرد به چندین نشانی IP اشاره دارد اعمال نمی‌شود.
این یک قابلیت غایب است، بنابراین در انتشار آینده ممکن است این تنظیم هر دو روش توزیع بار را کنترل کند.
.TP
round\-robin
یک تلاش برای اتصال جدید، مدخل میزبان بعدی را در فهرست انتخاب می‌کند.
.TP
disable
یک اتصال جدید همچنان از همان مدخل میزبان استفاده می‌کند تا زمانی که یک اتصال با خطا
مواجه شود، که پس از آن مدخل میزبان بعدی انتخاب می‌شود.
.PP
توصیه می‌شود مقدار \f[CR]server_login_retry\f[R] کمتر از مقدار پیش‌فرض
تنظیم شود تا تلاش‌های مجدد سریع هنگامی که چندین میزبان در دسترس هستند تضمین گردد.
.PP
پیش‌فرض: \f[CR]round\-robin\f[R]
.SS max_db_connections
پیکربندی حداکثر تعداد اتصالات سرور در سطح کل پایگاه‌داده (به این معنی که تمام
استخرهای درون این پایگاه‌داده بیش از این تعداد اتصال سرور نخواهند داشت).
.SS max_db_client_connections
پیکربندی حداکثر اتصالات کلاینت در سطح کل پایگاه‌داده.
باید همراه با max_client_conn استفاده شود تا تعداد اتصالاتی که
PgBouncer مجاز به پذیرش آن‌ها است محدود شود.
.SS server_lifetime
پیکربندی server_lifetime به ازای هر پایگاه‌داده.
در صورت عدم تنظیم، پایگاه‌داده از مقدار سراسری پیکربندی‌شده برای
\f[CR]server_lifetime\f[R] استفاده خواهد کرد.
.SS client_encoding
درخواست \f[CR]client_encoding\f[R] خاص از سرور.
.SS datestyle
درخواست \f[CR]datestyle\f[R] خاص از سرور.
.SS timezone
درخواست \f[CR]timezone\f[R] خاص از سرور.
.SH "بخش [USERS] (SECTION [USERS])"
این بخش شامل خطوطی به صورت key=value است مانند:
.IP
.EX
user1 = settings
.EE
.PP
که در آن کلید به عنوان نام کاربر و مقدار به عنوان فهرستی از جفت‌های
key=value از تنظیمات پیکربندی مخصوص به این کاربر در نظر گرفته می‌شود.
مثال:
.IP
.EX
user1 = pool_mode=session
.EE
.PP
تنها تعداد کمی از تنظیمات در اینجا در دسترس هستند.
.PP
توجه داشته باشید که هنگام پیکربندی \f[CR]auth_file\f[R]، اگر کاربری در
این بخش تعریف شده باشد اما در \f[CR]auth_file\f[R] فهرست نشده باشد، PgBouncer
در صورت تنظیم بودن \f[CR]auth_user\f[R] تلاش خواهد کرد از \f[CR]auth_query\f[R]
برای یافتن گذرواژه آن کاربر استفاده کند.
اگر \f[CR]auth_user\f[R] تنظیم نشده باشد، PgBouncer وانمود می‌کند که کاربر
وجود دارد و از بازگرداندن پیام‌های \[lq]no such user\[rq] به کلاینت خودداری می‌کند،
اما هیچ گذرواژه ارائه‌شده‌ای را نیز نخواهد پذیرفت.
.SS pool_size
تنظیم حداکثر اندازه استخرها برای تمامی اتصالات این کاربر.
در صورت عدم تنظیم، از مقدار پایگاه‌داده یا \f[CR]default_pool_size\f[R] استفاده می‌شود.
.SS reserve_pool_size
تنظیم تعداد اتصالات اضافی مجاز به یک استخر برای این کاربر.
در صورت عدم تنظیم، از پیکربندی پایگاه‌داده یا مقدار سراسری
\f[CR]reserve_pool_size\f[R] استفاده می‌شود.
.SS pool_mode
تنظیم حالت استخر برای استفاده در تمامی اتصالات این کاربر.
در صورت عدم تنظیم، از مقدار پایگاه‌داده یا \f[CR]pool_mode\f[R] پیش‌فرض استفاده می‌شود.
.SS max_user_connections
پیکربندی حداکثر اتصالات سرور برای کاربر (به عنوان مثال تمام استخرهای
دارای این کاربر بیش از این تعداد اتصال سرور نخواهند داشت).
.SS query_timeout
تنظیم حداکثر تعداد ثانیه‌هایی که یک پرس‌وجوی کاربر می‌تواند اجرا شود.
در صورت تنظیم، این مهلت زمانی بر query_timeout در سطح سرور که در بالا توضیح
داده شد تقدم دارد.
.SS idle_transaction_timeout
تنظیم حداکثر تعداد ثانیه‌هایی که کاربر می‌تواند یک تراکنش بیکار باز داشته باشد.
در صورت تنظیم، این مهلت زمانی بر idle_transaction_timeout در سطح سرور که در بالا توضیح
داده شد تقدم دارد.
.SS transaction_timeout
تنظیم حداکثر تعداد ثانیه‌هایی که کاربر می‌تواند یک تراکنش باز داشته باشد.
در صورت تنظیم، این مهلت زمانی بر transaction_timeout در سطح سرور که در بالا توضیح
داده شد تقدم دارد.
.SS client_idle_timeout
تنظیم حداکثر مدت زمانی بر حسب ثانیه که یک کلاینت مجاز است به طور بیکار به نمونه
PgBouncer متصل بماند.
در صورت تنظیم، این مهلت زمانی بر client_idle_timeout در سطح سرور که در بالا توضیح
داده شد تقدم دارد.
.PP
لطفاً توجه داشته باشید که این یک مهلت زمانی بالقوه خطرناک است.
.SS max_user_client_connections
پیکربندی حداکثر اتصالات کلاینت برای کاربر.
این معادل کاربری تنظیم max_client_conn است.
.SH "بخش [PEERS] (SECTION [PEERS])"
بخش \f[CR][peers]\f[R] همتاهایی را تعریف می‌کند که PgBouncer می‌تواند
درخواست‌های لغو را به آن‌ها ارسال کند و مشخص می‌کند که این درخواست‌های لغو به
کجا هدایت خواهند شد.
.PP
فرآیندهای PgBouncer می‌توانند با تعریف یک مقدار \f[CR]peer_id\f[R] و یک بخش
\f[CR][peers]\f[R] در پیکربندی‌های تمام فرآیندهای PgBouncer، در یک گروه با یکدیگر
همتا شوند.
این فرآیندهای PgBouncer می‌توانند درخواست‌های لغو را به فرآیندی که از آن منشأ گرفته است
ارسال کنند.
این امر برای عملکرد صحیح درخواست‌های لغو زمانی که چندین فرآیند PgBouncer (احتمالاً روی
سرورهای مختلف) پشت یک توزیع‌کننده بار TCP (TCP load balancer) قرار دارند ضروری است.
درخواست‌های لغو روی اتصالات TCP متفاوتی نسبت به پرس‌وجویی که در حال لغو آن هستند ارسال می‌شوند،
بنابراین یک توزیع‌کننده بار TCP ممکن است اتصال درخواست لغو را به فرآیندی متفاوت از آن فرآیندی
که برای آن در نظر گرفته شده بود ارسال کند.
با همتا کردن آن‌ها، این درخواست‌های لغو در نهایت به فرآیند مناسب هدایت می‌شوند.
توضیحات دقیق‌تر در این \c
.UR https://www.youtube.com/watch?v=X-nCHcZ6vQU
ویدیوی ضبط‌شده از یک ارائه کنفرانس
.UE \c
\& ارائه شده است.
.PP
این بخش شامل خطوطی به صورت key=value است مانند:
.IP
.EX
peer_id = connection string
.EE
.PP
که در آن کلید به عنوان یک \f[CR]peer_id\f[R] و مقدار به عنوان یک رشته
اتصال متشکل از جفت‌های key=value از پارامترهای اتصال در نظر گرفته می‌شود که در
زیر شرح داده شده‌اند (مشابه libpq، اما از خود libpq استفاده نمی‌شود و مجموعه قابلیت‌های در دسترس متفاوت است).
مثال:
.IP
.EX
1 = host=host1.example.com
2 = host=/tmp/pgbouncer\-2  port=5555
.EE
.PP
نکته ۱: برای اینکه قابلیت همتایی کار کند، \f[CR]peer_id\f[R] هر فرآیند PgBouncer
در گروه باید درون گروه همتا یکتا باشد.
و بخش \f[CR][peers]\f[R] باید شامل مدخل‌هایی برای هر یک از آن شناسه‌های همتا باشد.
یک نمونه را می‌توان در بخش مثال‌های این اسناد یافت.
مجاز \f[B]است\f[R]، اما الزامی نیست، که بخش \f[CR][peers]\f[R]
شامل \f[CR]peer_id\f[R] مربوط به همان فرآیند PgBouncer باشد که پیکربندی برای آن نوشته شده است.
چنین مدخلی نادیده گرفته خواهد شد، اما برای آسان‌تر شدن مدیریت پیکربندی مجاز دانسته شده است؛
زیرا امکان استفاده از یک بخش \f[CR][peers]\f[R] دقیقاً یکسان را برای چندین پیکربندی فراهم می‌کند.
.PP
نکته ۲: همتایی میان‌نسخه‌ای تا زمانی که تمام همتاها در یک سمت مرز نسخه v1.21.0
باشند پشتیبانی می‌شود.
در نسخه v1.21.0 تغییرات ساختاری بنیادینی در نحوه کدگذاری توکن‌های لغو ایجاد شد که
آن‌ها را با توکن‌های ایجادشده توسط نسخه‌های قبلی ناسازگار کرد.
.SS host
نام میزبان یا نشانی IP برای اتصال به آن.
نام‌های میزبان در زمان اتصال تفکیک می‌شوند و نتیجه طبق پارامتر
\f[CR]dns_max_ttl\f[R] در حافظه نهان ذخیره می‌شود.
اگر DNS چندین نتیجه بازگرداند، آن‌ها به روش نوبت‌گردشی استفاده می‌شوند.
اما به طور کلی توصیه نمی‌شود از نام میزبانی استفاده کنید که به چندین IP تفکیک می‌شود،
زیرا در این صورت درخواست لغو ممکن است همچنان به گره نادرستی ارسال شود و نیاز به ارسال مجدد
داشته باشد (که تنها تا سه بار مجاز است).
.PP
اگر مقدار با \f[CR]/\f[R] شروع شود، یک سوکت یونیکس در فضای نام
فایل‌سیستم استفاده می‌شود.
اگر مقدار با \f[CR]\[at]\f[R] شروع شود، یک سوکت یونیکس در فضای نام
انتزاعی استفاده می‌شود.
.PP
مثال‌ها:
.IP
.EX
host=localhost
host=127.0.0.1
host=2001:0db8:85a3:0000:0000:8a2e:0370:7334
host=/var/run/pgbouncer\-1
.EE
.SS port
پیش‌فرض: 6432
.SS pool_size
تعیین حداکثر تعداد درخواست‌های لغوی که می‌توانند به طور همزمان در مسیر ارسال
به همتا باشند.
کاملاً طبیعی است که درخواست‌های لغو به صورت انفجاری (bursts) برسند، برای مثال
زمانی که سرور پشتیبان Postgres کند است یا از کار افتاده است.
بنابراین مهم است که \f[CR]pool_size\f[R] آن‌قدر کم نباشد که نتواند این بارهای انفجاری
را مدیریت کند.
.PP
در صورت عدم تنظیم، از \f[CR]default_pool_size\f[R] استفاده می‌شود.
.SH "دستور INCLUDE (INCLUDE DIRECTIVE)"
فایل پیکربندی PgBouncer می‌تواند شامل دستورالعمل‌های include باشد که
فایل پیکربندی دیگری را برای خواندن و پردازش مشخص می‌کنند.
این کار امکان تقسیم فایل پیکربندی به بخش‌های فیزیکی مجزا را فراهم می‌کند.
دستورات include به صورت زیر هستند:
.IP
.EX
%include filename
.EE
.PP
اگر نام فایل یک مسیر مطلق نباشد، به عنوان مسیر نسبی نسبت به دایرکتوری
کاری جاری در نظر گرفته می‌شود.
.SH "قالب فایل احراز هویت (AUTHENTICATION FILE FORMAT)"
این بخش قالب فایلی را که توسط تنظیم \f[CR]auth_file\f[R] مشخص می‌شود،
توضیح می‌دهد.
این فایل یک فایل متنی در قالب زیر است:
.IP
.EX
\[dq]username1\[dq] \[dq]password\[dq] ...
\[dq]username2\[dq] \[dq]md5abcdef012342345\[dq] ...
\[dq]username2\[dq] \[dq]SCRAM\-SHA\-256$<iterations>:<salt>$<storedkey>:<serverkey>\[dq]
.EE
.PP
باید حداقل ۲ فیلد وجود داشته باشد که با نقل‌قول دوتایی محصور شده‌اند.
فیلد اول نام کاربری است و فیلد دوم گذرواژه متنی ساده، یک گذرواژه درهم‌سازی‌شده با
MD5 یا یک مقدار محرمانه SCRAM است.
PgBouncer بقیه خط را نادیده می‌گیرد.
علامت‌های نقل‌قول دوتایی درون مقدار یک فیلد را می‌توان با نوشتن دو نقل‌قول
دوتایی اسکیپ کرد.
.PP
قالب گذرواژه درهم‌سازی‌شده با MD5 در PostgreSQL:
.IP
.EX
\[dq]md5\[dq] + md5(password + username)
.EE
.PP
بنابراین کاربر \f[CR]admin\f[R] با گذرواژه \f[CR]1234\f[R] دارای
گذرواژه هش‌شده با MD5 به صورت \f[CR]md545f2603610af569b6155c45067268c6b\f[R] خواهد بود.
.PP
قالب مقدار محرمانه SCRAM در PostgreSQL:
.IP
.EX
SCRAM\-SHA\-256$<iterations>:<salt>$<storedkey>:<serverkey>
.EE
.PP
برای جزئیات بیشتر در این مورد، اسناد PostgreSQL و RFC 5803 را ببینید.
.PP
گذرواژه‌ها یا مقادیر محرمانه ذخیره‌شده در فایل احراز هویت دو هدف را
دنبال می‌کنند.
اول، در صورتی که روش احراز هویت مبتنی بر گذرواژه پیکربندی شده باشد، برای تأیید
گذرواژه‌های اتصالات ورودی کلاینت استفاده می‌شوند.
دوم، در صورتی که سرور پشتیبان نیازمند احراز هویت مبتنی بر گذرواژه باشد (مگر اینکه
گذرواژه مستقیماً در رشته اتصال پایگاه‌داده مشخص شده باشد)، به عنوان گذرواژه اتصالات
خروجی به سرور پشتیبان استفاده می‌شوند.
.SS "محدودیت‌ها (Limitations)"
اگر گذرواژه به صورت متن ساده ذخیره شده باشد، می‌تواند برای هر نوع احراز هویت
مبتنی بر گذرواژه مورد استفاده در سرور پشتیبان استفاده شود؛ متن ساده،
MD5 یا SCRAM (برای جزئیات به \c
.UR https://www.postgresql.org/docs/current/auth-password.html
.UE \c
\ مراجعه کنید).
.PP
گذرواژه‌های درهم‌سازی‌شده با MD5 در صورتی قابل استفاده هستند که سرور پشتیبان از
احراز هویت MD5 استفاده کند (یا کاربران خاصی دارای گذرواژه‌های هش‌شده با MD5 باشند).
.PP
مقادیر محرمانه SCRAM تنها در صورتی می‌توانند برای ورود به سرور استفاده شوند که
احراز هویت کلاینت نیز از SCRAM استفاده کند، تعریف پایگاه‌داده PgBouncer
نام کاربری را مشخص نکرده باشد، و مقادیر محرمانه SCRAM در PgBouncer و سرور PostgreSQL یکسان باشند
(نمک (salt) و تعداد تکرارهای یکسان، نه صرفاً گذرواژه یکسان).
این امر ناشی از یک ویژگی امنیتی ذاتی SCRAM است: مقدار محرمانه ذخیره‌شده SCRAM به خودی
خود نمی‌تواند برای استخراج اعتبارنامه‌های ورود استفاده شود.
.PP
فایل احراز هویت می‌تواند به صورت دستی نوشته شود، اما ایجاد آن از فهرست دیگری
از کاربران و گذرواژه‌ها نیز مفید است.
برای یک اسکریپت نمونه جهت تولید فایل احراز هویت از جدول سیستمی \f[CR]pg_authid\f[R]،
فایل \f[CR]./etc/mkauth.py\f[R] را ببینید.
همچنین می‌توانید از \f[CR]auth_query\f[R] به جای \f[CR]auth_file\f[R] استفاده کنید
تا از نگهداری یک فایل احراز هویت جداگانه بی‌نیاز شوید.
.SS "نکته‌ای درباره سرورهای مدیریت‌شده (Note on managed servers)"
اگر سرور پشتیبان برای استفاده از احراز هویت گذرواژه SCRAM پیکربندی شده باشد،
PgBouncer در صورتی که الف) گذرواژه کاربر به صورت متن ساده یا ب) مقدار محرمانه متناظر SCRAM را
نداند، نمی‌تواند با موفقیت احراز هویت کند.
.PP
برخی ارائه‌دهندگان ابری (مانند AWS RDS) دسترسی به جدول‌های سیستمی حساس
PostgreSQL را برای واکشی گذرواژه‌ها مسدود می‌کنند.
حتی برای کاربری با بالاترین سطح دسترسی (مانند عضوی از rds_superuser)، اجرای دستور
\f[CR]select * from pg_authid;\f[R] خطای
\f[CR]ERROR:  permission denied for table pg_authid.\f[R] را برمی‌گرداند.
این یک رفتار شناخته‌شده است (به \c
.UR https://aws.amazon.com/blogs/database/best-practices-for-migrating-postgresql-databases-to-amazon-rds-and-amazon-aurora
پست وبلاگ
.UE \c
\ مراجعه کنید).
.PP
بنابراین، واکشی یک مقدار محرمانه موجود SCRAM پس از ذخیره شدن آن در یک سرور
مدیریت‌شده غیرممکن است، که پیکربندی PgBouncer را برای استفاده از همان مقدار محرمانه
SCRAM دشوار می‌کند.
با این وجود، مقدار محرمانه SCRAM همچنان می‌تواند با استفاده از ترفند زیر
پیکربندی شده و در هر دو سمت استفاده شود:
.PP
یک مقدار محرمانه SCRAM برای یک گذرواژه دلخواه با ابزاری تولید کنید که قابلیت
چاپ این مقدار محرمانه را داشته باشد.
برای مثال \f[CR]psql \-\-echo\-hidden\f[R] و دستور
\f[CR]\[rs]password\f[R] پیش از ارسال مقدار محرمانه SCRAM به سرور،
آن را روی کنسول چاپ می‌کند:
.IP
.EX
$ psql \-\-echo\-hidden <connection_string>
postgres=# \[rs]password <role_name>
Enter new password for user \[dq]<role_name>\[dq]:
Enter it again:
********* QUERY **********
ALTER USER <role_name> PASSWORD \[aq]SCRAM\-SHA\-256$<iterations>:<salt>$<storedkey>:<serverkey>\[aq]
**************************
.EE
.PP
مقدار محرمانه SCRAM را از بخش QUERY یادداشت کنید و آن را در فایل
\f[CR]userlist.txt\f[R] در PgBouncer قرار دهید.
.PP
اگر از ابزاری غیر از \f[CR]psql \-\-echo\-hidden\f[R] استفاده کرده‌اید،
باید مقدار محرمانه SCRAM را در سرور نیز تنظیم کنید (می‌توانید از
\f[CR]alter role <role_name> password \[aq]<scram_secret>\[aq]\f[R]
برای این کار استفاده کنید).
.SH "قالب فایل HBA (HBA FILE FORMAT)"
محل فایل HBA توسط تنظیم \f[CR]auth_hba_file\f[R] مشخص می‌شود.
تنها در صورتی استفاده می‌شود که \f[CR]auth_type\f[R] روی \f[CR]hba\f[R] تنظیم شده باشد.
.PP
این فایل از قالب فایل \f[CR]pg_hba.conf\f[R] در PostgreSQL پیروی می‌کند (به \c
.UR https://www.postgresql.org/docs/current/auth-pg-hba-conf.html
.UE \c
\ مراجعه کنید).
.IP \[bu] 2
انواع رکوردهای پشتیبانی‌شده: \f[CR]local\f[R]، \f[CR]host\f[R]،
\f[CR]hostssl\f[R]، \f[CR]hostnossl\f[R].
.IP \[bu] 2
فیلد پایگاه‌داده: از \f[CR]all\f[R]، \f[CR]replication\f[R]،
\f[CR]sameuser\f[R]، \f[CR]\[at]file\f[R] و چندین نام پشتیبانی می‌کند.
موارد پشتیبانی‌نشده: \f[CR]samerole\f[R]، \f[CR]samegroup\f[R].
.IP \[bu] 2
فیلد نام کاربری: از \f[CR]all\f[R]، \f[CR]\[at]file\f[R] و چندین نام پشتیبانی می‌کند.
موارد پشتیبانی‌نشده: \f[CR]+groupname\f[R].
.IP \[bu] 2
فیلد نشانی: از \f[CR]all\f[R]، IPv4 و IPv6 پشتیبانی می‌کند.
موارد پشتیبانی‌نشده: \f[CR]samehost\f[R]، \f[CR]samenet\f[R]، نام‌های DNS و
پیشوندهای دامنه.
.IP \[bu] 2
فیلد روش احراز هویت (Auth\-method): تنها روش‌های پشتیبانی‌شده توسط
\f[CR]auth_type\f[R] در PgBouncer، به علاوه \f[CR]peer\f[R] و
\f[CR]reject\f[R] پشتیبانی می‌شوند؛ به استثنای \f[CR]any\f[R] و \f[CR]pam\f[R] که
فقط به صورت سراسری کار می‌کنند.
.IP \[bu] 2
پارامتر نگاشت نام کاربری (\f[CR]map=\f[R]) زمانی که \f[CR]auth_type\f[R] برابر با
\f[CR]cert\f[R] یا \f[CR]peer\f[R] باشد پشتیبانی می‌شود.
.SH "قالب فایل نگاشت IDENT (IDENT MAP FILE FORMAT)"
محل فایل نگاشت ident توسط تنظیم \f[CR]auth_ident_file\f[R] مشخص می‌شود.
تنها در صورتی بارگیری می‌شود که \f[CR]auth_type\f[R] روی \f[CR]hba\f[R] تنظیم شده باشد.
.PP
قالب این فایل گونه ساده‌شده‌ای از فایل نگاشت ident در PostgreSQL است (به \c
.UR https://www.postgresql.org/docs/current/auth-username-maps.html
.UE \c
\ مراجعه کنید).
.IP \[bu] 2
خطوط پشتیبانی‌شده تنها به شکل زیر هستند:
\f[CR]map\-name system\-username database\-username\f[R].
.IP \[bu] 2
هیچ پشتیبانی برای گنجاندن فایل/دایرکتوری وجود ندارد.
.IP \[bu] 2
فیلد نام کاربری سیستم (System\-username): عبارات منظم (regular expressions) پشتیبانی نمی‌شوند.
.IP \[bu] 2
فیلد نام کاربری پایگاه‌داده (Database\-username): از \f[CR]all\f[R] یا یک نام کاربری منفرد
Postgres پشتیبانی می‌کند.
موارد پشتیبانی‌نشده: \f[CR]+groupname\f[R] و عبارات منظم.
.SH "مثال‌ها (EXAMPLES)"
نمونه پیکربندی کوچک:
.IP
.EX
[databases]
template1 = host=localhost dbname=template1 auth_user=someuser

[pgbouncer]
pool_mode = session
listen_port = 6432
listen_addr = localhost
auth_type = md5
auth_file = users.txt
logfile = pgbouncer.log
pidfile = pgbouncer.pid
admin_users = someuser
stats_users = stat_collector
.EE
.PP
مثال‌های پایگاه‌داده:
.IP
.EX
[databases]

; foodb از طریق سوکت یونیکس
foodb =

; هدایت bardb به bazdb روی localhost
bardb = host=localhost dbname=bazdb

; دسترسی به پایگاه‌داده مقصد با یک کاربر منفرد انجام خواهد شد
forcedb = host=localhost port=300 user=baz password=foo client_encoding=UNICODE datestyle=ISO
.EE
.PP
نمونه تابع امن برای \f[CR]auth_query\f[R]:
.IP
.EX
CREATE OR REPLACE FUNCTION pgbouncer.user_lookup(in i_username text, out uname text, out phash text)
RETURNS record AS $$
BEGIN
    SELECT rolname, CASE WHEN rolvaliduntil < now() THEN NULL ELSE rolpassword END
    FROM pg_authid
    WHERE rolname=i_username AND rolcanlogin
    INTO uname, phash;
    RETURN;
END;
$$ LANGUAGE plpgsql
   SECURITY DEFINER
   \-\- Set a secure search_path: trusted schema(s), then \[aq]pg_temp\[aq].
   SET search_path = pg_catalog, pg_temp;
REVOKE ALL ON FUNCTION pgbouncer.user_lookup(text) FROM public, pgbouncer;
GRANT EXECUTE ON FUNCTION pgbouncer.user_lookup(text) TO pgbouncer;
.EE
.PP
نمونه پیکربندی برای ۲ فرآیند همتای PgBouncer برای ایجاد یک ساختار چندهسته‌ای
PgBouncer با استفاده از \f[CR]so_reuseport\f[R].
پیکربندی برای فرآیند اول:
.IP
.EX
[databases]
postgres = host=localhost dbname=postgres

[peers]
1 = host=/tmp/pgbouncer1
2 = host=/tmp/pgbouncer2

[pgbouncer]
listen_addr=127.0.0.1
auth_file=auth_file.conf
so_reuseport=1
unix_socket_dir=/tmp/pgbouncer1
peer_id=1
.EE
.PP
پیکربندی برای فرآیند دوم:
.IP
.EX
[databases]
postgres = host=localhost dbname=postgres

[peers]
1 = host=/tmp/pgbouncer1
2 = host=/tmp/pgbouncer2

[pgbouncer]
listen_addr=127.0.0.1
auth_file=auth_file.conf
so_reuseport=1
; تنها unix_socket_dir و peer_id متفاوت هستند
unix_socket_dir=/tmp/pgbouncer2
peer_id=2
.EE
.SH "همچنین ببینید (SEE ALSO)"
pgbouncer(1) \- صفحه راهنما برای استفاده عمومی و دستورات کنسول
.PP
\c
.UR https://www.pgbouncer.org
.UE \c