Install & Compatibility
Where this runs
tested against v3.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.7s · import 0.000s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ConnectionPool
✓ from psycopg_pool import ConnectionPool
✗ from psycopg_pool import ConnectionPool
AsyncConnectionPool
✓ from psycopg_pool import AsyncConnectionPool
NullConnectionPool
✓ from psycopg_pool import NullConnectionPool
This quickstart demonstrates how to initialize a `ConnectionPool` using a connection string, obtain a connection using a context manager, execute a simple query, and ensure proper connection handling (returning to pool, transaction management). It also highlights how the pool manages connections for multiple requests.
import os
from psycopg_pool import ConnectionPool
# Get connection string from environment variable for security
DB_URL = os.environ.get('DATABASE_URL', 'postgresql://user:password@host:port/dbname')
# Create a connection pool as a context manager
# The pool is opened and closed automatically
with ConnectionPool(DB_URL, min_size=1, max_size=5) as pool:
print("Connection pool created.")
# Get a connection from the pool as a context manager
with pool.connection() as conn:
# The connection context handles transaction commit/rollback
# and returns the connection to the pool.
with conn.cursor() as cur:
cur.execute("SELECT 1 + 1")
result = cur.fetchone()
print(f"Result: {result[0]}")
# Example of getting multiple connections (will block if pool exhausted)
print("Attempting to get another connection...")
with pool.connection() as conn2:
with conn2.cursor() as cur2:
cur2.execute("SELECT 'Hello from conn2'")
result2 = cur2.fetchone()
print(f"Result from conn2: {result2[0]}")
print("Pool is closed after exiting the 'with' block.")
Debug
Known issues
breakingThe default value for the `open` parameter in `ConnectionPool` is currently `True`, but this will likely change to `False` in future releases. For `AsyncConnectionPool`, opening in the constructor will become an error. Explicitly set `open=True` if you rely on the pool opening immediately, or manage it with `pool.open()` and `pool.close()` or as a context manager.fixFor `ConnectionPool`, explicitly pass `open=True` to the constructor, or wrap pool creation in a `with` statement. For `AsyncConnectionPool`, always use `async with AsyncConnectionPool(...) as pool:` or call `await pool.open()`.
affects: All versions, explicitly warned since 3.2.0 for sync pools and 3.2.0 for async pools.
gotchaUnlike `psycopg2`, using `with connection:` in `psycopg-pool` (via `with pool.connection() as conn:`) manages the entire connection's lifecycle within the `with` block, including returning it to the pool and implicitly handling transaction commit/rollback. In `psycopg2`, `with connection:` only managed the transaction.fixBe aware of the different behavior when migrating from `psycopg2`. For transaction-only blocks in `psycopg-pool`, use `with conn.transaction():`.
affects: All versions of `psycopg-pool` (Psycopg 3).
gotchaFor integration with SQLAlchemy, `psycopg-pool` versions prior to 3.3.0 might behave unexpectedly if `conn.close()` is called, as it would actually close the connection instead of returning it to the pool. SQLAlchemy expects `close()` to return the connection to the pool.fixUpgrade to `psycopg-pool` 3.3.0 or later and set `close_returns=True` in the `ConnectionPool` constructor when integrating with SQLAlchemy.
affects: <3.3.0
gotchaThe `psycopg-pool` library has its own versioning and release cycle, which is separate from the main `psycopg` package. This is important for managing dependencies and understanding compatibility.fixWhen specifying dependencies, refer to the specific `psycopg-pool` version rather than assuming it aligns with the `psycopg` version.
affects: All versions.
gotchaSetting both `min_size` and `max_size` to 0 in `ConnectionPool` previously resulted in a hang. Since version 3.0.3, this now correctly raises a `ValueError`.fixEnsure `min_size` is at least 1, or that `max_size` is greater than or equal to `min_size` (unless you explicitly intend a null pool with specific `max_size` throttling).
affects: <3.0.3
breaking`psycopg-pool` depends on `psycopg`, which requires the PostgreSQL client library (`libpq`) to be installed in the environment. If `libpq` or its development headers are missing, `psycopg` will fail to import with an `ImportError: no pq wrapper available`, making `psycopg-pool` unusable.fixEnsure that the PostgreSQL client library (`libpq`) and its development headers are installed in the environment before installing `psycopg-pool` or `psycopg`. For Debian/Ubuntu-based systems, this typically means running `apt-get install libpq-dev`. For other systems, consult the `psycopg` documentation for relevant installation instructions.
affects: All versions of `psycopg-pool` (as it's a fundamental dependency issue with `psycopg`).
breaking`psycopg`, a dependency of `psycopg-pool`, requires the PostgreSQL client library (`libpq`) to be installed in the environment. In minimal environments (e.g., Alpine Linux), this library might be missing, leading to an `ImportError: no pq wrapper available.` when importing `psycopg`.fixEnsure the PostgreSQL client library is installed in your environment. For Alpine Linux, install `postgresql-client` or `libpq` if available. For Debian/Ubuntu, install `libpq-dev`. Alternatively, use `psycopg[binary]` to install a pre-compiled wheel that bundles libpq.
affects: All versions.
Upgrade
Version history
3.3.1latest on PyPI · released May 1, 2026
Audit
Dependencies
psycopgrequiredCore PostgreSQL adapter for Python.