jackc/pgx
GitHub: jackc/pgx
pgx 是一个用纯 Go 编写的 PostgreSQL 驱动和工具包，提供高性能的数据库连接接口和底层协议解析组件。
Stars: 13509 | Forks: 1000
[](https://pkg.go.dev/github.com/jackc/pgx/v5)
[](https://github.com/jackc/pgx/actions/workflows/ci.yml)
# pgx - PostgreSQL Driver 和 Toolkit
pgx 是一个纯 Go 编写的 PostgreSQL 驱动和工具包。
pgx 驱动是一个底层的、高性能的接口，暴露了 PostgreSQL 特有的功能，例如 `LISTEN` /
`NOTIFY` 和 `COPY`。它还包含了一个用于标准 `database/sql` 接口的适配器。
工具包组件是一组相关的包，实现了 PostgreSQL 的功能，例如解析线协议
以及 PostgreSQL 和 Go 之间的类型映射。这些底层包可用于实现替代驱动、
代理、负载均衡器、逻辑复制客户端等。
## 用法示例
```
package main
import (
"context"
"fmt"
"os"
"github.com/jackc/pgx/v5"
)
func main() {
// urlExample := "postgres://username:password@localhost:5432/database_name"
conn, err := pgx.Connect(context.Background(), os.Getenv("DATABASE_URL"))
if err != nil {
fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
os.Exit(1)
}
defer conn.Close(context.Background())
var name string
var weight int64
err = conn.QueryRow(context.Background(), "select name, weight from widgets where id=$1", 42).Scan(&name, &weight)
if err != nil {
fmt.Fprintf(os.Stderr, "QueryRow failed: %v\n", err)
os.Exit(1)
}
fmt.Println(name, weight)
}
```
更多信息请参阅 [入门指南](https://github.com/jackc/pgx/wiki/Getting-started-with-pgx)。
## 特性
* 支持大约 70 种不同的 PostgreSQL 类型
* 自动语句准备和缓存
* 批量查询
* 单次往返查询模式
* 完整的 TLS 连接控制
* 对自定义类型的二进制格式支持（允许更快的编码/解码）
* `COPY` 协议支持，用于更快的大容量数据加载
* Tracing 和日志支持
* 带有连接后钩子（after-connect hook）的连接池，用于任意连接设置
* `LISTEN` / `NOTIFY`
* 将 PostgreSQL 数组转换为整数、浮点数和字符串的 Go slice 映射
* `hstore` 支持
* `json` 和 `jsonb` 支持
* 将 `inet` 和 `cidr` PostgreSQL 类型映射到 `netip.Addr` 和 `netip.Prefix`
* 大对象支持
* NULL 映射到指针的指针
* 支持自定义类型的 `database/sql.Scanner` 和 `database/sql/driver.Valuer` 接口
* Notice 响应处理
* 使用保存点（savepoints）模拟嵌套事务
## 在 pgx 和 database/sql 接口之间选择
pgx 接口速度更快。许多 PostgreSQL 特有的功能，如 `LISTEN` / `NOTIFY` 和 `COPY`，无法
通过 `database/sql` 接口使用。
建议在以下情况下使用 pgx 接口：
1. 应用程序仅针对 PostgreSQL。
2. 没有使用其他需要 `database/sql` 的库。
也可以使用 `database/sql` 接口，并根据需要将连接转换为底层的 pgx 接口。
## 测试
设置说明请参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
## 架构
关于 pgx 架构的描述，请参阅 Golang Estonia 的演示文稿 [PGX Top to Bottom](https://www.youtube.com/watch?v=sXMSWhcHCf8)。
## 支持的 Go 和 PostgreSQL 版本
pgx 支持各自团队支持的相同版本的 Go 和 PostgreSQL。对于 [Go](https://golang.org/doc/devel/release.html#policy)，这是最近的两个主要版本；对于 [PostgreSQL](https://www.postgresql.org/support/versioning/)，是过去 5 年内的主要版本。这意味着 pgx 支持 Go 1.24 及更高版本以及 PostgreSQL 14 及更高版本。pgx 也会针对 [CockroachDB](https://www.cockroachlabs.com/product/) 的最新版本进行测试。
## 版本策略
pgx 遵循语义化版本控制，适用于稳定版本的文档化公共 API。`v5` 是最新的稳定主要版本。
## PGX 系列库
### [github.com/jackc/pglogrepl](https://github.com/jackc/pglogrepl)
pglogrepl 提供了充当 PostgreSQL 逻辑复制客户端的功能。
### [github.com/jackc/pgmock](https://github.com/jackc/pgmock)
pgmock 提供了创建模拟 PostgreSQL 线协议的服务器的能力。这在内部通过故意引发异常错误来测试 pgx。pgproto3 和 pgmock 一起提供了实现 PostgreSQL 代理或 MitM（例如用于自定义连接池）所需的大部分基础工具。
### [github.com/jackc/tern](https://github.com/jackc/tern)
tern 是一个独立的 SQL 迁移系统。
### [github.com/jackc/pgerrcode](https://github.com/jackc/pgerrcode)
pgerrcode 包含 PostgreSQL 错误代码的常量。
## 第三方类型适配器
* [github.com/jackc/pgx-gofrs-uuid](https://github.com/jackc/pgx-gofrs-uuid)
* [github.com/jackc/pgx-shopspring-decimal](https://github.com/jackc/pgx-shopspring-decimal)
* [github.com/ColeBurch/pgx-govalues-decimal](https://github.com/ColeBurch/pgx-govalues-decimal)
* [github.com/twpayne/pgx-geos](https://github.com/twpayne/pgx-geos) ([PostGIS](https://postgis.net/) 和 [GEOS](https://libgeos.org/) 通过 [go-geos](https://github.com/twpayne/go-geos))
* [github.com/vgarvardt/pgx-google-uuid](https://github.com/vgarvardt/pgx-google-uuid)
## 第三方 Tracer 适配器
* [github.com/jackhopner/pgx-xray-tracer](https://github.com/jackhopner/pgx-xray-tracer)
* [github.com/exaring/otelpgx](https://github.com/exaring/otelpgx)
## 第三方 Logger 适配器
这些适配器可与 tracelog 包一起使用。
* [github.com/jackc/pgx-go-kit-log](https://github.com/jackc/pgx-go-kit-log)
* [github.com/jackc/pgx-log15](https://github.com/jackc/pgx-log15)
* [github.com/jackc/pgx-logrus](https://github.com/jackc/pgx-logrus)
* [github.com/jackc/pgx-zap](https://github.com/jackc/pgx-zap)
* [github.com/jackc/pgx-zerolog](https://github.com/jackc/pgx-zerolog)
* [github.com/mcosta74/pgx-slog](https://github.com/mcosta74/pgx-slog)
* [github.com/kataras/pgx-golog](https://github.com/kataras/pgx-golog)
## 支持 PGX 的第三方库
### [github.com/pashagolub/pgxmock](https://github.com/pashagolub/pgxmock)
pgxmock 是一个实现了 pgx 接口的模拟库。
pgxmock 唯一的目的是在测试中模拟 pgx 行为，而无需真实的数据库连接。
### [github.com/georgysavva/scany](https://github.com/georgysavva/scany)
用于将数据库中的数据扫描到 Go 结构体等的库。
### [github.com/vingarcia/ksql](https://github.com/vingarcia/ksql)
一个经过精心设计的 SQL 客户端，旨在让 SQL 的使用更简单、
更高效且更不易出错，专为 Golang 打造。
### [github.com/otan/gopgkrb5](https://github.com/otan/gopgkrb5)
添加 GSSAPI / Kerberos 身份验证支持。
### [github.com/wcamarao/pmx](https://github.com/wcamarao/pmx)
用于 Go 结构体和切片的显式数据映射和扫描库。
### [github.com/stephenafamo/scan](https://github.com/stephenafamo/scan)
类型安全且灵活的包，用于将数据库数据扫描到 Go 类型中。
支持结构体、map、切片和自定义映射函数。
### [github.com/z0ne-dev/mgx](https://github.com/z0ne-dev/mgx)
用于原生 pgx 的代码优先迁移库（无 database/sql 抽象）。
### [github.com/amirsalarsafaei/sqlc-pgx-monitoring](https://github.com/amirsalarsafaei/sqlc-pgx-monitoring)
用于 pgx 和 sqlc 的数据库监控/指标库。使用 OpenTelemetry 跟踪、记录和监控您的 sqlc 查询性能。
### [https://github.com/nikolayk812/pgx-outbox](https://github.com/nikolayk812/pgx-outbox)
使用 jackc/pgx 驱动的 PostgreSQL 事务性发件箱模式的简单 Golang 实现。
### [https://github.com/Arlandaren/pgxWrappy](https://github.com/Arlandaren/pgxWrappy)
简化 pgx 库的使用，提供便捷的嵌套结构扫描。
### [https://github.com/KoNekoD/pgx-colon-query-rewriter](https://github.com/KoNekoD/pgx-colon-query-rewriter)
pgx 查询重写器的实现，用于在命名查询参数中使用 ':' 代替 '@'。
标签：EVTX分析, Go, Golang, Golang库, ORM替代, pgx, Postgres, PostgreSQL, Ruby工具, SQL, 后端开发, 安全编程, 底层编程, 开发组件, 开源库, 搜索引擎爬虫, 数据库代理, 数据库工具包, 数据库连接池, 数据库驱动, 日志审计, 测试用例, 类型映射, 系统审计, 负载均衡, 逻辑复制