PGBOUNCER.INI(5) Databases PGBOUNCER.INI(5)

pgbouncer - فایل پیکربندی pgbouncer

این فایل پیکربندی در قالب “ini” است. نام بخش‌ها درون “[” و ”]” قرار می‌گیرند. خطوطی که با “;” یا “#” آغاز می‌شوند به عنوان کامنت در نظر گرفته شده و نادیده گرفته می‌شوند. نویسه‌های “;” و “#” اگر در ادامه خط ظاهر شوند، به عنوان نویسه ویژه شناخته نمی‌شوند.

فایل گزارش (log file) را مشخص می‌کند. برای اجرای دیمن (-d)، باید این گزینه یا syslog تنظیم شده باشد.

فایل لاگ باز نگه داشته می‌شود، بنابراین پس از چرخش لاگ‌ها (log rotation)، باید از دستور kill -HUP یا در کنسول از RELOAD; استفاده شود. در ویندوز، سرویس باید متوقف شده و مجدداً راه‌اندازی گردد.

توجه داشته باشید که تنظیم logfile به خودی خود ارسال لاگ‌ها به stderr را متوقف نمی‌کند. برای این کار از گزینه خط فرمان -q یا -d استفاده کنید.

پیش‌فرض: تنظیم نشده

فایل PID را مشخص می‌کند. بدون تنظیم pidfile، اجرای دیمن (-d) مجاز نیست.

پیش‌فرض: تنظیم نشده

فهرستی (جداشده با کاما) از نشانی‌هایی را مشخص می‌کند که باید برای اتصالات TCP شنود شوند. همچنین می‌توانید از * به معنای “شنود روی تمام نشانی‌ها” استفاده کنید. در صورت عدم تنظیم، تنها اتصالات سوکت یونیکس پذیرفته می‌شوند.

نشانی‌ها را می‌توان به صورت عددی (IPv4/IPv6) یا با نام مشخص کرد.

پیش‌فرض: تنظیم نشده

پورتی که باید روی آن شنود انجام شود. هم برای TCP و هم سوکت‌های یونیکس اعمال می‌شود.

پیش‌فرض: 6432

محل قرارگیری سوکت‌های یونیکس را مشخص می‌کند. هم برای سوکت شنود و هم برای اتصالات سرور اعمال می‌شود. اگر روی یک رشته خالی تنظیم شود، سوکت‌های یونیکس غیرفعال می‌شوند. مقداری که با @ آغاز شود، مشخص می‌کند که باید یک سوکت یونیکس در فضای نام انتزاعی (abstract namespace) ایجاد شود (در حال حاضر در لینوکس و ویندوز پشتیبانی می‌شود).

برای اینکه راه‌اندازی مجدد برخط (-R) کار کند، یک سوکت یونیکس باید پیکربندی شده باشد و در فضای نام فایل‌سیستم قرار داشته باشد.

پیش‌فرض: /tmp (در ویندوز خالی)

حالت دسترسی فایل‌سیستم برای سوکت یونیکس. برای سوکت‌های موجود در فضای نام انتزاعی نادیده گرفته می‌شود. در ویندوز پشتیبانی نمی‌شود.

پیش‌فرض: 0777

نام گروه مورد استفاده برای سوکت یونیکس. برای سوکت‌های موجود در فضای نام انتزاعی نادیده گرفته می‌شود. در ویندوز پشتیبانی نمی‌شود.

پیش‌فرض: تنظیم نشده

در صورت تنظیم، کاربر یونیکس را برای تغییر هویت پس از راه‌اندازی مشخص می‌کند. تنها در صورتی کار می‌کند که PgBouncer به عنوان ریشه (root) آغاز شده باشد یا از قبل با کاربر مشخص‌شده در حال اجرا باشد. در ویندوز پشتیبانی نمی‌شود.

پیش‌فرض: تنظیم نشده

مشخص می‌کند که چه زمانی یک اتصال سرور می‌تواند توسط کلاینت‌های دیگر مجدداً استفاده شود.

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

حداکثر تعداد مجاز اتصالات کلاینت.

هنگامی که این تنظیم افزایش می‌یابد، ممکن است محدودیت توصیف‌گرهای فایل (file descriptor) در سیستم‌عامل نیز نیاز به افزایش داشته باشد. توجه داشته باشید که تعداد توصیف‌گرهای فایل بالقوه مورد استفاده بیش از max_client_conn است. اگر هر کاربر با نام کاربری خود به سرور متصل شود، حداکثر نظری استفاده‌شده برابر است با:

max_client_conn + (max pool_size * total databases * total users)

اگر یک کاربر پایگاه‌داده در رشته اتصال مشخص شده باشد (تمام کاربران با یک نام کاربری یکسان متصل شوند)، حداکثر نظری برابر است با:

max_client_conn + (max pool_size * total databases)

حداکثر مقدار نظری هرگز نباید رخ دهد، مگر اینکه شخصی عمداً بار کاری ویژه‌ای برای آن ایجاد کرده باشد. با این وجود، به این معنی است که باید تعداد توصیف‌گرهای فایل را روی مقداری به اندازه کافی بالا و ایمن تنظیم کنید.

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

پیش‌فرض: 100

حداکثر تعداد اتصالات سرور مجاز به ازای هر جفت کاربر/پایگاه‌داده. می‌تواند توسط pool_size در پیکربندی به ازای هر پایگاه‌داده و به ازای هر کاربر بازنویسی شود؛ این مقدار پیش‌فرضی است که در صورت عدم تعیین مشخص pool_size برای یک پایگاه‌داده یا کاربر معین، استفاده می‌شود.

پیش‌فرض: 20

اگر تعداد اتصالات سرور کمتر از این مقدار باشد، اتصالات بیشتری به استخر اضافه می‌کند. رفتار سیستم را زمانی که بار کاری عادی پس از دوره‌ای از عدم فعالیت کامل ناگهان بازمی‌گردد، بهبود می‌بخشد. این مقدار عملاً در سقف اندازه استخر (pool size) محدود می‌شود.

تنها برای استخرهایی اعمال می‌شود که حداقل یکی از موارد زیر برقرار باشد:

•
مدخل مربوطه در بخش [database] برای آن استخر، مقداری برای کلید user تنظیم کرده باشد (کاربر اجباری).
•
حداقل یک کلاینت به استخر متصل باشد.

پیش‌فرض: 0 (غیرفعال)

چه تعداد اتصال اضافی به یک استخر مجاز است (گزینه reserve_pool_timeout را ببینید). مقدار 0 آن را غیرفعال می‌کند.

پیش‌فرض: 0 (غیرفعال)

اگر کلاینتی در این مدت سرویس دریافت نکند، از اتصالات اضافی استخر ذخیره استفاده می‌شود. مقدار 0 آن را غیرفعال می‌کند. [ثانیه]

پیش‌فرض: 5.0

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

این گزینه را می‌توان به ازای هر پایگاه‌داده در بخش [databases] نیز تنظیم کرد.

توجه داشته باشید که با رسیدن به این محدودیت، بستن اتصال یک کلاینت به یک استخر بلافاصله اجازه برقراری اتصال سرور برای استخر دیگری را نمی‌دهد، زیرا اتصال سرور برای استخر اول همچنان باز است. به محض اینکه اتصال سرور (به دلیل مهلت عدم فعالیت) بسته شود، بلافاصله یک اتصال سرور جدید برای استخر در حال انتظار باز خواهد شد.

پیش‌فرض: 0 (نامحدود)

اجازه ندهید اتصالات کلاینت به PgBouncer به ازای هر پایگاه‌داده بیش از این مقدار شود (صرف‌نظر از کاربر). این گزینه پایگاه‌داده PgBouncer را که کلاینت به آن متصل شده در نظر می‌گیرد، نه پایگاه‌داده PostgreSQL اتصال خروجی را.

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

این گزینه را می‌توان به ازای هر پایگاه‌داده در بخش [databases] نیز تنظیم کرد.

پیش‌فرض: 0 (نامحدود)

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

این گزینه را می‌توان به ازای هر کاربر در بخش [users] نیز تنظیم کرد.

توجه داشته باشید که با رسیدن به این محدودیت، بستن اتصال یک کلاینت به یک استخر بلافاصله اجازه برقراری اتصال سرور برای استخر دیگری را نمی‌دهد، زیرا اتصال سرور برای استخر اول همچنان باز است. به محض اینکه اتصال سرور (به دلیل مهلت عدم فعالیت) بسته شود، بلافاصله یک اتصال سرور جدید برای استخر در حال انتظار باز خواهد شد.

پیش‌فرض: 0 (نامحدود)

اجازه ندهید اتصالات کلاینت به ازای هر کاربر بیش از این مقدار شود (صرف‌نظر از پایگاه‌داده). این مقدار باید روی عددی بزرگ‌تر از max_user_connections تنظیم شود. تفاوت بین max_user_connections و max_user_client_connections را می‌توان به عنوان حداکثر اندازه صف برای کاربر در نظر گرفت.

این گزینه را می‌توان به ازای هر کاربر در بخش [users] نیز تنظیم کرد.

پیش‌فرض: 0 (نامحدود)

به طور پیش‌فرض، PgBouncer از اتصالات سرور به روش LIFO (آخرین ورودی، اولین خروجی) مجدداً استفاده می‌کند تا اتصالات کمتری بیشترین بار کاری را دریافت کنند. این روش در صورتی که یک سرور منفرد سرویس‌دهنده به پایگاه‌داده داشته باشید، بهترین کارایی را به همراه دارد. اما اگر سیستم نوبت‌گردشی (round-robin) در پشت نشانی پایگاه‌داده وجود داشته باشد (TCP، DNS یا فهرستی از میزبان‌ها)، بهتر است PgBouncer نیز اتصالات را به همین شیوه استفاده کند تا بار کاری یکنواختی حاصل شود.

