asyncpg — Fast Async PostgreSQL Driver for Python

Introduction

asyncpg is a high-performance asyncio PostgreSQL client library for Python, written in Cython. It implements the PostgreSQL binary protocol directly, bypassing libpq, and achieves 3x the throughput of psycopg2 in async workloads. It is the recommended PostgreSQL driver for async Python frameworks like FastAPI, Starlette, and Sanic.

What asyncpg Does

• Connects to PostgreSQL using native asyncio with the binary wire protocol
• Executes queries with automatic type conversion between Python and PostgreSQL types
• Manages connection pools with configurable min/max size and health checks
• Supports prepared statements, transactions, cursors, and COPY operations
• Handles PostgreSQL LISTEN/NOTIFY for real-time event subscriptions

Architecture Overview

asyncpg communicates directly with PostgreSQL using the binary protocol (not libpq), which eliminates the overhead of text serialization. Cython-compiled codecs handle type conversion at near-C speed. The connection pool maintains a set of warmed connections with prepared statement caches, reducing per-query overhead. Each connection runs its own protocol state machine integrated with the asyncio event loop.

Setup & Configuration

• Install via pip install asyncpg (requires a C compiler for Cython extensions)
• Connect with asyncpg.connect(dsn) or use asyncpg.create_pool(dsn) for pooling
• Configure pool size with min_size and max_size parameters
• Set statement_cache_size to control per-connection prepared statement caching
• Use server_settings dict to set PostgreSQL session parameters like search_path

Key Features

• Binary protocol implementation delivers 3x throughput vs text-based drivers
• Cython-compiled codecs for fast Python-to-PostgreSQL type conversion
• Built-in connection pooling with health checks and automatic reconnection
• Prepared statement caching reduces repeated query parsing overhead
• LISTEN/NOTIFY support for real-time PostgreSQL event streaming

Comparison with Similar Tools

• psycopg (v3) — supports both sync and async, asyncpg is async-only but faster for pure async workloads
• psycopg2 — synchronous only, asyncpg is async-native with higher throughput
• SQLAlchemy asyncio — ORM layer that can use asyncpg as its backend driver
• databases — async database abstraction, often uses asyncpg under the hood for PostgreSQL

FAQ

Q: Can I use asyncpg with SQLAlchemy? A: Yes. SQLAlchemy 1.4+ supports asyncpg as a dialect via postgresql+asyncpg:// connection strings.

Q: How does asyncpg compare to psycopg3 in performance? A: asyncpg is generally faster for raw query throughput due to its Cython implementation and binary protocol. psycopg3 offers broader compatibility and a sync API.

Q: Does asyncpg support connection pooling? A: Yes. Use asyncpg.create_pool() for a built-in pool with configurable min/max connections and automatic health checks.

Q: Can I use asyncpg with Django? A: Django does not natively support asyncpg. Use it with async frameworks like FastAPI, Starlette, or Sanic instead.

Sources

• https://github.com/MagicStack/asyncpg
• https://magicstack.github.io/asyncpg/