{"canonical_url":"https://engineer.company/glossary/connection-pool/","content_markdown":"# Connection pool\n\n## What it is\n\nA connection pool is a set of open database connections that an application\nkeeps and lends out again, instead of opening a new connection for every piece\nof work and closing it afterwards. Code checks a connection out of the pool,\nruns its statements on it and hands it back, and the next caller that needs one\ngets the same connection, already open. SQLAlchemy's documentation describes\npooling as \"a standard technique used to maintain long running connections in\nmemory for efficient reuse\". The same page gives the pool a second job: it\nmanages how many connections the application may use at the same time, so a\nburst of traffic waits for a free connection instead of opening more.\n\nA pool can live in two places. Inside the application it is part of the database\nlibrary: every SQLAlchemy `Engine` comes with one, and Django can keep one in\neach process for PostgreSQL. Outside the application it is a separate program\nthat sits between the clients and the database server. PgBouncer is such a\npooler for PostgreSQL: applications connect to it as if it were the database,\nand it lends them server connections from pools of its own. The two can be\ncombined, and Django's database reference has a section on running behind a\ntransaction pooler such as PgBouncer.\n\nWhy a connection is worth keeping shows on the server side. PostgreSQL gives\neach client a process of its own: a supervisor process called the postmaster\nlistens for incoming connections, starts a new server process for every\nconnection request, and each client is connected to exactly one of those\nprocesses. Opening a connection therefore means starting a process on the\ndatabase server, and a pool pays that price once and then reuses the result.\n\n## Why it matters\n\nThe first reason is the cost of connecting. Django's documentation makes the\ncase for keeping connections in plain terms: a persistent connection avoids the\noverhead of establishing a new one in each HTTP request. Its default does the\nopposite, though. `CONN_MAX_AGE` is 0, which closes the connection at the end of\nevery request; a positive number of seconds keeps it open for reuse, and `None`\nkeeps it open without a limit. That is the simplest form of reuse, one\nconnection per thread that outlives the request, and a pool is the general form\nof it.\n\nThe second reason is the limit on the server. PostgreSQL's `max_connections` is\ntypically 100 by default, may be lower if the kernel settings will not support\nit, and can only be changed at server start. Three of those slots are reserved\nfor superusers by default. Raising the number is not free either: PostgreSQL\nsizes certain resources, shared memory among them, directly from\n`max_connections`. Without a pool, every worker holds a connection of its own,\nand Django's documentation spells out what follows: because each thread keeps\nits own connection, the database has to accept at least as many simultaneous\nconnections as there are worker threads. A pool turns that into a number the\nteam chooses and can add up.\n\nThe third reason is hygiene. A pool is the one place every connection passes\nthrough between two borrowers, so it is where a connection gets cleaned and\ntested. When a connection comes back, SQLAlchemy's pool calls `rollback()` on\nit, which releases any transactional state, locks included, so the next borrower\ndoes not inherit a half-finished transaction. In PgBouncer’s default session-pooling mode, its `server_reset_query`, `DISCARD ALL` by default, runs when a server connection is released and before another client receives it. And a pool can test a\nconnection before lending it out, which matters for connections that have sat\nidle for a while.\n\n## What it looks like in practice\n\nIn SQLAlchemy 2.1 every `Engine` gets a `QueuePool` by default, with SQLite's\nin-memory database as the exception. Its `pool_size` is 5 and its `max_overflow`\nis 10, so one engine can hold up to 15 connections at once, and a caller that\nfinds them all in use waits `pool_timeout`, 30 seconds by default, before giving\nup. The settings are keyword arguments to `create_engine()`:\n\n```python\nfrom sqlalchemy import create_engine\n\n# At most ten connections for this engine: ten kept open, none beyond.\nengine = create_engine(\n    \"postgresql+psycopg2://me@localhost/mydb\",\n    pool_size=10,\n    max_overflow=0,\n    pool_timeout=10,  # wait ten seconds for a free connection, then give up\n    pool_pre_ping=True,  # test each connection as it is checked out\n    pool_recycle=3600,  # replace connections that are over an hour old\n)\n```\n\nWith `pool_pre_ping`, the pool checks at checkout that the connection is still\nusable, through the driver's own ping or a statement equivalent to `SELECT 1`.\n`pool_recycle` is meant for servers that close connections left unused for a\ncertain time: with 3600, any connection open for more than an hour is replaced\nat its next checkout.\n\nDjango 6.1 has a pool of its own for PostgreSQL. It works only with the psycopg\ndriver and needs the `psycopg[pool]` package, and it is switched on with\n`\"OPTIONS\": {\"pool\": True}` in the database settings, or with a dictionary of\noptions for psycopg's `ConnectionPool`. The pool reuses connections across\nthreads, and each process keeps a separate pool for each database alias.\n`CONN_MAX_AGE` must stay at 0 when pooling is on; the lifetime of a pooled\nconnection is set with the pool's `max_lifetime` option instead. Under ASGI,\nDjango's documentation advises turning persistent connections off and using this\nbuilt-in pool instead.\n\nPgBouncer's `pool_mode` decides when a server connection can go to another\nclient. In session mode, the default, the client keeps it until it disconnects.\nIn transaction mode, a client has a server connection only while a transaction\nruns, so a few dozen server connections can serve many more clients. Statement\nmode releases the connection after every query and does not allow transactions\nthat span several statements. Each pool holds up to `default_pool_size` server\nconnections per user and database pair, 20 by default, and PgBouncer accepts up\nto `max_client_conn` client connections, 100 by default.\n\nThe company's own notes put the pool early in the order of work.\n[Optimise the database before you shard it](/notes/optimise-before-you-shard/)\nhas the reader count the active sessions in `pg_stat_activity` against the CPU\ncores: when many times more are active than there are cores, the server spends\nits time switching between them, and a connection pool fixes that before any\nhardware does.\n[Selling the last ticket exactly once](/notes/selling-limited-stock-without-overselling/)\napplies the same idea to a flash sale: a hundred thousand buyers should become a\nfew dozen connections through PgBouncer, not thousands of server processes\nwaiting for one lock.\n\n## Where it goes wrong\n\n**The pools add up to more than the server allows.** Each pool counts only its\nown connections. At SQLAlchemy's defaults one engine can reach 15, so twelve\nprocesses can ask for 180 from a server whose default `max_connections` is\ntypically 100, three of them reserved for superusers, and Django keeps a\nseparate pool for every database alias in every process. Add up the maximum of\nevery pool that points at the database, across every process of every\napplication and every scheduled job, and keep the sum below `max_connections`\nminus the reserved slots. When it cannot fit, put PgBouncer in front and let it\nhold the number of server connections.\n\n**A connection dies while it waits in the pool.** A connection that sat idle can\nbe closed on the other side without the pool knowing, and the next borrower then\nfails on its first statement. Turn on `pool_pre_ping` in SQLAlchemy or\n`CONN_HEALTH_CHECKS` in Django, which tests a reused connection once per\nrequest, and set `pool_recycle` or psycopg's `max_lifetime` below the time after\nwhich the server closes idle connections. Neither covers a connection dropped in\nthe middle of a transaction: SQLAlchemy's documentation says plainly that\npre-ping does not handle that case, so the application has to retry the work\nitself.\n\n**A forked worker inherits the parent's connections.** A web server or a job\nrunner that creates the engine and then forks its workers leaves every child\nholding the same pooled connections as the parent. The SQLAlchemy documentation\ncalls it critical that pooled connections are not shared with a forked process,\nbecause both processes would then talk over the same network connection. Follow\nits recommended approach and call `engine.dispose(close=False)` in each child's\ninitializer, so the child starts with an empty pool and leaves the parent's\nconnections alone; the alternatives are `NullPool`, which opens and closes a\nconnection for every use, or calling `engine.dispose()` before forking.\n\n**Transaction pooling breaks session state.** In PgBouncer's transaction mode,\ntwo transactions from the same client can run on different server connections,\nso anything a client sets up for its session is not guaranteed to be there for\nits next transaction. PgBouncer's feature list marks `SET`, `LISTEN`, cursors\ndeclared `WITH HOLD`, SQL-level `PREPARE` and session-level advisory locks as\nnever supported in that mode, and is open that the mode, by its nature, breaks\nsome of the assumptions clients make about the server. Keep session state out of\ncode that goes through a transaction pooler, and send the clients that need it\nto a pool in session mode. In Django, set `DISABLE_SERVER_SIDE_CURSORS` to\n`True` for a database behind a transaction pooler, or run those queries inside\n`atomic()`.\n\n## Further reading\n\n- [Connection Pooling](https://docs.sqlalchemy.org/en/21/core/pooling.html)\n  — `QueuePool` and its defaults, disconnect handling, reset on return and pools\n  under fork in SQLAlchemy 2.1.\n- [PgBouncer features](https://www.pgbouncer.org/features.html)\n  — the session, transaction and statement modes, and which PostgreSQL features\n  each one supports.\n- [PgBouncer configuration](https://www.pgbouncer.org/config.html)\n  — `pool_mode`, `default_pool_size`, `max_client_conn` and the timeouts, with\n  their defaults.\n- [How Connections Are Established](https://www.postgresql.org/docs/current/connect-estab.html)\n  — PostgreSQL's process per user model and the postmaster.\n- [Connections and Authentication](https://www.postgresql.org/docs/current/runtime-config-connection.html)\n  — `max_connections` and the connection slots reserved for superusers and other\n  roles.\n- [Databases](https://docs.djangoproject.com/en/stable/ref/databases/)\n  — persistent connections, the PostgreSQL connection pool and transaction\n  pooling, in Django's reference.\n\n\u003chttps://engineer.company/glossary/connection-pool/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Why a database connection is worth keeping, how a pool reuses and caps connections, what PgBouncer's modes change, and four ways pools go wrong.","formats":{"gemtext":"https://engineer.company/glossary/connection-pool/index.gmi","gopher":"https://engineer.company/glossary/connection-pool/gophermap","html":"https://engineer.company/glossary/connection-pool/","json":"https://engineer.company/glossary/connection-pool/index.json","markdown":"https://engineer.company/glossary/connection-pool/index.md","pdf":"https://engineer.company/glossary/connection-pool/index.pdf"},"kind":"page","language":"en","title":"What is a connection pool?","url":"https://engineer.company/glossary/connection-pool/","version":1}