پیش‌فرض: 0

به طور پیش‌فرض، PgBouncer پارامترهای client_encoding، datestyle، timezone، standard_conforming_strings و application_name را به ازای هر کلاینت رهگیری می‌کند. برای اینکه امکان رهگیری سایر پارامترها نیز فراهم شود، می‌توان آن‌ها را در اینجا مشخص کرد تا PgBouncer بداند که باید در حافظه نهان متغیرهای کلاینت نگهداری شده و هر زمان که کلاینت فعال شد در سرور بازیابی شوند.

اگر نیاز به تعیین چندین مقدار دارید، از یک فهرست جداشده با کاما استفاده کنید (مانند default_transaction_read_only, IntervalStyle)

نکته: بیشتر پارامترها را نمی‌توان از این طریق رهگیری کرد. تنها پارامترهایی قابل رهگیری هستند که Postgres به کلاینت گزارش می‌دهد. پستگرس فهرست رسمی از پارامترهایی که به کلاینت گزارش می‌دهد دارد. با این حال، افزونه‌های Postgres می‌توانند این فهرست را تغییر دهند؛ آن‌ها می‌توانند پارامترهایی را خودشان اضافه کرده و گزارش دهند، و می‌توانند شروع به گزارش پارامترهای از قبل موجودی کنند که Postgres گزارش نمی‌دهد. به ویژه Citus 12.0+ باعث می‌شود Postgres پارامتر search_path را نیز گزارش دهد.

پروتکل Postgres امکان تعیین تنظیمات پارامترها را فراهم می‌کند؛ هم مستقیماً به عنوان یک پارامتر در بسته راه‌اندازی (startup packet)، و هم درون بسته راه‌اندازی options. پارامترهایی که با استفاده از هر دو روش مشخص شده‌اند توسط track_extra_parameters پشتیبانی می‌شوند. با این وجود، گنجاندن خود options در track_extra_parameters امکان‌پذیر نیست و فقط پارامترهای موجود در options مجاز هستند.

پیش‌فرض: IntervalStyle

به طور پیش‌فرض، PgBouncer تنها به پارامترهایی در بسته‌های راه‌اندازی اجازه می‌دهد که بتواند آن‌ها را رهگیری کند: client_encoding، datestyle، timezone و standard_conforming_strings. تمام پارامترهای دیگر خطایی ایجاد خواهند کرد. برای مجاز کردن پارامترهای دیگر، می‌توان آن‌ها را در اینجا مشخص کرد تا PgBouncer بداند توسط مدیر سیستم مدیریت می‌شوند و می‌تواند آن‌ها را نادیده بگیرد.

اگر نیاز به تعیین چندین مقدار دارید، از یک فهرست جداشده با کاما استفاده کنید (مانند options,extra_float_digits)

پروتکل Postgres امکان تعیین تنظیمات پارامترها را فراهم می‌کند؛ هم مستقیماً به عنوان یک پارامتر در بسته راه‌اندازی، و هم درون بسته راه‌اندازی options. پارامترهایی که با استفاده از هر دو روش مشخص شده‌اند توسط ignore_startup_parameters پشتیبانی می‌شوند. حتی امکان گنجاندن خود options در track_extra_parameters نیز وجود دارد که باعث می‌شود هر پارامتر ناشناخته موجود در options نادیده گرفته شود.

پیش‌فرض: خالی

شناسه همتا (peer id) برای شناسایی این فرآیند PgBouncer در گروهی از فرآیندهای همتای PgBouncer استفاده می‌شود. مقدار peer_id باید درون یک گروه از فرآیندهای همتای PgBouncer یکتا باشد. هنگامی که روی 0 تنظیم شود، قابلیت همتایی PgBouncer غیرفعال است. برای اطلاعات بیشتر، اسناد بخش [peers] را ببینید. حداکثر مقداری که می‌تواند برای peer_id استفاده شود 16383 است.

پیش‌فرض: 0

غیرفعال کردن پروتکل پرس‌وجوی ساده (Simple Query protocol یا PQexec). برخلاف پروتکل پرس‌وجوی گسترده (Extended Query protocol)، پروتکل پرس‌وجوی ساده اجازه اجرای چندین پرس‌وجو در یک بسته را می‌دهد که امکان برخی از انواع حملات تزریق SQL (SQL-injection) را فراهم می‌کند. غیرفعال کردن آن می‌تواند امنیت را بهبود ببخشد. بدیهی است این به این معنی است که تنها کلاینت‌هایی که منحصراً از پروتکل پرس‌وجوی گسترده استفاده می‌کنند به کار خود ادامه خواهند داد.

پیش‌فرض: 0

افزودن نشانی میزبان و پورت کلاینت به تنظیم application name که در ابتدای برقراری اتصال تعیین می‌شود. این کار به شناسایی منبع پرس‌وجوهای نامناسب و مواردی از این دست کمک می‌کند. این منطق تنها در ابتدای اتصال اعمال می‌شود. اگر application_name بعداً با دستور SET تغییر کند، PgBouncer مجدداً آن را تغییر نمی‌دهد.

پیش‌فرض: 0

محل فایل پیکربندی فعلی را نشان می‌دهد. تغییر آن باعث می‌شود PgBouncer در دستور بعدی RELOAD یا SIGHUP از فایل پیکربندی دیگری استفاده کند.

پیش‌فرض: فایل مشخص‌شده از خط فرمان

مورد استفاده در ثبت سرویس در سیستم‌های win32.

پیش‌فرض: pgbouncer

نام مستعار برای service_name.

مشخص می‌کند که میانگین‌های نمایش‌داده‌شده در دستورات مختلف SHOW هر چند وقت یک‌بار به‌روزرسانی شوند و آمار تجمیعی هر چند وقت یک‌بار در لاگ نوشته شوند (اما گزینه log_stats را نیز ببینید). [ثانیه]

پیش‌فرض: 60

هنگامی که این مقدار روی یک مقدار غیر صفر تنظیم شود، PgBouncer دستورات مرتبط با عبارات آماده‌شده (prepared statements) نام‌گذاری‌شده در سطح پروتکل را که توسط کلاینت در حالت‌های استخربندی تراکنش (transaction) و عبارت (statement) ارسال می‌شوند، رهگیری می‌کند. PgBouncer اطمینان حاصل می‌کند که هر عبارت آماده‌شده توسط کلاینت، روی اتصال سرور پشتیبان در دسترس باشد؛ حتی زمانی که عبارت در ابتدا روی اتصال سرور دیگری آماده شده باشد.

PgBouncer به صورت داخلی تمام پرس‌وجوهایی را که توسط کلاینت‌ها به عنوان یک عبارت آماده‌شده ارسال می‌شوند بررسی می‌کند و به هر رشته پرس‌وجوی یکتا، یک نام داخلی با قالب PGBOUNCER_{unique_id} اختصاص می‌دهد. اگر همان رشته پرس‌وجو چندین بار آماده شود (احتمالاً توسط کلاینت‌های مختلف)، این پرس‌وجوها نام داخلی یکسانی را به اشتراک می‌گذارند. PgBouncer عبارت را تنها روی سرور واقعی PostgreSQL با استفاده از نام داخلی (و نه نام ارائه‌شده توسط کلاینت) آماده می‌کند. PgBouncer نامی را که کلاینت به هر عبارت آماده‌شده داده است رهگیری می‌کند. سپس هر دستوری را که از یک عبارت آماده‌شده استفاده می‌کند، با جایگزین کردن نام سمت کلاینت با نام داخلی (برای مثال جایگزینی my_prepared_statement با PGBOUNCER_123) پیش از ارسال آن دستور به سرور، بازنویسی می‌کند. مهم‌تر از همه، اگر عبارت آماده‌شده‌ای که کلاینت می‌خواهد اجرا کند هنوز روی سرور آماده نشده باشد (مثلاً به این دلیل که سرور متفاوتی نسبت به زمان آماده‌سازی عبارت به کلاینت اختصاص یافته است)، PgBouncer پیش از اجرای عبارت، آن را به طور شفاف آماده می‌کند.

نکته: این رهگیری و بازنویسی دستورات عبارت آماده‌شده برای دستورات عبارت آماده‌شده در سطح SQL کار نمی‌کند، بنابراین دستورات PREPARE، EXECUTE و DEALLOCATE مستقیماً به Postgres ارسال می‌شوند. استثنای این قاعده دستورات DEALLOCATE ALL و DISCARD ALL هستند؛ این دستورات مطابق انتظار عمل کرده و عبارات آماده‌شده‌ای را که PgBouncer برای کلاینت ارسال‌کننده رهگیری کرده است، پاک می‌کنند.

مقدار واقعی این تنظیم تعداد عبارات آماده‌شده‌ای را کنترل می‌کند که در یک حافظه نهان LRU روی یک اتصال سرور منفرد فعال نگه داشته می‌شوند. هنگامی که این تنظیم روی 0 باشد، پشتیبانی از عبارت آماده‌شده برای استخربندی تراکنش و عبارت غیرفعال است. برای دستیابی به بهترین کارایی، باید سعی کنید مطمئن شوید که این تنظیم بزرگ‌تر از تعداد عبارات آماده‌شده متداول مورد استفاده در برنامه شما است. به خاطر داشته باشید که هر چه این مقدار بالاتر باشد، ردپای حافظه هر اتصال PgBouncer روی سرور PostgreSQL شما بزرگ‌تر خواهد بود، زیرا پرس‌وجوهای بیشتری را روی آن اتصالات آماده نگه می‌دارد. همچنین ردپای حافظه خود PgBouncer را افزایش می‌دهد، زیرا اکنون نیاز به رهگیری رشته‌های پرس‌وجو دارد.

