Psycopg

Psycopg 3 is a complete rewrite of the classic psycopg2 PostgreSQL driver, built around asyncio-native connections and cursors, a C-optimized libpq binding, and strict static typing. It ships as a small family of packages (the pure-Python core, an optional Cython speedup module, and a separate connection-pool package) so applications can pull in exactly the runtime they need.

It is the driver of choice for modern async Python web stacks (FastAPI, Django async views, aiohttp) that need first-class PostgreSQL support without falling back to thread pools, while still supporting fully synchronous usage for traditional codebases.

What You Get

• Synchronous and native asyncio connection/cursor classes sharing one API surface
• libpq pipeline mode support for batching multiple queries over one round trip
• An optional C/Cython extension (psycopg_c) for CPU-bound adaptation hot paths
• A separate psycopg_pool package with sync and async connection pools
• Server-side (named) cursors, COPY support, and typed row factories (dict, namedtuple, dataclass)
• Full type adaptation system mapping PostgreSQL types (including arrays, ranges, JSON) to Python objects

Common Use Cases

• Powering async web frameworks (FastAPI, Starlette, async Django) that talk to PostgreSQL without blocking the event loop
• High-throughput services that need pipeline mode to cut round-trip latency on batched writes
• Migrating psycopg2 codebases to a maintained, actively developed driver with modern typing
• Applications needing precise control over server-side cursors and COPY for bulk data transfer

Under The Hood

Architecture: The repository is organized as three cooperating packages — psycopg/psycopg (pure-Python core defining Connection/AsyncConnection, Cursor/AsyncCursor, and the adaptation layer in _transformer.py/_adapters_map.py), psycopg_c (a Cython-compiled libpq binding for performance), and psycopg_pool (kept as a separately-released package so pooling can iterate on its own cadence). Connections communicate with PostgreSQL via generator-based state machines (generators.py, waiting.py) that let the same code drive both blocking sockets and asyncio event loops, which is how sync and async cursors share nearly identical implementations. Tech Stack: Python 3.9+, Cython/C for the optional binary extension, libpq as the underlying client library, pytest for testing, mypy --strict for type-checking across all three sub-packages. Code Quality: The tests/ directory contains 70+ test modules covering connections, cursors (sync/async/server-side/raw), COPY, pipelines, transactions, type adaptation, DNS/SRV resolution, and CockroachDB compatibility (tests/crdb/), with mirrored _async variants generated from shared fixtures to keep sync/async behavior in lockstep; mypy strict = true is enforced project-wide via pre-commit hooks. API Design: The public API deliberately follows PEP 249 (DB-API 2.0) conventions extended with async with/async for support, row factories for typed results, and context-manager-based transactions, so developers already familiar with psycopg2 or other DBAPI drivers have very little new surface to learn.