# asyncpg — Fast Async PostgreSQL Driver for Python

> High-performance asyncio PostgreSQL client written in Cython, delivering 3x the throughput of psycopg2 for async workloads.

## Install

Save in your project root:

# asyncpg — Fast Async PostgreSQL Driver for Python

## Quick Use
```bash
pip install asyncpg
```
```python
import asyncio
import asyncpg

async def main():
    conn = await asyncpg.connect('postgresql://user:pass@localhost/mydb')
    row = await conn.fetchrow('SELECT $1::int AS num', 42)
    print(row['num'])  # 42
    await conn.close()

asyncio.run(main())
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-03d79b4b
Author: AI Open Source