با این حال، تأثیر آن بر مصرف حافظه PgBouncer چندان زیاد نیست: - هر پرس‌وجوی یکتا یک بار در حافظه نهان سراسری پرس‌وجو ذخیره می‌شود. - هر اتصال کلاینت بافری را نگه می‌دارد که از آن برای بازنویسی بسته‌ها استفاده می‌کند. این مقدار حداکثر ۴ برابر اندازه pkt_buf است. این حد معمولاً پر نمی‌شود، مگر زمانی که پرس‌وجوهای موجود در عبارات آماده‌شده شما بین ۲ تا ۴ برابر اندازه pkt_buf باشند.

بنابراین اگر سناریوی زیر را به عنوان مثال در نظر بگیرید: - ۱۰۰۰ کلاینت فعال وجود دارد - کلاینت‌ها ۲۰۰ پرس‌وجوی یکتا آماده می‌کنند - میانگین اندازه یک پرس‌وجو ۵ کیلوبایت است - پارامتر pkt_buf روی مقدار پیش‌فرض 4096 (۴ کیلوبایت) تنظیم شده است

در این حالت، PgBouncer حداکثر به مقدار حافظه زیر برای مدیریت این عبارات آماده نیاز دارد:

200 x 5kB + 1000 x 4 x 4kB = ~17MB حافظه.

رهگیری عبارات آماده‌شده نه تنها هزینه حافظه دارد، بلکه مصرف CPU را نیز افزایش می‌دهد، زیرا PgBouncer باید پرس‌وجوها را بررسی و بازنویسی کند. چندین نمونه PgBouncer می‌توانند روی یک پورت مشترک شنود کنند تا از بیش از یک هسته پردازشی استفاده شود؛ برای جزئیات به اسناد گزینه so_reuseport مراجعه کنید.

اما مسلماً عبارات آماده‌شده مزایای کارایی نیز دارند. درست همانند اتصال مستقیم به PostgreSQL، آماده‌سازی پرس‌وجویی که بارها اجرا می‌شود، میزان کلی پارس کردن و برنامه‌ریزی اجرایی مورد نیاز را کاهش می‌دهد. روشی که PgBouncer عبارات آماده را رهگیری می‌کند، به‌ویژه زمانی که چندین کلاینت پرس‌وجوهای یکسانی را آماده می‌کنند، برای کارایی بسیار سودمند است؛ زیرا اتصالات کلاینت به طور خودکار از یک عبارت آماده‌شده روی یک اتصال سرور مجدداً استفاده می‌کنند، حتی اگر توسط کلاینت دیگری آماده شده باشد. به عنوان مثال، اگر pool_size برابر با 20 داشته باشید و ۱۰۰ کلاینت داشته باشید که همگی دقیقاً یک پرس‌وجوی یکسان را آماده می‌کنند، پرس‌وجو تنها ۲۰ بار روی سرور PostgreSQL آماده (و بنابراین پارس) می‌شود.

استفاده مجدد از عبارات آماده‌شده یک جنبه منفی دارد. اگر نوع داده‌های برگشتی یا آرگومان‌های یک عبارت آماده در طول اجراها تغییر کند، PostgreSQL در حال حاضر خطایی مانند زیر صادر می‌کند:

ERROR:  cached plan must not change result type

می‌توانید با پرهیز از داشتن چندین کلاینت که از یک رشته پرس‌وجوی دقیقاً یکسان در یک عبارت آماده استفاده می‌کنند اما انتظار انواع آرگومان یا نتیجه متفاوتی دارند، از چنین خطاهایی جلوگیری کنید. یکی از رایج‌ترین راه‌های مواجهه با این مشکل در طول مهاجرت‌های DDL است که در آن ستون جدیدی اضافه می‌کنید یا نوع یک ستون را در یک جدول موجود تغییر می‌دهید. در این موارد می‌توانید پس از انجام مهاجرت، دستور RECONNECT را روی کنسول مدیریتی PgBouncer اجرا کنید تا آماده‌سازی مجدد پرس‌وجو اجباری شده و خطا برطرف شود.

پیش‌فرض: 200

تعداد تکرارهای محاسباتی که باید هنگام رمزگذاری گذرواژه با استفاده از SCRAM-SHA-256 انجام شود. تعداد تکرار بالاتر، محافظت بیشتری در برابر حملات جستجوی فراگیر (brute-force) روی گذرواژه‌های ذخیره‌شده فراهم می‌کند، اما احراز هویت را کندتر می‌سازد.

پیش‌فرض: 4096

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

نحوه احراز هویت کاربران.

