asyncpg

library0.31.0pypypi✓ verified 11d ago

High-performance async PostgreSQL driver for Python/asyncio. Implements PostgreSQL binary protocol natively — ~5x faster than psycopg3 in benchmarks. Current version: 0.31.0 (Nov 2025). Still pre-1.0. NOT DB-API 2.0 compliant — uses $1/$2 placeholders not %s. No dict row support out of the box — returns Record objects. Major footgun: prepared statements break with pgbouncer in transaction/statement mode (Supabase, Neon poolers).

database http-networking

pip install asyncpg

github ↗package ↗

INSTALL

IMPORT

SIG · ASYNCPG

asyncpg

databasepythonv0.31.0

Install

1.9s avg

Import

286ms

Disk

26MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.31.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.304s · 25.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.9s · import 0.268s · 29MB

26MB installed

● package 26MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

asyncpg

✓ import asyncpg

✗ import asyncpg

asyncpg connection pool with correct $1/$2 placeholders.

# pip install asyncpg import asyncpg import asyncio async def main(): # Connection pool for production pool = await asyncpg.create_pool( 'postgresql://user:pass@localhost/mydb', min_size=2, max_size=10 ) async with pool.acquire() as conn: # $1, $2 — not %s await conn.execute( 'INSERT INTO users(name, email) VALUES($1, $2)', 'Alice', 'alice@example.com' ) # fetchrow returns asyncpg.Record — dict-like row = await conn.fetchrow( 'SELECT * FROM users WHERE name = $1', 'Alice' ) print(row['name']) # 'Alice' print(dict(row)) # convert to plain dict # fetch returns list of Records rows = await conn.fetch('SELECT id, name FROM users') await pool.close() asyncio.run(main())

Debug

Known issues

breakingPlaceholders are $1/$2/$3 (PostgreSQL native) NOT %s (psycopg2) or ? (sqlite3). LLMs trained on psycopg2 code consistently generate %s placeholders which fail with asyncpg.

fix

await conn.fetch('SELECT * FROM t WHERE id = $1 AND active = $2', id, True)

affects: all

breakingasyncpg is NOT DB-API 2.0 compliant. Code written for psycopg2/sqlite3 will not work without changes. No cursor objects, different method names (fetch/fetchrow/fetchval not execute/fetchone/fetchall).

fix

Use fetch() for multiple rows, fetchrow() for one row, fetchval() for a single value, execute() for DML without results.

affects: all

breakingPrepared statements break with pgbouncer in transaction/statement pool mode. Error: 'prepared statement asyncpg_stmt_X does not exist'. Affects Supabase transaction pooler (port 6543), Neon, and any pgbouncer setup.

fix

Set statement_cache_size=0 when connecting: await asyncpg.connect('...', statement_cache_size=0). For SQLAlchemy: connect_args={'statement_cache_size': 0}

affects: all

gotchafetch() returns list of asyncpg.Record objects, not dicts. Record supports dict-style access (row['name']) but isinstance(row, dict) is False. Code that expects dicts breaks silently.

fix

Convert with dict(row) or [dict(r) for r in rows] if you need plain dicts.

affects: all

gotchaStill pre-1.0 (0.31.x). API stability not guaranteed across minor versions.

fix

Pin version in production: pip install asyncpg==0.31.0

affects: all

gotchaPrepared statements and cursors from Connection.prepare() become invalid once a connection is released back to the pool. Must re-prepare on next acquisition.

fix

Don't cache prepared statement objects across pool.acquire() calls.

affects: all

breakingConnection failed: 'Connect call failed' (OSError: Errno 111) means the asyncpg client could not establish a network connection to the database server. This is typically due to the database not running, incorrect host/port in the connection string, or a firewall blocking the connection.

fix

Ensure the PostgreSQL server is running and accessible from the application's host/network. Verify the connection string (host, port) is correct. Check firewall rules.

affects: all

breakingasyncpg.create_pool or asyncpg.connect fails with 'OSError: [Errno 111] Connect call failed' if the PostgreSQL database server is not running, not listening on the specified host/port, or is unreachable due to network issues (e.g., firewall). This is a general network/database availability error, not specific to asyncpg's API or usage patterns.

fix

Ensure the PostgreSQL server is running, listening on the correct host and port, and is reachable from the application's network environment. Verify the database host, port, and any relevant firewall rules.

affects: all

Upgrade

Version history

0.31.0latest on PyPI · released Nov 24, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

30 hits · last 30 days

node

Resources

githubhttps://github.com/MagicStack/asyncpg ↗

packagehttps://pypi.org/project/asyncpg/ ↗