asyncpg：专为 asyncio 打造的 PostgreSQL 驱动

文章目录

[asyncpg：专为 asyncio 打造的 PostgreSQL 驱动](#asyncpg：专为 asyncio 打造的 PostgreSQL 驱动)

asyncpg：专为 asyncio 打造的 PostgreSQL 驱动

asyncpg 是一款专为 PostgreSQL 和 Python 异步生态设计的数据库驱动库，由 MagicStack 团队维护，目前在 GitHub 上获得了超过 8,000 颗 Star。

它的核心定位很清晰：为 Python 的 asyncio 框架提供高效、干净的 PostgreSQL 服务端二进制协议实现。不同于主流的 ORM 或统一数据库抽象层，asyncpg 选择直接暴露 PostgreSQL 的原生能力，让开发者能充分利用数据库底层特性，而不被中间层遮挡。

性能表现

asyncpg 最明显的特性之一是速度。根据项目维护方在 2023 年 6 月使用 pgbench 工具进行的基准测试，asyncpg 平均比 psycopg3 快 5 倍。这个数字来自多次测试的几何平均值，覆盖了常见查询场景。对于高并发的异步应用，这种性能差距会直接影响响应延迟和吞吐量。

设计思路

asyncpg 没有遵循 Python 的 DB-API 规范，而是直接实现了 PostgreSQL 服务端协议。这种设计带来几个实际好处：prepared statements 开箱即用，scrollable cursors 不需要额外封装，查询结果支持部分迭代而不是一次性全部加载进内存，复合类型和数组的编解码自动完成，自定义数据类型的扩展也足够直接。

这种直达底层的方式意味着开发者可以充分利用 PostgreSQL 的高级特性，代价是需要对协议本身有一定了解。

环境要求

asyncpg 需要 Python 3.9 或更高版本，支持的 PostgreSQL 版本范围从 9.5 到 18。安装时没有额外运行时依赖，除非需要使用 GSSAPI/SSPI 认证。

安装

通过 pip 即可安装：

复制代码

pip install asyncpg

如果需要 GSSAPI/SSPI 认证支持：

复制代码

pip install 'asyncpg[gssauth]'

基本用法

asyncpg 的 API 设计围绕 asyncio 的 async/await 语法：

python 复制代码

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())

代码结构直观：建立连接、执行查询、获取结果、关闭连接，全部使用 await 关键字衔接。参数绑定通过 $1、$ 2 等占位符实现，避免字符串拼接带来的注入风险。fetch 方法返回的是 Record 对象列表，既可以通过列名访问字段，也可以通过索引取值。

适用场景

asyncpg 适合已经使用 asyncio 构建应用的 Python 项目，尤其是需要直接操控 PostgreSQL 高级特性的场景。如果你正在使用 FastAPI、Sanic 或其他异步框架处理高并发请求，asyncpg 是一个值得考虑的数据库层选择。对于习惯了同步数据库驱动的开发者，切换到异步模型需要一定的学习成本，但性能回报通常是值得的。

项目采用 Apache 2.0 协议开源。

习惯了同步数据库驱动的开发者，切换到异步模型需要一定的学习成本，但性能回报通常是值得的。

项目采用 Apache 2.0 协议开源。