کلاینت باید از طریق اتصال TLS با یک گواهی کلاینت معتبر متصل شود. سپس نام کاربری از فیلد CommonName گواهی گرفته می‌شود.
استفاده از بررسی گذرواژه مبتنی بر MD5. این روش پیش‌فرض احراز هویت است. فایل auth_file می‌تواند شامل گذرواژه‌های رمزگذاری‌شده با MD5 و متن ساده باشد. اگر md5 پیکربندی شده باشد و کاربر دارای یک رمز امن SCRAM باشد، احراز هویت SCRAM به طور خودکار به جای آن استفاده می‌شود.
استفاده از بررسی گذرواژه با SCRAM-SHA-256. فایل auth_file باید شامل مقادیر محرمانه SCRAM یا گذرواژه‌های متن ساده باشد.
گذرواژه با متن ساده از طریق شبکه ارسال می‌شود. منسوخ شده است.
هیچ احراز هویتی انجام نمی‌شود. نام کاربری همچنان باید در auth_file وجود داشته باشد.
مانند روش trust است، اما نام کاربری ارائه‌شده نادیده گرفته می‌شود. مستلزم آن است که تمام پایگاه‌های داده برای ورود به عنوان یک کاربر خاص پیکربندی شده باشند. علاوه بر این، پایگاه‌داده کنسول به هر کاربری اجازه می‌دهد به عنوان مدیر وارد شود.
نوع واقعی احراز هویت از auth_hba_file بارگیری می‌شود. این امکان استفاده از روش‌های مختلف احراز هویت را برای مسیرهای دسترسی مختلف فراهم می‌کند، برای مثال: اتصالات از طریق سوکت یونیکس از روش احراز هویت peer استفاده کنند، اتصالات از طریق TCP باید از TLS استفاده کنند.
کاربران در برابر یک سرور LDAP احراز هویت می‌شوند، مشابه PostgreSQL (برای جزئیات https://www.postgresql.org/docs/current/auth-ldap.html را ببینید). گزینه‌های اتصال LDAP با استفاده از تنظیم auth_ldap_options، یا به عنوان جایگزین در auth_hba_file پیکربندی می‌شوند.
از PAM برای احراز هویت کاربران استفاده می‌شود، auth_file نادیده گرفته می‌شود. این روش با پایگاه‌های داده‌ای که از گزینه auth_user استفاده می‌کنند سازگار نیست. نام سرویس گزارش‌شده به PAM برابر با “pgbouncer” است. گزینه pam در فایل پیکربندی HBA پشتیبانی نمی‌شود.

فایل پیکربندی HBA مورد استفاده هنگامی که auth_type برابر با hba باشد. برای جزئیات به بخش قالب فایل HBA در زیر مراجعه کنید.

پیش‌فرض: تنظیم نشده

فایل نگاشت هویت (identity map) مورد استفاده هنگامی که auth_type برابر با hba باشد و نگاشت کاربر تعریف شده باشد. برای جزئیات به بخش قالب فایل نگاشت Ident در زیر مراجعه کنید.

پیش‌فرض: تنظیم نشده

نام فایلی که نام‌های کاربری و گذرواژه‌ها از آن بارگیری می‌شوند. برای جزئیات به بخش قالب فایل احراز هویت در زیر مراجعه کنید.

بیشتر انواع احراز هویت (به موارد بالا نگاه کنید) نیازمند تنظیم auth_file یا auth_user هستند؛ در غیر این صورت هیچ کاربری تعریف نخواهد شد.

پیش‌فرض: تنظیم نشده

اگر auth_user تنظیم شود، هر کاربری که در auth_file مشخص نشده باشد، از طریق پرس‌وجوی auth_query از جدول pg_authid در پایگاه‌داده و با استفاده از auth_user واکشی می‌شود. گذرواژه auth_user از auth_file گرفته خواهد شد. (اگر auth_user نیازی به گذرواژه نداشته باشد، نیازی به تعریف آن در auth_file نیست.)

دسترسی مستقیم به pg_authid نیازمند دسترسی‌های مدیریتی (admin) است. ترجیح داده می‌شود از یک کاربر غیر ارشد استفاده شود که تابعی با مشخصه SECURITY DEFINER را فراخوانی می‌کند.

پیش‌فرض: تنظیم نشده

پرس‌وجو برای بارگیری گذرواژه کاربر از پایگاه‌داده.

دسترسی مستقیم به pg_authid نیازمند دسترسی‌های مدیریتی است. ترجیح داده می‌شود از یک کاربر غیر ارشد استفاده شود که تابعی با مشخصه SECURITY DEFINER را فراخوانی می‌کند.

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

پیش‌فرض: SELECT rolname, CASE WHEN rolvaliduntil < now() THEN NULL ELSE rolpassword END FROM pg_authid WHERE rolname=$1 AND rolcanlogin

نام پایگاه‌داده در بخش [database] که برای اهداف احراز هویت استفاده می‌شود. این گزینه می‌تواند سراسری باشد یا در صورت تعیین در رشته اتصال، بازنویسی شود.

گزینه‌های اتصال LDAP برای استفاده در صورتی که auth_type برابر با ldap باشد. (اگر احراز هویت از طریق auth_hba_file پیکربندی شده باشد، استفاده نمی‌شود.) مثال:

auth_ldap_options = ldapurl="ldap://127.0.0.1:12345/dc=example,dc=net?uid?sub"

فعال یا غیرفعال کردن syslog. در ویندوز، به جای آن از event log استفاده می‌شود.

پیش‌فرض: 0

نامی که لاگ‌ها تحت آن به syslog ارسال می‌شوند.

پیش‌فرض: pgbouncer (نام برنامه)

فسیلیتی (facility) مورد استفاده برای ارسال لاگ‌ها به syslog. گزینه‌های ممکن: auth، authpriv، daemon، user، local0-7.

پیش‌فرض: daemon

ثبت لاگ ورودهای موفقیت‌آمیز.

پیش‌فرض: 1

ثبت لاگ قطع اتصال‌ها همراه با دلیل.

پیش‌فرض: 1

ثبت لاگ پیام‌های خطایی که استخربند به کلاینت‌ها ارسال می‌کند.

پیش‌فرض: 1

نوشتن آمار تجمیعی در لاگ، در هر دوره stats_period. اگر ابزارهای پایش خارجی برای دریافت همین داده‌ها از دستورات SHOW استفاده شوند، می‌توان این گزینه را غیرفعال کرد.

پیش‌فرض: 1

افزایش سطح جزئیات لاگ‌ها (verbosity). مشابه سوییچ “-v” در خط فرمان عمل می‌کند. برای مثال، استفاده از “-v -v” در خط فرمان همانند verbose=2 است. مقدار 3 بالاترین سطح جزئیات است که در حال حاضر پشتیبانی می‌شود.

پیش‌فرض: 0

فهرست جداشده با کاما از کاربران پایگاه‌داده که مجاز به اتصال و اجرای تمامی دستورات روی کنسول هستند. هنگامی که auth_type برابر با any باشد نادیده گرفته می‌شود؛ در این حالت هر نام کاربری به عنوان مدیر پذیرفته می‌شود.

پیش‌فرض: خالی

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

پیش‌فرض: خالی

پرس‌وجویی که هنگام آزادسازی اتصال و پیش از در دسترس قرار دادن آن برای کلاینت‌های دیگر، به سرور ارسال می‌شود. در آن لحظه هیچ تراکنشی در حال انجام نیست، بنابراین این مقدار نباید شامل ABORT یا ROLLBACK باشد.

این پرس‌وجو قرار است هرگونه تغییرات اعمال‌شده در نشست پایگاه‌داده را پاک کند تا کلاینت بعدی اتصال را در یک وضعیت کاملاً مشخص و معین دریافت نماید. مقدار پیش‌فرض DISCARD ALL است که همه چیز را پاک می‌کند، اما این کار هیچ وضعیت از پیش کش‌شده‌ای برای کلاینت بعدی باقی نمی‌گذارد. می‌توان آن را سبک‌تر کرد، برای مثال DEALLOCATE ALL تنها برای حذف عبارات آماده، در صورتی که برنامه با حفظ برخی از وضعیت‌ها دچار اختلال نشود.

هنگامی که استخربندی تراکنش (transaction pooling) استفاده می‌شود، server_reset_query استفاده نمی‌شود، زیرا در این حالت، کلاینت‌ها نباید از هیچ‌یک از ویژگی‌های مبتنی بر نشست استفاده کنند؛ چرا که هر تراکنش به یک اتصال متفاوت ختم شده و بنابراین وضعیت نشست متفاوتی دریافت می‌کند.

پیش‌فرض: DISCARD ALL

آیا server_reset_query باید در تمام حالت‌های استخربندی اجرا شود یا خیر. هنگامی که این تنظیم خاموش است (پیش‌فرض)، دستور server_reset_query تنها در استخرهایی اجرا می‌شود که در حالت استخربندی نشست (session pooling) قرار دارند. اتصالات در حالت استخربندی تراکنش نباید نیازی به پرس‌وجوی بازنشانی داشته باشند.

این تنظیم برای دور زدن پیکربندی‌های نامناسبی است که برنامه‌های استفاده‌کننده از ویژگی‌های نشست را روی PgBouncer با استخربندی تراکنش اجرا می‌کنند. این کار خطاهای غیر قطعی را به خطای قطعی تبدیل می‌کند: کلاینت‌ها همیشه وضعیت خود را پس از هر تراکنش از دست می‌دهند.

پیش‌فرض: 0

مدت زمانی که اتصالات آزادشده بدون اجرای server_check_query روی آن‌ها، برای استفاده مجدد فوری در دسترس نگه داشته می‌شوند. اگر 0 باشد، بررسی همیشه اجرا می‌شود.

پیش‌فرض: 30.0

پرس‌وجوی ساده و بی‌اثر برای بررسی زنده بودن اتصال سرور.

اگر یک رشته خالی باشد، بررسی سلامت غیرفعال می‌شود.

اگر <empty> باشد، یک پرس‌وجوی خالی به عنوان بررسی سلامت ارسال می‌شود.

پیش‌فرض: <empty>

قطع اتصال فوری سرور در حالت استخربندی نشست یا پس از پایان تراکنش فعلی در صورتی که در حالت “close_needed” باشد (تنظیم‌شده توسط RECONNECT، یا RELOAD که تنظیمات اتصال را تغییر می‌دهد، یا تغییر DNS)، به جای انتظار برای پایان نشست. در حالت استخربندی عبارت یا تراکنش، این گزینه تاثیری ندارد زیرا رفتار پیش‌فرض در آنجا همین است.

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

این تنظیم باعث می‌شود اعمال تغییرات پیکربندی اتصال، در صورت استفاده از استخربندی نشست و نشست‌های طولانی‌مدت، سریع‌تر اثر کند. نقطه ضعف این است که نشست‌های کلاینت ممکن است با یک تغییر پیکربندی قطع شوند، بنابراین برنامه‌های کلاینت نیاز به منطقی برای اتصال مجدد و برقراری مجدد وضعیت نشست خواهند داشت. اما توجه داشته باشید که هیچ تراکنشی از بین نخواهد رفت، زیرا تراکنش‌های در حال اجرا قطع نمی‌شوند، بلکه فقط نشست‌های بیکار قطع خواهند شد.

پیش‌فرض: 0

استخربند یک اتصال سرور استفاده‌نشده (که در حال حاضر به هیچ اتصال کلاینتی متصل نیست) را که بیش از این مدت متصل بوده باشد می‌بندد. تنظیم آن روی 0 به این معنی است که اتصال تنها یک بار استفاده شده و سپس بسته می‌شود. [ثانیه]

این گزینه را می‌توان به ازای هر پایگاه‌داده در بخش [databases] نیز تنظیم کرد.

پیش‌فرض: 3600.0

اگر یک اتصال سرور بیش از این تعداد ثانیه بیکار بوده باشد، بسته خواهد شد. اگر 0 باشد، این مهلت زمانی غیرفعال می‌شود. [ثانیه]

پیش‌فرض: 600.0

اگر برقراری اتصال و ورود در این مدت زمان به پایان نرسد، اتصال بسته خواهد شد. [ثانیه]

پیش‌فرض: 15.0

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

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

پیش‌فرض: 15.0

اگر کلاینتی متصل شود اما در این مدت زمان موفق به ورود نشود، اتصال آن قطع خواهد شد. عمدتاً برای جلوگیری از اتصالات مرده‌ای که مانع از اجرای SUSPEND و در نتیجه راه‌اندازی مجدد برخط می‌شوند مورد نیاز است. [ثانیه]

پیش‌فرض: 60.0

اگر استخرهای پایگاه‌داده ایجادشده به صورت خودکار (از طریق “*“) به مدت این تعداد ثانیه استفاده نشده باشند، آزاد می‌شوند. جنبه منفی این کار این است که آمارهای آن‌ها نیز فراموش می‌شود. [ثانیه]

پیش‌فرض: 3600.0

مدت زمانی که جستجوهای DNS می‌توانند در حافظه نهان ذخیره شوند. مقدار واقعی TTL در DNS نادیده گرفته می‌شود. [ثانیه]

پیش‌فرض: 15.0

مدت زمانی که خطاهای DNS و جستجوهای NXDOMAIN DNS می‌توانند در حافظه نهان ذخیره شوند. [ثانیه]

پیش‌فرض: 15.0

دوره زمانی برای بررسی اینکه آیا شماره سریال منطقه (zone serial) تغییر کرده است یا خیر.

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

تنها با بک‌اند c-ares (گزینه --with-cares در configure) کار می‌کند.

پیش‌فرض: 0.0 (غیرفعال)

محل فایل سفارشی resolv.conf. این گزینه برای امکان تعیین سرورهای DNS سفارشی و احتمالاً سایر گزینه‌های تفکیک نام، مستقل از پیکربندی سراسری سیستم‌عامل است.

نیازمند بک‌اند evdns (نسخه 2.0.3 یا بالاتر) یا c-ares (نسخه 1.15.0 یا بالاتر) است.

تجزیه و پارس این فایل توسط کتابخانه بک‌اند DNS انجام می‌شود و نه PgBouncer؛ بنابراین برای جزئیات مربوط به نحو و دستورات مجاز، به اسناد کتابخانه مراجعه کنید.

پیش‌فرض: خالی (استفاده از پیش‌فرض‌های سیستم‌عامل)

مدت زمانی که کلاینت در صف باقی می‌ماند پیش از اینکه PgBouncer یک پیام اعلان مبنی بر در صف بودن ارسال کند. [ثانیه]

مقدار 0 این پیام اعلان را غیرفعال می‌کند.

پیش‌فرض: 5

اگر محتوای هر یک از فایل‌های گواهی (cert) یا کلید (key) بدون تغییر نام فایل در تنظیمات پیکربندی تغییر داده شود، محتوای فایل جدید برای اتصالات جدید پس از دستور RELOAD استفاده خواهد شد. با این حال، اتصالات موجود بسته نخواهند شد. اگر به دلایل امنیتی لازم باشد که تمام اتصالات در سریع‌ترین زمان ممکن از فایل‌های جدید استفاده کنند، توصیه می‌شود پس از RELOAD دستور RECONNECT اجرا شود.

تغییر هر یک از تنظیمات TLS به دلایل امنیتی به طور خودکار دستور RECONNECT را فعال می‌کند.

حالت TLS مورد استفاده برای اتصالات کلاینت‌ها. اتصالات TLS به طور پیش‌فرض غیرفعال هستند. در صورت فعال بودن، گزینه‌های client_tls_key_file و client_tls_cert_file نیز باید پیکربندی شوند تا کلید و گواهی مورد استفاده PgBouncer برای پذیرش اتصالات کلاینت تنظیم شوند. رایج‌ترین قالب فایل گواهی قابل استفاده توسط PgBouncer قالب PEM است.

استفاده از TCP ساده. اگر کلاینت درخواست TLS دهد، نادیده گرفته می‌شود. پیش‌فرض.
اگر کلاینت درخواست TLS دهد، استفاده می‌شود. اگر نه، از TCP ساده استفاده می‌شود. اگر کلاینت یک گواهی کلاینت ارائه دهد، اعتبارسنجی نمی‌شود.
مشابه allow.
کلاینت باید از TLS استفاده کند. در غیر این صورت، اتصال کلاینت رد می‌شود. اگر کلاینت گواهی کلاینت ارائه دهد، اعتبارسنجی نمی‌شود.
کلاینت باید از TLS به همراه یک گواهی کلاینت معتبر استفاده کند.
مشابه verify-ca.

کلید خصوصی برای PgBouncer جهت پذیرش اتصالات کلاینت.

پیش‌فرض: تنظیم نشده

گواهی برای کلید خصوصی. کلاینت‌ها می‌توانند آن را اعتبارسنجی کنند.

پیش‌فرض: تنظیم نشده

فایل گواهی ریشه (Root CA) برای اعتبارسنجی گواهی‌های کلاینت.

پیش‌فرض: تنظیم نشده

کدام نسخه‌های پروتکل TLS مجاز هستند. مقادیر مجاز: tlsv1.0، tlsv1.1، tlsv1.2، tlsv1.3. میان‌برها: all (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3)، secure (tlsv1.2,tlsv1.3).

پیش‌فرض: secure

رمزهای مجاز TLS، در نحو OpenSSL. میان‌برها:

•
default/secure/fast/normal (همگی از پیش‌فرض‌های سرتاسری سیستم در OpenSSL استفاده می‌کنند)
•
all (تمامی رمزها را فعال می‌کند، توصیه نمی‌شود)

تنها اتصالات با نسخه TLS 1.2 و پایین‌تر تحت تأثیر قرار می‌گیرند. برای نسخه 1.3 به گزینه client_tls13_ciphers در زیر مراجعه کنید.

پیش‌فرض: default

رمزهای مجاز TLS نسخه 1.3. در صورت خالی بودن، از مقدار client_tls_ciphers استفاده خواهد کرد. مقادیر مجاز:

•
TLS_AES_256_GCM_SHA384
•
TLS_CHACHA20_POLY1305_SHA256
•
TLS_AES_128_GCM_SHA256
•
TLS_AES_128_CCM_8_SHA256
•
TLS_AES_128_CCM_SHA256

تنها اتصالاتی که از نسخه TLS 1.3 و بالاتر استفاده می‌کنند تحت تأثیر قرار می‌گیرند. برای نسخه 1.2 و پایین‌تر گزینه client_tls_ciphers را ببینید.

پیش‌فرض: <empty>

نام منحنی بیضوی مورد استفاده برای تبادل کلید ECDH.

مقادیر مجاز: none (غیرفعال بودن DH)، auto (ECDH با ۲۵۶ بیت)، نام منحنی

پیش‌فرض: auto

نوع تبادل کلید DHE.

مقادیر مجاز: none (غیرفعال بودن DH)، auto (DH با ۲۰۴۸ بیت)، legacy (DH با ۱۰۲۴ بیت)

پیش‌فرض: auto

حالت TLS مورد استفاده برای اتصالات به سرورهای PostgreSQL. حالت پیش‌فرض prefer است.

استفاده از TCP ساده. حتی درخواست TLS از سرور داده نمی‌شود.
در صورتی که سرور اتصال ساده را رد کند، TLS امتحان می‌شود.
همیشه در ابتدا درخواست اتصال TLS از PostgreSQL داده می‌شود. در صورت رد شدن، اتصال از طریق TCP ساده برقرار خواهد شد. گواهی سرور اعتبارسنجی نمی‌شود. پیش‌فرض.
اتصال حتماً باید از طریق TLS انجام شود. اگر سرور آن را رد کند، تلاشی برای اتصال ساده TCP انجام نمی‌شود. گواهی سرور اعتبارسنجی نمی‌شود.
اتصال باید از طریق TLS باشد و گواهی سرور طبق server_tls_ca_file معتبر باشد. نام میزبان سرور با گواهی مطابقت داده نمی‌شود.
اتصال باید از طریق TLS باشد و گواهی سرور طبق server_tls_ca_file معتبر باشد. نام میزبان سرور باید با اطلاعات گواهی مطابقت داشته باشد.

فایل گواهی ریشه برای اعتبارسنجی گواهی‌های سرور PostgreSQL.

پیش‌فرض: تنظیم نشده

کلید خصوصی برای PgBouncer جهت احراز هویت در برابر سرور PostgreSQL.

پیش‌فرض: تنظیم نشده

گواهی برای کلید خصوصی. سرور PostgreSQL می‌تواند آن را اعتبارسنجی کند.

پیش‌فرض: تنظیم نشده

کدام نسخه‌های پروتکل TLS مجاز هستند. مقادیر مجاز: tlsv1.0، tlsv1.1، tlsv1.2، tlsv1.3. میان‌برها: all (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3)، secure (tlsv1.2,tlsv1.3)، legacy (همه).

پیش‌فرض: secure

رمزهای مجاز TLS، در نحو OpenSSL. میان‌برها:

•
default/secure/fast/normal (همگی از پیش‌فرض‌های سرتاسری سیستم در OpenSSL استفاده می‌کنند)
•
all (تمامی رمزها را فعال می‌کند، توصیه نمی‌شود)

تنها اتصالات با نسخه TLS 1.2 و پایین‌تر تحت تأثیر قرار می‌گیرند. برای نسخه 1.3 به گزینه server_tls13_ciphers در زیر مراجعه کنید.

پیش‌فرض: default

رمزهای مجاز TLS نسخه 1.3. در صورت خالی بودن، از مقدار server_tls_ciphers استفاده خواهد کرد. مقادیر مجاز:

•
TLS_AES_256_GCM_SHA384
•
TLS_CHACHA20_POLY1305_SHA256
•
TLS_AES_128_GCM_SHA256
•
TLS_AES_128_CCM_8_SHA256
•
TLS_AES_128_CCM_SHA256

تنها اتصالاتی که از نسخه TLS 1.3 و بالاتر استفاده می‌کنند تحت تأثیر قرار می‌گیرند. برای نسخه 1.2 و پایین‌تر گزینه client_tls_ciphers را ببینید.

پیش‌فرض: <empty>

تنظیم مهلت‌های زمانی زیر می‌تواند موجب خطاهای غیرمنتظره شود.

پرس‌وجوهایی که اجرای آن‌ها بیشتر از این مقدار طول بکشد لغو می‌شوند. این گزینه فقط باید همراه با یک statement_timeout کمی کوچک‌تر در سمت سرور استفاده شود تا فقط برای مشکلات شبکه اعمال گردد. [ثانیه]

پیش‌فرض: 0.0 (غیرفعال)

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

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

پیش‌فرض: 120.0

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

این تنظیم برای جلوگیری از قفل شدن کلاینت زمانی که درخواست لغو به دلیل از کار افتادن سرور نمی‌تواند ارسال شود، استفاده می‌شود.

پیش‌فرض: 10.0

اتصالات کلاینتی که بیش از این تعداد ثانیه بیکار بمانند بسته می‌شوند. این مقدار باید بزرگ‌تر از تنظیمات طول عمر اتصال در سمت کلاینت باشد و فقط برای مشکلات شبکه مورد استفاده قرار گیرد. [ثانیه]

پیش‌فرض: 0.0 (غیرفعال)

اگر کلاینتی بیش از این مدت در وضعیت “idle in transaction” (بیکار درون تراکنش) باقی بماند، اتصال آن قطع خواهد شد. [ثانیه]

پیش‌فرض: 0.0 (غیرفعال)

اگر کلاینتی بیش از این مدت در وضعیت “in transaction” (درون تراکنش) باقی بماند، اتصال آن قطع خواهد شد. [ثانیه]

پیش‌فرض: 0.0 (غیرفعال)

مدت زمان انتظار برای تخلیه بافر در طول SUSPEND یا راه‌اندازی مجدد (-R). در صورتی که تخلیه بافر موفقیت‌آمیز نباشد، اتصال قطع می‌شود. [ثانیه]

پیش‌فرض: 10

اندازه بافر داخلی برای بسته‌ها. بر اندازه بسته‌های TCP ارسالی و مصرف کلی حافظه تأثیر می‌گذارد. بسته‌های واقعی libpq می‌توانند بزرگ‌تر از این باشند، بنابراین نیازی به تنظیم آن روی مقادیر بزرگ نیست.

پیش‌فرض: 4096

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

پیش‌فرض: 2147483647

آرگومان backlog برای listen(2). مشخص می‌کند چه تعداد تلاش جدید و پاسخ‌داده‌نشده برای اتصال در صف نگهداری شوند. هنگامی که صف پر شود، اتصالات جدید بعدی رد می‌شوند.

پیش‌فرض: 128

تعداد دفعات پردازش داده‌ها روی یک اتصال، پیش از رفتن به اتصال بعدی. بدون این محدودیت، یک اتصال با مجموعه نتایج بزرگ می‌تواند PgBouncer را برای مدت طولانی متوقف کند. یک حلقه به اندازه یک pkt_buf داده را پردازش می‌کند. مقدار 0 به معنای عدم محدودیت است.

پیش‌فرض: 5

مشخص می‌کند که آیا گزینه سوکت SO_REUSEPORT روی سوکت‌های شنود TCP تنظیم شود یا خیر. در برخی سیستم‌عامل‌ها، این امکان اجرای چندین نمونه از PgBouncer را روی همان میزبان با شنود روی یک پورت مشترک فراهم می‌کند و به هسته اجازه می‌دهد اتصالات را به طور خودکار توزیع کند. این گزینه روشی است برای اینکه PgBouncer بتواند از هسته‌های پردازشی (CPU) بیشتری استفاده کند. (PgBouncer تک‌نخی است و به ازای هر نمونه از یک هسته CPU استفاده می‌کند.)

رفتار دقیق بستگی به هسته سیستم‌عامل دارد. در زمان نگارش این متن، این تنظیم تأثیر مورد نظر را در (نسخه‌های به اندازه کافی جدید) لینوکس، DragonFlyBSD و FreeBSD دارد. (در FreeBSD، گزینه سوکت SO_REUSEPORT_LB را به جای آن اعمال می‌کند.) برخی سیستم‌عامل‌های دیگر از این گزینه سوکت پشتیبانی می‌کنند اما تأثیر مورد نظر را نخواهد داشت: این گزینه به چندین فرآیند اجازه می‌دهد به یک پورت متصل شوند اما تنها یکی از آن‌ها اتصالات را دریافت خواهد کرد. برای جزئیات به اسناد setsockopt() سیستم‌عامل خود مراجعه کنید.

در سیستم‌هایی که به هیچ وجه از این گزینه سوکت پشتیبانی نمی‌کنند، روشن کردن این تنظیم منجر به خطا خواهد شد.

هر نمونه PgBouncer روی یک میزبان مشابه، حداقل به تنظیمات متفاوتی برای unix_socket_dir و pidfile، و همچنین logfile در صورت استفاده نیاز دارد. همچنین توجه داشته باشید که در صورت استفاده از این گزینه، دیگر نمی‌توانید به یک نمونه خاص از PgBouncer از طریق TCP/IP متصل شوید، که ممکن است پیامدهایی برای پایش و جمع‌آوری معیارها داشته باشد.

برای اطمینان از اینکه لغو پرس‌وجوها همچنان کار می‌کند، باید قابلیت همتایی PgBouncer را بین فرآیندهای مختلف PgBouncer راه‌اندازی کنید. برای جزئیات به اسناد گزینه پیکربندی peer_id و بخش پیکربندی peers مراجعه فرمایید. همچنین مثالی از به‌کارگیری همتایی و so_reuseport در بخش مثال‌های این اسناد آورده شده است.

پیش‌فرض: 0

گزینه سوکت TCP_DEFER_ACCEPT را تنظیم می‌کند؛ برای جزئیات man 7 tcp را ببینید. (این یک گزینه بولی است: مقدار 1 به معنای فعال بودن است. مقدار واقعی تنظیم‌شده در صورت فعال بودن در حال حاضر روی ۴۵ ثانیه ثابت است.)

در حال حاضر این گزینه فقط در لینوکس پشتیبانی می‌شود.

پیش‌فرض: 1 در لینوکس، در غیر این صورت 0

پیش‌فرض: تنظیم نشده

قابلیت پایه‌ای keepalive را با پیش‌فرض‌های سیستم‌عامل فعال می‌کند.

در لینوکس، پیش‌فرض‌های سیستم عبارتند از tcp_keepidle=7200، tcp_keepintvl=75، tcp_keepcnt=9. احتمالاً در سیستم‌عامل‌های دیگر نیز مشابه هستند.

پیش‌فرض: 1

پیش‌فرض: تنظیم نشده

پیش‌فرض: تنظیم نشده

پیش‌فرض: تنظیم نشده

گزینه سوکت TCP_USER_TIMEOUT را تنظیم می‌کند. این گزینه حداکثر مدت زمانی را بر حسب میلی‌ثانیه مشخص می‌کند که داده‌های ارسال‌شده می‌توانند پیش از بسته شدن اجباری اتصال TCP، بدون تأیید دریافت باقی بمانند. در صورت تنظیم روی 0، از پیش‌فرض سیستم‌عامل استفاده می‌شود.

در حال حاضر این گزینه فقط در لینوکس پشتیبانی می‌شود.

پیش‌فرض: 0

بخش [databases] نام پایگاه‌های داده‌ای را تعریف می‌کند که کلاینت‌های PgBouncer می‌توانند به آن‌ها متصل شوند و مشخص می‌کند که این اتصالات به کجا هدایت خواهند شد. این بخش شامل خطوطی به صورت key=value است مانند:

dbname = connection string

که در آن کلید به عنوان نام پایگاه‌داده و مقدار به عنوان یک رشته اتصال در نظر گرفته می‌شود که متشکل از جفت‌های key=value از پارامترهای اتصال است که در زیر شرح داده شده‌اند (مشابه libpq، اما از خود libpq استفاده نمی‌شود و مجموعه قابلیت‌های در دسترس متفاوت است). مثال:

foodb = host=host1.example.com port=5432
bardb = host=localhost dbname=bazdb

نام پایگاه‌داده می‌تواند شامل نویسه‌های _0-9A-Za-z بدون نیاز به نقل‌قول باشد. نام‌هایی که شامل سایر نویسه‌ها هستند باید با نقل‌قول استاندارد شناسه‌های SQL مشخص شوند: نقل‌قول دوتایی، با “” برای یک بار وقوع نقل‌قول دوتایی.

نام پایگاه‌داده “pgbouncer” برای کنسول مدیریتی رزرو شده است و نمی‌توان از آن به عنوان یک کلید در اینجا استفاده کرد.

نویسه “*” به عنوان پایگاه‌داده جایگزین عمل می‌کند: اگر نام دقیق وجود نداشته باشد، مقدار آن به عنوان رشته اتصال برای پایگاه‌داده درخواستی در نظر گرفته می‌شود. برای مثال، اگر مدخلی به شکل زیر وجود داشته باشد (و مدخل بازنویسی دیگری وجود نداشته باشد)

* = host=foo

آن‌گاه یک اتصال به PgBouncer با مشخص کردن پایگاه‌داده “bar”، عملاً به گونه‌ای رفتار خواهد کرد که گویی مدخلی به شکل

bar = host=foo dbname=bar

وجود دارد (با استفاده از این مزیت که پیش‌فرض برای dbname همان نام پایگاه‌داده سمت کلاینت است؛ بخش زیر را ببینید).

چنین مدخل‌های پایگاه‌داده ایجادشده به صورت خودکار، در صورتی که بیشتر از زمان مشخص‌شده توسط پارامتر autodb_idle_timeout بیکار بمانند، پاکسازی می‌شوند.

نام پایگاه‌داده مقصد.

پیش‌فرض: همان نام پایگاه‌داده سمت کلاینت

نام میزبان یا نشانی IP برای اتصال به آن. نام‌های میزبان در زمان اتصال حل (resolve) می‌شوند و نتیجه طبق پارامتر dns_max_ttl در حافظه نهان ذخیره می‌شود. هنگامی که تفکیک نام یک میزبان تغییر می‌کند، اتصالات سرور موجود هنگامی که آزاد می‌شوند (با توجه به حالت استخربندی) به طور خودکار بسته می‌شوند و اتصالات سرور جدید بلافاصله از تفکیک نام جدید استفاده می‌کنند. اگر DNS چندین نتیجه بازگرداند، آن‌ها به روش نوبت‌گردشی استفاده می‌شوند.

اگر مقدار با / شروع شود، یک سوکت یونیکس در فضای نام فایل‌سیستم استفاده می‌شود. اگر مقدار با @ شروع شود، یک سوکت یونیکس در فضای نام انتزاعی استفاده می‌شود.

می‌توان فهرستی از نام‌های میزبان یا نشانی‌ها را که با کاما جدا شده‌اند مشخص کرد. در این صورت، اتصالات به صورت نوبت‌گردشی برقرار می‌شوند. (اگر یک فهرست میزبان شامل نام‌هایی باشد که به نوبه خود از طریق DNS به چندین نشانی تفکیک می‌شوند، سیستم‌های نوبت‌گردشی مستقل از یکدیگر عمل می‌کنند. این یک وابستگی به پیاده‌سازی است که ممکن است در آینده تغییر کند.) توجه داشته باشید که در یک فهرست، تمام میزبان‌ها باید در همه زمان‌ها در دسترس باشند: هیچ سازوکاری برای نادیده گرفتن میزبان‌های غیرقابل دسترس یا انتخاب میزبان‌های در دسترس از یک فهرست یا موارد مشابه وجود ندارد. (این با مفهوم فهرست میزبان در libpq متفاوت است.) همچنین توجه داشته باشید که این موضوع تنها بر نحوه انتخاب مقصد اتصالات جدید تأثیر می‌گذارد. تنظیم server_round_robin را نیز برای چگونگی انتساب کلاینت‌ها به اتصالات سرور از قبل برقرار شده بررسی کنید.

مثال‌ها:

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

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

پیش‌فرض: 5432

اگر user= تنظیم شود، تمام اتصالات به پایگاه‌داده مقصد با کاربر مشخص‌شده برقرار خواهند شد، به این معنی که تنها یک استخر برای این پایگاه‌داده وجود خواهد داشت.

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

اگر هیچ گذرواژه‌ای در اینجا مشخص نشود، گذرواژه موجود در auth_file برای کاربری که در بالا مشخص شده است استفاده خواهد شد. روش‌های پویای کشف گذرواژه مانند auth_query در حال حاضر در اینجا پشتیبانی نمی‌شوند.

بازنویسی تنظیم سراسری auth_user، در صورت تعیین شدن.

بازنویسی تنظیم سراسری auth_query، در صورت تعیین شدن. کل دستور SQL باید در داخل نقل‌قول تکی (single quote) قرار گیرد.

بازنویسی تنظیم سراسری auth_dbname، در صورت تعیین شدن.

تنظیم حداکثر اندازه استخرها برای این پایگاه‌داده. در صورت عدم تنظیم، از default_pool_size استفاده می‌شود.

تنظیم حداقل اندازه استخر برای این پایگاه‌داده. در صورت عدم تنظیم، از min_pool_size سراسری استفاده می‌شود.

تنها در صورتی اعمال می‌شود که حداقل یکی از موارد زیر برقرار باشد:

•
این مدخل در بخش [database] مقداری برای کلید user تعیین کرده باشد (کاربر اجباری).
•
حداقل یک کلاینت به استخر متصل باشد.

تعیین اتصالات اضافی برای این پایگاه‌داده. در صورت عدم تنظیم، از reserve_pool_size سراسری استفاده می‌شود. به دلایل سازگاری با نسخه‌های پیشین، reserve_pool یک نام مستعار برای این گزینه است.

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

تنظیم حالت استخربندی مختص به این پایگاه‌داده. در صورت عدم تنظیم، از pool_mode پیش‌فرض استفاده می‌شود.

هنگامی که یک فهرست جداشده با کاما در host مشخص شده باشد، load_balance_hosts کنترل می‌کند که کدام مدخل برای یک اتصال جدید انتخاب شود.

نکته: این تنظیم در حال حاضر تنها رفتار توزیع بار را هنگام ارائه چندین میزبان در رشته اتصال کنترل می‌کند، اما زمانی که رکورد DNS یک میزبان منفرد به چندین نشانی IP اشاره دارد اعمال نمی‌شود. این یک قابلیت غایب است، بنابراین در انتشار آینده ممکن است این تنظیم هر دو روش توزیع بار را کنترل کند.

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

توصیه می‌شود مقدار server_login_retry کمتر از مقدار پیش‌فرض تنظیم شود تا تلاش‌های مجدد سریع هنگامی که چندین میزبان در دسترس هستند تضمین گردد.

پیش‌فرض: round-robin

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

پیکربندی حداکثر اتصالات کلاینت در سطح کل پایگاه‌داده. باید همراه با max_client_conn استفاده شود تا تعداد اتصالاتی که PgBouncer مجاز به پذیرش آن‌ها است محدود شود.

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

درخواست client_encoding خاص از سرور.

درخواست datestyle خاص از سرور.

درخواست timezone خاص از سرور.

این بخش شامل خطوطی به صورت key=value است مانند:

user1 = settings

که در آن کلید به عنوان نام کاربر و مقدار به عنوان فهرستی از جفت‌های key=value از تنظیمات پیکربندی مخصوص به این کاربر در نظر گرفته می‌شود. مثال:

user1 = pool_mode=session

تنها تعداد کمی از تنظیمات در اینجا در دسترس هستند.

توجه داشته باشید که هنگام پیکربندی auth_file، اگر کاربری در این بخش تعریف شده باشد اما در auth_file فهرست نشده باشد، PgBouncer در صورت تنظیم بودن auth_user تلاش خواهد کرد از auth_query برای یافتن گذرواژه آن کاربر استفاده کند. اگر auth_user تنظیم نشده باشد، PgBouncer وانمود می‌کند که کاربر وجود دارد و از بازگرداندن پیام‌های “no such user” به کلاینت خودداری می‌کند، اما هیچ گذرواژه ارائه‌شده‌ای را نیز نخواهد پذیرفت.

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

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

تنظیم حالت استخر برای استفاده در تمامی اتصالات این کاربر. در صورت عدم تنظیم، از مقدار پایگاه‌داده یا pool_mode پیش‌فرض استفاده می‌شود.

پیکربندی حداکثر اتصالات سرور برای کاربر (به عنوان مثال تمام استخرهای دارای این کاربر بیش از این تعداد اتصال سرور نخواهند داشت).

تنظیم حداکثر تعداد ثانیه‌هایی که یک پرس‌وجوی کاربر می‌تواند اجرا شود. در صورت تنظیم، این مهلت زمانی بر query_timeout در سطح سرور که در بالا توضیح داده شد تقدم دارد.

تنظیم حداکثر تعداد ثانیه‌هایی که کاربر می‌تواند یک تراکنش بیکار باز داشته باشد. در صورت تنظیم، این مهلت زمانی بر idle_transaction_timeout در سطح سرور که در بالا توضیح داده شد تقدم دارد.

تنظیم حداکثر تعداد ثانیه‌هایی که کاربر می‌تواند یک تراکنش باز داشته باشد. در صورت تنظیم، این مهلت زمانی بر transaction_timeout در سطح سرور که در بالا توضیح داده شد تقدم دارد.

تنظیم حداکثر مدت زمانی بر حسب ثانیه که یک کلاینت مجاز است به طور بیکار به نمونه PgBouncer متصل بماند. در صورت تنظیم، این مهلت زمانی بر client_idle_timeout در سطح سرور که در بالا توضیح داده شد تقدم دارد.

لطفاً توجه داشته باشید که این یک مهلت زمانی بالقوه خطرناک است.

پیکربندی حداکثر اتصالات کلاینت برای کاربر. این معادل کاربری تنظیم max_client_conn است.

بخش [peers] همتاهایی را تعریف می‌کند که PgBouncer می‌تواند درخواست‌های لغو را به آن‌ها ارسال کند و مشخص می‌کند که این درخواست‌های لغو به کجا هدایت خواهند شد.

فرآیندهای PgBouncer می‌توانند با تعریف یک مقدار peer_id و یک بخش [peers] در پیکربندی‌های تمام فرآیندهای PgBouncer، در یک گروه با یکدیگر همتا شوند. این فرآیندهای PgBouncer می‌توانند درخواست‌های لغو را به فرآیندی که از آن منشأ گرفته است ارسال کنند. این امر برای عملکرد صحیح درخواست‌های لغو زمانی که چندین فرآیند PgBouncer (احتمالاً روی سرورهای مختلف) پشت یک توزیع‌کننده بار TCP (TCP load balancer) قرار دارند ضروری است. درخواست‌های لغو روی اتصالات TCP متفاوتی نسبت به پرس‌وجویی که در حال لغو آن هستند ارسال می‌شوند، بنابراین یک توزیع‌کننده بار TCP ممکن است اتصال درخواست لغو را به فرآیندی متفاوت از آن فرآیندی که برای آن در نظر گرفته شده بود ارسال کند. با همتا کردن آن‌ها، این درخواست‌های لغو در نهایت به فرآیند مناسب هدایت می‌شوند. توضیحات دقیق‌تر در این ویدیوی ضبط‌شده از یک ارائه کنفرانس ارائه شده است.

این بخش شامل خطوطی به صورت key=value است مانند:

peer_id = connection string

که در آن کلید به عنوان یک peer_id و مقدار به عنوان یک رشته اتصال متشکل از جفت‌های key=value از پارامترهای اتصال در نظر گرفته می‌شود که در زیر شرح داده شده‌اند (مشابه libpq، اما از خود libpq استفاده نمی‌شود و مجموعه قابلیت‌های در دسترس متفاوت است). مثال:

1 = host=host1.example.com
2 = host=/tmp/pgbouncer-2  port=5555

نکته ۱: برای اینکه قابلیت همتایی کار کند، peer_id هر فرآیند PgBouncer در گروه باید درون گروه همتا یکتا باشد. و بخش [peers] باید شامل مدخل‌هایی برای هر یک از آن شناسه‌های همتا باشد. یک نمونه را می‌توان در بخش مثال‌های این اسناد یافت. مجاز است، اما الزامی نیست، که بخش [peers] شامل peer_id مربوط به همان فرآیند PgBouncer باشد که پیکربندی برای آن نوشته شده است. چنین مدخلی نادیده گرفته خواهد شد، اما برای آسان‌تر شدن مدیریت پیکربندی مجاز دانسته شده است؛ زیرا امکان استفاده از یک بخش [peers] دقیقاً یکسان را برای چندین پیکربندی فراهم می‌کند.

نکته ۲: همتایی میان‌نسخه‌ای تا زمانی که تمام همتاها در یک سمت مرز نسخه v1.21.0 باشند پشتیبانی می‌شود. در نسخه v1.21.0 تغییرات ساختاری بنیادینی در نحوه کدگذاری توکن‌های لغو ایجاد شد که آن‌ها را با توکن‌های ایجادشده توسط نسخه‌های قبلی ناسازگار کرد.

نام میزبان یا نشانی IP برای اتصال به آن. نام‌های میزبان در زمان اتصال تفکیک می‌شوند و نتیجه طبق پارامتر dns_max_ttl در حافظه نهان ذخیره می‌شود. اگر DNS چندین نتیجه بازگرداند، آن‌ها به روش نوبت‌گردشی استفاده می‌شوند. اما به طور کلی توصیه نمی‌شود از نام میزبانی استفاده کنید که به چندین IP تفکیک می‌شود، زیرا در این صورت درخواست لغو ممکن است همچنان به گره نادرستی ارسال شود و نیاز به ارسال مجدد داشته باشد (که تنها تا سه بار مجاز است).

اگر مقدار با / شروع شود، یک سوکت یونیکس در فضای نام فایل‌سیستم استفاده می‌شود. اگر مقدار با @ شروع شود، یک سوکت یونیکس در فضای نام انتزاعی استفاده می‌شود.

مثال‌ها:

host=localhost
host=127.0.0.1
host=2001:0db8:85a3:0000:0000:8a2e:0370:7334
host=/var/run/pgbouncer-1

پیش‌فرض: 6432

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

در صورت عدم تنظیم، از default_pool_size استفاده می‌شود.

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

%include filename

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

این بخش قالب فایلی را که توسط تنظیم auth_file مشخص می‌شود، توضیح می‌دهد. این فایل یک فایل متنی در قالب زیر است:

"username1" "password" ...
"username2" "md5abcdef012342345" ...
"username2" "SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>"

باید حداقل ۲ فیلد وجود داشته باشد که با نقل‌قول دوتایی محصور شده‌اند. فیلد اول نام کاربری است و فیلد دوم گذرواژه متنی ساده، یک گذرواژه درهم‌سازی‌شده با MD5 یا یک مقدار محرمانه SCRAM است. PgBouncer بقیه خط را نادیده می‌گیرد. علامت‌های نقل‌قول دوتایی درون مقدار یک فیلد را می‌توان با نوشتن دو نقل‌قول دوتایی اسکیپ کرد.

قالب گذرواژه درهم‌سازی‌شده با MD5 در PostgreSQL:

"md5" + md5(password + username)

بنابراین کاربر admin با گذرواژه 1234 دارای گذرواژه هش‌شده با MD5 به صورت md545f2603610af569b6155c45067268c6b خواهد بود.

قالب مقدار محرمانه SCRAM در PostgreSQL:

SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>

برای جزئیات بیشتر در این مورد، اسناد PostgreSQL و RFC 5803 را ببینید.

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

اگر گذرواژه به صورت متن ساده ذخیره شده باشد، می‌تواند برای هر نوع احراز هویت مبتنی بر گذرواژه مورد استفاده در سرور پشتیبان استفاده شود؛ متن ساده، MD5 یا SCRAM (برای جزئیات به https://www.postgresql.org/docs/current/auth-password.html مراجعه کنید).

گذرواژه‌های درهم‌سازی‌شده با MD5 در صورتی قابل استفاده هستند که سرور پشتیبان از احراز هویت MD5 استفاده کند (یا کاربران خاصی دارای گذرواژه‌های هش‌شده با MD5 باشند).

مقادیر محرمانه SCRAM تنها در صورتی می‌توانند برای ورود به سرور استفاده شوند که احراز هویت کلاینت نیز از SCRAM استفاده کند، تعریف پایگاه‌داده PgBouncer نام کاربری را مشخص نکرده باشد، و مقادیر محرمانه SCRAM در PgBouncer و سرور PostgreSQL یکسان باشند (نمک (salt) و تعداد تکرارهای یکسان، نه صرفاً گذرواژه یکسان). این امر ناشی از یک ویژگی امنیتی ذاتی SCRAM است: مقدار محرمانه ذخیره‌شده SCRAM به خودی خود نمی‌تواند برای استخراج اعتبارنامه‌های ورود استفاده شود.

فایل احراز هویت می‌تواند به صورت دستی نوشته شود، اما ایجاد آن از فهرست دیگری از کاربران و گذرواژه‌ها نیز مفید است. برای یک اسکریپت نمونه جهت تولید فایل احراز هویت از جدول سیستمی pg_authid، فایل ./etc/mkauth.py را ببینید. همچنین می‌توانید از auth_query به جای auth_file استفاده کنید تا از نگهداری یک فایل احراز هویت جداگانه بی‌نیاز شوید.

اگر سرور پشتیبان برای استفاده از احراز هویت گذرواژه SCRAM پیکربندی شده باشد، PgBouncer در صورتی که الف) گذرواژه کاربر به صورت متن ساده یا ب) مقدار محرمانه متناظر SCRAM را نداند، نمی‌تواند با موفقیت احراز هویت کند.

