WIUNIX ACADEMY
PgBouncer در حالت تراکنشی؛ بررسی سازگاری برنامه و صف اتصال
پیش از تغییر حالت اتصال‌ها، وابستگی برنامه به نشست دیتابیس را پیدا کنید، دستورهای آماده را با درایور واقعی بسنجید و انتظار در PgBouncer را از کندی خود PostgreSQL جدا کنید.
محیطت را انتخاب کنآموزش متناسب با محیط تو
کجا اجرا می‌کنی؟
سیستم‌عامل و نسخه را انتخاب کن تا مراحل، دستورها و راه‌حل‌ها برای همان محیط نمایش داده شوند.
آموزش متناسب با مقادیر تو
تنظیمات این آموزش
مقادیر نمونه را برای محیط خودت تنظیم کن؛ متن و دستورهای مرتبط با هم تغییر می‌کنند. رمز، کلید خصوصی و توکن وارد نکن. مقادیر فقط در همین زبانه نگهداری می‌شوند و به سرور یا لینک اشتراک‌گذاری فرستاده نمی‌شوند. پیش از اجرا، DNS، گواهی‌ها و سیاست شبکهٔ واقعی را بررسی کن.
آی‌پی، دامنه یا پورت مثال‌ها با محیط تو فرق دارد؟ دکمهٔ زیر را باز کن، مقادیر را تغییر بده و «اعمال در آموزش» را بزن؛ سپس دستورهای به‌روز‌شده را کپی کن.
تنظیم مقادیر برای محیط من5 مقدار قابل‌تغییر
از اینجا شروع کن
در پایان چه چیزی خواهی داشت؟
روی مسیر آزمایشی نشان دهید برنامه پس از جابه‌جایی اتصالِ سمت سرور همچنان درست کار می‌کند و تعداد اتصال‌ها به ظرفیت دیتابیس می‌خورد.
سیستم‌عامل‌ها و نسخه‌های پوشش‌داده‌شده
مسیرهای مستند برای Ubuntu، Debian و خانوادهٔ Red Hat؛ محصول و کلاینت سازگار باید از قبل نصب باشند. محدودیت هر شاخه در گام نخست آمده است. فرمان‌ها هنگام نگارش روی سرویس واقعی اجرا نشده‌اند.
قبل از شروع
- PgBouncer به‌روز و مختص آزمایش، متصل به PostgreSQL 18؛ تنظیمات فعلی اتصال، TLS و حساب سرویس باید مشخص و محفوظ باشند.
- دو اتصال محافظت‌شدهٔ libpq برای مدیر PgBouncer و برنامهٔ آزمایشی، به‌علاوهٔ کلاینت آماده با نسخه‌های سازگار Psycopg و libpq.
- مجوز ویرایش تنظیمات همان نمونه و فرصت اجرای بار کاری شبیه شرایط عادی برنامهٔ برنامه؛ این مقاله نصب، ساخت حساب یا بازکردن پورت انجام نمی‌دهد.
اتصال برنامه همیشه به یک پردازش PostgreSQL نمی‌رسد
در حالت transaction pooling، PgBouncer اتصال سمت سرور را در پایان تراکنش آزاد می‌کند تا کلاینت دیگری از آن استفاده کند. بنابراین برنامه ممکن است connection خود را باز نگه دارد، اما تراکنش بعدی روی پردازش دیگری در PostgreSQL اجرا شود. اگر برنامه چیزی را برای کل نشست تنظیم کرده باشد، همین جابه‌جایی می‌تواند نتیجه را عوض کند.
در این راهنما ابتدا این وابستگی‌ها را شناسایی می‌کنیم، بعد یک مسیر موجودِ آزمایشی را تغییر می‌دهیم و با درایور واقعی صحت آن را می‌سنجیم. در پایان نیز صف انتظار PgBouncer را از زمانی که دیتابیس صرف اجرای کوئری می‌کند جدا می‌خوانیم.
کار را روی نمونهٔ آزمایشی موجود انجام دهید
listener، TLS، حساب‌ها و اتصال PgBouncer به دیتابیس باید از قبل درست کار کنند. نسخهٔ دقیق هر سه جزء، یعنی PgBouncer، PostgreSQL و درایور برنامه را ثبت کنید. وجود پشتیبانی عمومی از دستور آماده در نسخهٔ۱٫۲۱ به معنی مناسب‌بودن آن نسخه برای مسیر Psycopg این مقاله نیست؛ پیش‌نیاز دقیق مثال در بخش آزمون آمده است.
تنظیمات محافظت‌شده و مسیرهای اتصال فعلی را حفظ کنید. این آموزش جای راه‌اندازی اولیه یا بازبینی امنیت listener نیست و نباید نمونهٔ در حال استفادهٔ کاربران را برای آزمون تغییر دهد.
نام اتصال‌های موجود را وارد کنید، نه رمز را
فرم، نام serviceهای libpq، مسیر تنظیمات و ظرفیت موردنظر برای نمونهٔ آزمایشی را می‌گیرد. تعریف service باید از قبل در فایل محافظت‌شده، همراه با TLS و احراز هویت درست، آماده باشد. رشتهٔ اتصال حاوی گذرواژه را در فرم یا خط فرمان نگذارید.
این مقدارها فقط در همین تب نگهداری می‌شوند. با «اعمال»، متن و پنل‌های کپی با هم تغییر می‌کنند؛ در حالت نامعتبر یا اعمال‌نشده کپی غیرفعال می‌ماند. عدد ظرفیت یک فرض برای بررسی است؛ نباید آن را به همهٔ سرویس‌ها تعمیم دهید.
قدم بعدی
پیش از شروع، مسیر ابزار و محل اجرای فرمان‌ها را بررسی کنید
این تمرین روی PgBouncer موجود انجام می‌شود و راهنمای نصب آن نیست. در Ubuntu نسخه‌های ۲۶٫۱۰ و ۲۶٫۰۴ و Debian نسخه‌های ۱۳ و ۱۲، کلاینت PostgreSQL را از نصب موجود PGDG انتخاب کنید. در RHEL، Rocky Linux و AlmaLinux شاخه‌های ۹ و ۱۰، مسیر کلاینت PGDG نسخهٔ ۱۸ برابر /usr/pgsql-18/bin است. مسیر /etc/pgbouncer/pgbouncer.ini فقط نمونه است؛ پیش از پشتیبان‌گیری یا ویرایش، آن را با ExecStart سرویس و فایل‌های تنظیمات فرعی تطبیق دهید. تغییر فایل بر عهدهٔ مسئول مجاز همان سرویس است؛ آزمایش درایور و پایش از کلاینت مجاز انجام می‌شود. صرف نام بستهٔ توزیع کافی نیست: آزمایش این صفحه به PgBouncer نسخهٔ ۱٫۲۲ یا بالاتر، Psycopg نسخهٔ ۳٫۲ یا بالاتر و libpq نسخهٔ ۱۷ یا بالاتر در همان محیط Python نیاز دارد. بستهٔ psycopg2 جای Psycopg 3 را نمی‌گیرد.
این مسیرها از مستندات استخراج شده‌اند و آزمون عملی سازگاری محسوب نمی‌شوند. ابتدا /etc/os-release و نسخهٔ دقیق محصول را بررسی کنید. حساب‌ها، دسترسی شبکه و اعتبارنامه‌های محافظت‌شده باید از قبل آماده باشند. برای آماده‌کردن ابزارها، سرویس موجود را دوباره راه‌اندازی نکنید، دیتابیس تازه مقداردهی اولیه نکنید، پورتی روی فایروال باز نکنید و Python سیستم را تغییر ندهید.
محیط Python برنامه باید از قبل وابستگی سازگار را داشته باشد. RHEL 9 به‌طور پیش‌فرض Python 3.9 و RHEL 10 نسخهٔ 3.12 دارد؛ نسخهٔ چاپ‌شده و نسخهٔ کتابخانه را بررسی کنید. این صفحه بسته‌ای با pip در Python سیستم نصب نمی‌کند.
نسخهٔ سرویس PgBouncer را در گام inventory با SHOW VERSION از راه دور می‌خوانیم؛ نصب باینری daemon روی کلاینت لازم نیست.
کلاینت مدیریت مجاز؛ بررسی‌های مخصوص گره فقط روی همان گرهٔ موجود
cat /etc/os-release
id
test -x /usr/lib/postgresql/18/bin/psql
/usr/lib/postgresql/18/bin/psql --version
python3 --versionسیستم‌عامل، مسیر و نسخهٔ ابزار با محیط انتخابی سازگار است؛ در صورت تفاوت، پیش از تغییر داده توقف کنید.
قدم بعدی
تنظیم فعال و نسخهٔ درایور را ثبت کنید
از ایستگاه مدیریت آزمایش اجرا کنید. تنظیمی که SHOW CONFIG نشان می‌دهد با فایلی که قصد ویرایشش را دارید یکی فرض نکنید؛ مقدارهای اختصاصیِ database یا user ممکن است تنظیم سراسری را تغییر دهند. حالت pool، ظرفیت آماده‌سازی و تعداد اتصال‌های سمت سرور را برای همان مسیر بررسی کنید.
در برنامه هم نسخهٔ درایور و libpq، روش آماده‌سازی دستور، پارامترهای آغاز اتصال و زمان بستن و بازکردن connection را یادداشت کنید. خروجی مدیریتی را خصوصی نگه دارید.
رایانهٔ مدیریت محیط آزمایشی
/usr/lib/postgresql/18/bin/psql -X -v ON_ERROR_STOP=1 'service=academy_pool_admin' -c 'SHOW VERSION;' -c 'SHOW CONFIG;' -c 'SHOW DATABASES;' -c 'SHOW POOLS;' -c 'SHOW STATS;'مسیر اتصال منتخب و مقدارهای مؤثر آن، همراه با نسخهٔ واقعی کلاینت، ثبت شده‌اند.
آماده‌سازی در پروتکل با PREPARE در SQL فرق دارد
مقدار غیرصفر max_prepared_statements به PgBouncer اجازه می‌دهد دستورهای نام‌دارِ آماده‌شده در پروتکل را رهگیری کند. این قابلیت، دستور SQL یعنی PREPARE و اجرای بعدی آن را با جابه‌جایی نشست سازگار نمی‌کند. LISTEN، قفل advisory در سطح نشست، جدول موقت ماندگار و SET مورد انتظار بین دو تراکنش نیز همچنان به بازطراحی یا مسیر session pooling نیاز دارند.
اگر تنظیمی فقط برای همان تراکنش لازم است، SET LOCAL را در همان تراکنش در نظر بگیرید. سازگاری PDO هم به ترکیب واقعی نسخه‌ها وابسته است؛ FAQ فعلی ترکیب PHP 8.4 یا جدیدتر با libpq 17 را مطرح می‌کند. نام PHP به‌تنهایی برای نتیجه‌گیری کافی نیست.