asyncpg
High-performance async PostgreSQL client library for Python asyncio — 3-10x faster than psycopg2 for most operations. asyncpg uses PostgreSQL binary protocol (not text), prepared statement caching, and efficient type codecs for optimal performance. Provides: connection pooling (asyncpg.create_pool()), raw SQL execution (await conn.fetch()), record objects with column access, custom type codecs, copy operations, and listen/notify for PostgreSQL events. Does not implement DBAPI 2.0 — uses its own async API. Used directly or as the driver underneath SQLAlchemy async and Tortoise ORM. Essential for high-throughput async Python agent services querying PostgreSQL.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Parameterized queries prevent SQL injection by default. TLS via ssl parameter for encrypted agent database connections. Database credentials via environment variables in DSN. LISTEN/NOTIFY pub/sub data should not contain sensitive agent information without encryption.
⚡ Reliability
Best When
You're building a high-performance async FastAPI or aiohttp agent service that queries PostgreSQL and need maximum throughput — asyncpg delivers 3-10x better performance than psycopg2 with native asyncio integration.
Avoid When
You need MySQL, you prefer ORM over raw SQL, or your agent service is synchronous (use psycopg2).
Use Cases
- • High-throughput async agent API with PostgreSQL — asyncpg connection pool with 20 connections handles 10k+ concurrent agent requests more efficiently than psycopg2 thread pool
- • Raw SQL agent data queries without ORM overhead — await pool.fetch('SELECT * FROM agents WHERE status = $1 ORDER BY created_at DESC LIMIT $2', 'active', 100) for high-performance agent list queries
- • Bulk agent data loading with COPY protocol — await conn.copy_records_to_table('agents', records=agent_batch) for 100x faster bulk agent data inserts vs individual INSERT statements
- • Real-time agent notifications via LISTEN/NOTIFY — await conn.add_listener('agent_events', callback) for PostgreSQL pub/sub event delivery to agent services without external message broker
- • Custom type codecs for agent-specific PostgreSQL types — register codec for PostgreSQL composite types or custom domains representing agent configuration objects
Not For
- • MySQL or SQLite — asyncpg is PostgreSQL-only; use aiomysql for async MySQL, aiosqlite for async SQLite in agent services
- • Synchronous Python applications — asyncpg is async-only; use psycopg2 or psycopg3 for synchronous agent data access
- • Teams wanting ORM — asyncpg is raw SQL; use SQLAlchemy async (with asyncpg driver) or Tortoise ORM for agent services that need model-based database access
Interface
Authentication
Database driver — auth via PostgreSQL credentials in DSN string or keyword arguments. Supports SSL/TLS for encrypted agent database connections.
Pricing
asyncpg is Apache 2.0 licensed, maintained by MagicStack. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ asyncpg is not DBAPI 2.0 — asyncpg uses its own API (fetch, fetchrow, execute, executemany); code written for psycopg2's cursor.execute()/fetchall() doesn't port directly; agent code migration from psycopg2 requires API rewrite not just driver swap
- ⚠ Connection pool must be created at startup — asyncpg.create_pool() is a coroutine; create pool in FastAPI lifespan event (asynccontextmanager) or startup handler; creating pool per request causes connection flood and defeats pooling for agent API
- ⚠ Parameter placeholders use $1/$2, not %s — asyncpg uses PostgreSQL-native $1, $2 positional parameters not Python %s or %(name)s; mixing placeholder styles causes PostgreSQL syntax error in agent queries
- ⚠ Record objects are read-only tuples — asyncpg fetch() returns Record objects (not dict); access by column name (record['agent_id']) or index; converting to dict requires dict(record) for agent code that needs mutable dicts
- ⚠ Pool min_size vs max_size affects agent throughput — default pool has max_size=10; under high agent request load, pool exhaustion queues requests; set max_size based on PostgreSQL max_connections and agent service instance count
- ⚠ SSL certificate verification requires explicit config — asyncpg verifies SSL certificates by default; self-signed dev PostgreSQL certificates require ssl=ssl.create_default_context() with custom CA; ssl='disable' for no verification (dev only, never production agent databases)
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for asyncpg.
Scores are editorial opinions as of 2026-03-06.