برخی ارائه‌دهندگان ابری (مانند AWS RDS) دسترسی به جدول‌های سیستمی حساس PostgreSQL را برای واکشی گذرواژه‌ها مسدود می‌کنند. حتی برای کاربری با بالاترین سطح دسترسی (مانند عضوی از rds_superuser)، اجرای دستور select * from pg_authid; خطای ERROR: permission denied for table pg_authid. را برمی‌گرداند. این یک رفتار شناخته‌شده است (به پست وبلاگ مراجعه کنید).

بنابراین، واکشی یک مقدار محرمانه موجود SCRAM پس از ذخیره شدن آن در یک سرور مدیریت‌شده غیرممکن است، که پیکربندی PgBouncer را برای استفاده از همان مقدار محرمانه SCRAM دشوار می‌کند. با این وجود، مقدار محرمانه SCRAM همچنان می‌تواند با استفاده از ترفند زیر پیکربندی شده و در هر دو سمت استفاده شود:

یک مقدار محرمانه SCRAM برای یک گذرواژه دلخواه با ابزاری تولید کنید که قابلیت چاپ این مقدار محرمانه را داشته باشد. برای مثال psql --echo-hidden و دستور \password پیش از ارسال مقدار محرمانه SCRAM به سرور، آن را روی کنسول چاپ می‌کند:

