asyncpg is a PostgreSQL database client library for Python's asyncio framework that implements the PostgreSQL server binary protocol natively, intended for Python developers building asynchronous applications against PostgreSQL.

What it is

asyncpg is a database interface library designed specifically for PostgreSQL and Python/asyncio. It is developed and maintained by MagicStack, distributed under the Apache 2.0 licence, and published on PyPI. Rather than layering an abstraction over the database, asyncpg implements the PostgreSQL server binary protocol natively and exposes PostgreSQL features directly to application code.

The concrete problem it solves is the loss of fidelity and throughput that comes from driving PostgreSQL through a generic facade. asyncpg positions itself explicitly against a generic DB-API style abstraction, which tends to hide server-side capabilities behind a lowest-common-denominator interface. By speaking the binary protocol and exposing PostgreSQL's own semantics, asyncpg makes features such as prepared statements, scrollable cursors and partial result iteration available without workarounds, and lets composite types and arrays cross the wire without manual conversion. It is the asyncio-native alternative to psycopg3 in the PostgreSQL driver segment of the Python ecosystem.

Key capabilities

• Implements the PostgreSQL server binary protocol natively and exposes its features directly, rather than hiding them behind a generic facade such as DB-API.
• Support for prepared statements, scrollable cursors, and partial iteration on query results.
• Automatic encoding and decoding of composite types, arrays, and any combination of those.
• Straightforward support for custom data types.
• Runs on Python 3.9 or later and is supported for PostgreSQL versions 9.5 to 18.
• Installed from PyPI as asyncpg with no dependencies when GSSAPI/SSPI authentication is not used; asyncpg[gssauth] adds that support.
• Core API centres on asyncpg.connect(...) and conn.fetch('SELECT * FROM mytable WHERE id = $1', 10), with await conn.close() for teardown.

Who uses it and how

• Python/asyncio services that need a database driver built for the same event loop, rather than a synchronous driver wrapped in a thread pool.
• Throughput-sensitive workloads: in project testing, a geometric mean of benchmarks from the PostgreSQL client driver benchmarking tool toolbench in June 2023 put asyncpg on average 5x faster than psycopg3.
• Applications that rely on PostgreSQL-specific data shapes, where automatic encoding and decoding of composite types and arrays removes manual marshalling.
• Environments requiring GSSAPI or SSPI authentication, served by the optional asyncpg[gssauth] install extra.

Getting started

Install from PyPI with pip install asyncpg, or use pip install 'asyncpg[gssauth]' if GSSAPI/SSPI authentication is required. Connect from an asyncio program with asyncpg.connect(...) and issue queries with conn.fetch(...).

How it compares

The facts name one comparable tool, psycopg3, which asyncpg benchmarks against at roughly 5x faster on average. The distinction is architectural rather than commercial: asyncpg targets PostgreSQL and asyncio directly through the server binary protocol, while a DB-API style facade trades some of that exposure and speed for broader interface conformity. No list of paid products that asyncpg replaces is provided in the facts.

When to use it — and when not to

A team adopting asyncpg must already run and operate its own PostgreSQL server, because asyncpg is a client library and nothing more; it ships no database, no storage layer and no managed hosting. Projects committed to synchronous code, to DB-API portability across multiple database engines, or to PostgreSQL versions outside the tested 9.5 to 18 range should look elsewhere, since other databases implementing the PostgreSQL protocol may work but are not actively tested. The project carries a substantial open-issue count of 308, and the README itself is terse, so a self-hoster should expect to work from the linked documentation and the code rather than from extensive in-repo guidance.

$ pip install asyncpg

$ pip install 'asyncpg[gssauth]'

import asyncio
import asyncpg

async def run():
    conn = await asyncpg.connect(user='user', password='password',
                                 database='database', host='127.0.0.1')
    values = await conn.fetch(
        'SELECT * FROM mytable WHERE id = $1',
        10,
    )
    await conn.close()

asyncio.run(run())