{"canonical_url":"https://engineer.company/uk/glossary/connection-pool/","content_markdown":"# Пул з'єднань\n\n## Що це таке\n\nПул з'єднань — це набір відкритих з'єднань із базою даних, які застосунок тримає\nй позичає знову, замість того щоб відкривати нове з'єднання для кожної дії та\nзакривати його після неї. Його ще називають пулом підключень. Код бере з'єднання\nз пулу, виконує на ньому свої інструкції та повертає його, і наступний, кому\nвоно потрібне, отримує те саме з'єднання, уже відкрите. Документація SQLAlchemy\nописує пулінг як стандартний прийом, що тримає довгоживучі з'єднання в пам'яті\nдля ефективного повторного використання. Та сама сторінка дає пулу ще одну роль:\nвін керує тим, скільки з'єднань застосунок може використовувати одночасно, тож\nраптовий сплеск трафіку чекає на вільне з'єднання, а не відкриває нові.\n\nПул може жити у двох місцях. Усередині застосунку він є частиною бібліотеки для\nроботи з базою: кожен `Engine` у SQLAlchemy має власний пул, а Django може\nтримати по одному в кожному процесі для PostgreSQL. Поза застосунком це окрема\nпрограма, що стоїть між клієнтами й сервером бази даних. PgBouncer — саме такий\nпулер для PostgreSQL: застосунки під'єднуються до нього так, ніби це база даних,\nа він позичає їм серверні з'єднання з власних пулів. Ці два варіанти можна\nпоєднувати, і в довіднику Django про бази даних є розділ про роботу за\nтранзакційним пулером на кшталт PgBouncer.\n\nЧому з'єднання варто зберігати, видно на боці сервера. PostgreSQL дає кожному\nклієнтові окремий процес: головний процес, postmaster, слухає вхідні з'єднання й\nзапускає новий серверний процес на кожен запит на з'єднання, і кожен клієнт\nпід'єднаний рівно до одного з цих процесів. Отже, відкрити з'єднання означає\nзапустити процес на сервері бази даних, а пул платить цю ціну один раз і далі\nвикористовує результат повторно.\n\n## Чому це важливо\n\nПерша причина — ціна під'єднання. Документація Django каже про це прямо:\nпостійне з'єднання позбавляє від витрат на встановлення нового в кожному\nHTTP-запиті. Проте типове налаштування робить навпаки. `CONN_MAX_AGE` дорівнює\n0, і з'єднання закривається наприкінці кожного запиту; додатне число секунд\nтримає його відкритим для повторного використання, а `None` — без обмеження. Це\nнайпростіша форма повторного використання, одне з'єднання на потік, яке живе\nдовше за запит, а пул — її загальна форма.\n\nДруга причина — межа на сервері. Типове значення `max_connections` у PostgreSQL\nзазвичай становить 100, може бути меншим, якщо налаштування ядра цього не\nвитримують, і змінюється лише під час запуску сервера. Три місця з них типово\nзарезервовано для суперкористувачів. Підняти це число теж не безкоштовно:\nPostgreSQL визначає розмір деяких ресурсів, зокрема спільної пам'яті,\nбезпосередньо з `max_connections`. Без пулу кожен робочий процес тримає власне\nз'єднання, і документація Django пояснює наслідок: оскільки кожен потік має своє\nз'єднання, база даних мусить приймати щонайменше стільки одночасних з'єднань,\nскільки є робочих потоків. Пул дає команді змогу самій визначати кількість з'єднань\nі підсумовувати її для всіх пулів.\n\nТретя причина — гігієна. Пул — це єдине місце, через яке кожне з'єднання\nпроходить між двома позичальниками, тож саме тут його прибирають і перевіряють.\nКоли з'єднання повертається, пул SQLAlchemy викликає на ньому `rollback()`, і це\nзвільняє весь транзакційний стан разом із блокуваннями, тож наступний\nпозичальник не успадкує недороблену транзакцію. У типовому режимі PgBouncer із пулом сеансів його `server_reset_query`, типово\n`DISCARD ALL`, виконується після звільнення серверного з'єднання й перед тим,\nяк його отримає інший клієнт. А ще пул може перевірити з'єднання, перш ніж\nйого позичити, і це важливо для з'єднань, які довго простоювали.\n\n## Як це виглядає на практиці\n\nУ SQLAlchemy 2.1 кожен `Engine` типово отримує `QueuePool`, окрім бази даних\nSQLite у пам'яті. Його `pool_size` дорівнює 5, а `max_overflow` — 10, тож один\nengine може мати до 15 з'єднань одночасно, а виклик, який застає їх усі\nзайнятими, чекає `pool_timeout`, типово 30 секунд, і лише тоді здається. Ці\nпараметри передають як іменовані аргументи до `create_engine()`:\n\n```python\nfrom sqlalchemy import create_engine\n\n# Щонайбільше десять з'єднань на цей engine: усі відкриті, понад них жодного.\nengine = create_engine(\n    \"postgresql+psycopg2://me@localhost/mydb\",\n    pool_size=10,\n    max_overflow=0,\n    pool_timeout=10,  # чекати на вільне з'єднання десять секунд, далі здатися\n    pool_pre_ping=True,  # перевіряти кожне з'єднання під час видачі\n    pool_recycle=3600,  # замінювати з'єднання, старші за годину\n)\n```\n\nІз `pool_pre_ping` пул під час видачі перевіряє, що з'єднання ще придатне, через\nвласний ping драйвера або інструкцію, рівнозначну `SELECT 1`. `pool_recycle`\nпризначений для серверів, які закривають з'єднання, що певний час не\nвикористовувалися: зі значенням 3600 кожне з'єднання, відкрите понад годину,\nзамінюється під час наступної видачі.\n\nDjango 6.1 має власний пул для PostgreSQL. Він працює лише з драйвером psycopg,\nпотребує пакета `psycopg[pool]`, а вмикають його через `\"OPTIONS\": {\"pool\":\nTrue}` у налаштуваннях бази даних або словником параметрів для `ConnectionPool`\nіз psycopg. Пул повторно використовує з'єднання між потоками, і кожен процес має\nокремий пул для кожного псевдоніма бази даних. `CONN_MAX_AGE` має лишатися 0,\nколи пул увімкнено; час життя з'єднання в пулі натомість задає параметр пулу\n`max_lifetime`. Для ASGI документація Django радить вимкнути постійні з'єднання\nй користуватися цим вбудованим пулом.\n\nПараметр PgBouncer `pool_mode` визначає, коли серверне з'єднання може перейти до\nіншого клієнта. У режимі `session`, типовому, клієнт тримає з'єднання, доки не\nвід'єднається. У режимі `transaction` клієнт має серверне з'єднання лише поки\nтриває транзакція, тож кілька десятків серверних з'єднань можуть обслуговувати\nзначно більше клієнтів. Режим `statement` звільняє з'єднання після кожного\nзапиту й не дозволяє транзакцій із кількох інструкцій. Кожен пул вміщує до\n`default_pool_size` серверних з'єднань на пару користувача й бази даних, типово\n20, а PgBouncer приймає до `max_client_conn` клієнтських з'єднань, типово 100.\n\nВласні нотатки компанії ставлять пул на ранній крок.\n[Оптимізуйте базу, перш ніж її шардувати](/uk/notes/optimise-before-you-shard/)\nпропонує порахувати активні сесії в `pg_stat_activity` і порівняти з кількістю\nядер CPU: коли активних у багато разів більше, ніж ядер, сервер витрачає час на\nперемикання між ними, і пул з'єднань виправить це раніше, ніж будь-яке залізо.\n[Продати останній квиток рівно один раз](/uk/notes/selling-limited-stock-without-overselling/)\nзастосовує ту саму думку до флеш-розпродажу: сто тисяч покупців мають\nперетворитися на кілька десятків з'єднань через PgBouncer, а не на тисячі\nсерверних процесів, що чекають на одне блокування.\n\n## Де виникають проблеми\n\n**Пули разом просять більше з'єднань, ніж дозволяє сервер.** Кожен пул рахує\nлише власні з'єднання. За типових значень SQLAlchemy один engine може дійти до\n15, тож дванадцять процесів можуть попросити 180 у сервера, де `max_connections`\nзазвичай типово дорівнює 100, а три з них зарезервовано для суперкористувачів;\nдо того ж Django має окремий пул для кожного псевдоніма бази даних у кожному\nпроцесі. Складіть максимум кожного пулу, що дивиться на цю базу даних, по всіх\nпроцесах усіх застосунків і всіх запланованих завдань, і тримайте суму нижче за\n`max_connections` мінус зарезервовані місця. Якщо не вміщається, поставте\nпопереду PgBouncer і дайте йому тримати кількість серверних з'єднань.\n\n**З'єднання вмирає, поки чекає в пулі.** З'єднання, яке простоювало, можуть\nзакрити з іншого боку так, що пул про це не знає, і наступний позичальник тоді\nпадає на першій же інструкції. Увімкніть `pool_pre_ping` у SQLAlchemy або\n`CONN_HEALTH_CHECKS` у Django, яке перевіряє повторно використане з'єднання раз\nна запит, і задайте `pool_recycle` або `max_lifetime` у psycopg меншим за час,\nпісля якого сервер закриває невикористовувані з'єднання. Жоден із цих засобів не\nрятує з'єднання, що обривається посеред транзакції: документація SQLAlchemy\nпрямо каже, що pre-ping цього випадку не обробляє, тож застосунок мусить сам\nповторити роботу.\n\n**Робочий процес, створений через fork, успадковує з'єднання батьківського.**\nВебсервер або обробник завдань, що створює свій engine, а потім запускає робочі\nпроцеси через fork, залишає кожному дочірньому процесу ті самі з'єднання з пулу,\nщо й у батьківського. Документація SQLAlchemy називає критично важливим не\nділити з'єднання з пулу з процесом, створеним через fork, бо обидва процеси тоді\nговоритимуть через одне й те саме мережеве з'єднання. Дотримуйтеся\nрекомендованого підходу й викликайте `engine.dispose(close=False)` в\nініціалізаторі кожного дочірнього процесу, щоб він починав із порожнього пулу й\nне чіпав з'єднань батьківського. Альтернативи — `NullPool`, який відкриває й\nзакриває з'єднання для кожного використання, або виклик `engine.dispose()` перед\nfork.\n\n**Транзакційний пулінг ламає стан сесії.** У режимі `transaction` у PgBouncer\nдві транзакції одного клієнта можуть виконуватися на різних серверних\nз'єднаннях, тож усе, що клієнт налаштовує для своєї сесії, не обов'язково буде\nна місці в його наступній транзакції. Перелік можливостей PgBouncer позначає\n`SET`, `LISTEN`, курсори, оголошені з `WITH HOLD`, `PREPARE` на рівні SQL і\nрекомендаційні блокування на рівні сесії як ніколи не підтримувані в цьому\nрежимі й відверто визнає, що режим за своєю природою порушує деякі припущення\nклієнтів щодо сервера. Тримайте стан сесії поза кодом, що йде через\nтранзакційний пулер, а клієнтів, яким він потрібен, спрямовуйте до пулу в режимі\n`session`. У Django для бази даних за транзакційним пулером встановіть\n`DISABLE_SERVER_SIDE_CURSORS` у `True` або виконуйте ці запити всередині\n`atomic()`.\n\n## Що почитати далі\n\n- [Connection Pooling](https://docs.sqlalchemy.org/en/21/core/pooling.html)\n  — `QueuePool` і його типові значення, обробка розірваних з'єднань, скидання\n  під час повернення та пули після fork у SQLAlchemy 2.1.\n- [PgBouncer features](https://www.pgbouncer.org/features.html)\n  — режими session, transaction і statement та можливості PostgreSQL, які\n  підтримує кожен із них.\n- [PgBouncer configuration](https://www.pgbouncer.org/config.html)\n  — `pool_mode`, `default_pool_size`, `max_client_conn` і тайм-аути з їхніми\n  типовими значеннями.\n- [How Connections Are Established](https://www.postgresql.org/docs/current/connect-estab.html)\n  — модель PostgreSQL з окремим процесом на кожного користувача і процес\n  postmaster.\n- [Connections and Authentication](https://www.postgresql.org/docs/current/runtime-config-connection.html)\n  — `max_connections` і місця для з'єднань, зарезервовані для суперкористувачів\n  та інших ролей.\n- [Databases](https://docs.djangoproject.com/en/stable/ref/databases/)\n  — постійні з'єднання, пул для PostgreSQL і транзакційний пулінг у довіднику\n  Django.\n\n\u003chttps://engineer.company/uk/glossary/connection-pool/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Чому з'єднання з базою даних варто зберігати, як пул повторно використовує й обмежує з'єднання, що змінюють режими PgBouncer і чотири типові пастки.","formats":{"gemtext":"https://engineer.company/uk/glossary/connection-pool/index.gmi","gopher":"https://engineer.company/uk/glossary/connection-pool/gophermap","html":"https://engineer.company/uk/glossary/connection-pool/","json":"https://engineer.company/uk/glossary/connection-pool/index.json","markdown":"https://engineer.company/uk/glossary/connection-pool/index.md","pdf":"https://engineer.company/uk/glossary/connection-pool/index.pdf"},"kind":"page","language":"uk","title":"Що таке пул з'єднань?","url":"https://engineer.company/uk/glossary/connection-pool/","version":1}