$ psql --echo-hidden <connection_string>
postgres=# \password <role_name>
Enter new password for user "<role_name>":
Enter it again:
********* QUERY **********
ALTER USER <role_name> PASSWORD 'SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>'
**************************

مقدار محرمانه SCRAM را از بخش QUERY یادداشت کنید و آن را در فایل userlist.txt در PgBouncer قرار دهید.

اگر از ابزاری غیر از psql --echo-hidden استفاده کرده‌اید، باید مقدار محرمانه SCRAM را در سرور نیز تنظیم کنید (می‌توانید از alter role <role_name> password '<scram_secret>' برای این کار استفاده کنید).

محل فایل HBA توسط تنظیم auth_hba_file مشخص می‌شود. تنها در صورتی استفاده می‌شود که auth_type روی hba تنظیم شده باشد.

این فایل از قالب فایل pg_hba.conf در PostgreSQL پیروی می‌کند (به https://www.postgresql.org/docs/current/auth-pg-hba-conf.html مراجعه کنید).

•
انواع رکوردهای پشتیبانی‌شده: local، host، hostssl، hostnossl.
•
فیلد پایگاه‌داده: از all، replication، sameuser، @file و چندین نام پشتیبانی می‌کند. موارد پشتیبانی‌نشده: samerole، samegroup.
•
فیلد نام کاربری: از all، @file و چندین نام پشتیبانی می‌کند. موارد پشتیبانی‌نشده: +groupname.
•
فیلد نشانی: از all، IPv4 و IPv6 پشتیبانی می‌کند. موارد پشتیبانی‌نشده: samehost، samenet، نام‌های DNS و پیشوندهای دامنه.
•
فیلد روش احراز هویت (Auth-method): تنها روش‌های پشتیبانی‌شده توسط auth_type در PgBouncer، به علاوه peer و reject پشتیبانی می‌شوند؛ به استثنای any و pam که فقط به صورت سراسری کار می‌کنند.
•
پارامتر نگاشت نام کاربری (map=) زمانی که auth_type برابر با cert یا peer باشد پشتیبانی می‌شود.

محل فایل نگاشت ident توسط تنظیم auth_ident_file مشخص می‌شود. تنها در صورتی بارگیری می‌شود که auth_type روی hba تنظیم شده باشد.

قالب این فایل گونه ساده‌شده‌ای از فایل نگاشت ident در PostgreSQL است (به https://www.postgresql.org/docs/current/auth-username-maps.html مراجعه کنید).

•
خطوط پشتیبانی‌شده تنها به شکل زیر هستند: map-name system-username database-username.
•
هیچ پشتیبانی برای گنجاندن فایل/دایرکتوری وجود ندارد.
•
فیلد نام کاربری سیستم (System-username): عبارات منظم (regular expressions) پشتیبانی نمی‌شوند.
•
فیلد نام کاربری پایگاه‌داده (Database-username): از all یا یک نام کاربری منفرد Postgres پشتیبانی می‌کند. موارد پشتیبانی‌نشده: +groupname و عبارات منظم.

نمونه پیکربندی کوچک:

[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

مثال‌های پایگاه‌داده:

[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

نمونه تابع امن برای auth_query:

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 'pg_temp'.
   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;

نمونه پیکربندی برای ۲ فرآیند همتای PgBouncer برای ایجاد یک ساختار چندهسته‌ای PgBouncer با استفاده از so_reuseport. پیکربندی برای فرآیند اول:

[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

پیکربندی برای فرآیند دوم:

[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

pgbouncer(1) - صفحه راهنما برای استفاده عمومی و دستورات کنسول

https://www.pgbouncer.org

1.25.2