pgwire

为您的数据服务构建兼容 Postgres 的访问层。

该库实现了 PostgreSQL 线协议，并提供编写兼容 PostgreSQL 的服务器和客户端所需的基本 API。它类似于 hyper，但用于 postgres 线协议。

datafusion-postgres 项目是一个基于 pgwire 构建的更完整的库，以 datafusion 作为查询引擎，并实现了基于 datafusion 的 pg_catalog。

如果您对相关主题感兴趣，可以查看项目想法以基于此库进行构建。

状态

关于 Postgres 线协议

Postgres 线协议是一种相对通用的第 7 层协议。该协议包含 6 个部分：

启动：客户端与服务器之间的握手和身份验证。
简单查询：postgresql 的基于文本的查询协议。查询以字符串形式提供，服务器允许以流式方式返回响应数据。
扩展查询：一种新的查询子协议，能够在服务器端缓存查询并使用新参数复用。响应部分与简单查询相同。
复制：用于从 postgresql 复制数据到 postgresql 的子协议。
复制
逻辑复制

另外请注意，Postgres 线协议不包含关于 SQL 的语义，因此从字面意义上讲，您可以使用任何查询语言、数据格式甚至自然语言与后端进行交互。

响应始终以数据行格式编码。并且数据头部包含字段描述，用于描述其名称、类型和格式。

Jelte Fennema-Nio 在 PgConf.dev 2024 上的演讲对线协议的工作原理进行了很好的介绍： https://www.youtube.com/watch?v=nh62VgNj6hY

用法

服务器/后端

要在你的服务器应用程序中使用 pgwire，你需要实现两个关键组件：startup processor 和 query processor。对于查询处理，有两种类型的查询：simple 和 extended。通过向你的应用程序添加 SimpleQueryHandler，你将获得 psql 命令行工具兼容性。而对于更多语言驱动程序以及额外的 prepared statement、二进制编码支持，则需要 ExtendedQueryHandler。

提供了示例来演示 pgwire 在服务器端的最基本用法：

examples/sqlite.rs: 核心使用内存中的 sqlite 数据库，并通过 postgresql 协议提供服务。这是一个包含 simple 和 extended 查询实现的完整示例。cargo run --features _sqlite --example sqlite
examples/duckdb.rs: 现已移至 pgwire-duckdb
examples/gluesql.rs: 核心使用内存中的 gluesql，并通过 postgresql 协议提供服务。
examples/server.rs: 演示一个始终返回固定结果的服务器。
examples/secure_server.rs: 演示一个支持 ssl 且始终返回固定结果的服务器。
examples/scram.rs: 演示如何配置更安全的身份验证机制： SCRAM
examples/transaction.rs: 查看如何在 wire 协议级别控制事务状态。
examples/datafusion.rs: 现已移至 datafusion-postgres
examples/oauth.rs, examples/keycloak_oauth.rs: Postgres 18 OAuth 身份验证的示例。

Client/Frontend

客户端/前端 API 正在开发中。该 API 将专注于提供对 postgres 线协议的完全访问。它旨在构建类似 postgres 代理的组件。对于用于应用程序开发的通用 postgres 驱动程序，您可以使用 rust-postgres。

使用 pgwire 的项目

GreptimeDB：云原生时序数据库
risinglight：用于教育目的的 OLAP 数据库系统
PeerDB Postgres 优先的 ETL/ELT，实现 Postgres 数据进出速度提升 10 倍，已被 Clickhouse 收购
CeresDB CeresDB 是蚂蚁集团的高性能、分布式、云原生时序数据库。
dozer 一个用于构建、部署和维护数据产品的实时数据平台。
pg_catalog 为自定义数据库提供 postgres 兼容层。
SpacetimeDB 面向多人游戏的数据库。它使用 pgwire 作为 postgres 协议接口。
corrosion 来自 fly.io：基于 Gossip 的大型分布式系统服务发现（及其他功能）。
db9.ai：面向智能体的 Postgres。

如果您的项目未在此列出，请提交拉取请求。

社区

开发者邮件列表

如果您喜欢 pgwire 的理念并希望加入该库的开发，或其生态集成、扩展，欢迎加入我们的开发者邮件列表：https://groups.io/g/pgwire-dev/

Github 讨论

本仓库的 Github 讨论区也开放用于更多一般性问题。

许可证

本库以 MIT/Apache 双重许可证发布。