database/sql 的抽象税#

database/sql 是 Go 标准库的通用数据库接口。“通用”意味着它要兼容所有数据库驱动，所以：

• 参数和结果要经过通用接口。driver.Value 只能表达 nil、bool、int64、float64、string、[]byte、time.Time 等通用类型。PostgreSQL 的 uuid、jsonb、inet、range、composite 等类型，通常要依赖驱动转换，或者实现 Scanner / Valuer。
• PG 专属能力不好直接暴露。Batch、COPY、Listen/Notify、自定义类型注册、tracer hook 这些能力，在 pgx 原生 API 里是直接的一等能力；走 database/sql 时要么不可用，要么需要绕回具体驱动。
• 连接池语义更通用。sql.DB 有 SetMaxOpenConns、SetMaxIdleConns、SetConnMaxLifetime 等配置，足够可用；pgxpool 则额外提供 AfterConnect、BeforeAcquire、AfterRelease、Stat() 等更贴近 PostgreSQL 服务的控制点。

pgx 的原生优势#

pgx 直接实现 PostgreSQL wire protocol，不经过 database/sql：

• Extended protocol 和 statement cache。pgx 默认使用 extended protocol，并带有 prepared statement cache。对支持的类型，pgx 可以使用 binary format，避免很多文本编码/解析成本。
• 原生类型支持。pgtype 包覆盖大量 PostgreSQL 类型——uuid、jsonb、inet、range、composite 等，不需要全部压扁成字符串再解析。
• Batch query。一次网络往返发多条查询，减少 RTT。database/sql 没有这个能力。
• COPY protocol。批量插入走 PostgreSQL 的 COPY 协议，比逐行 INSERT 快一个数量级。
• 连接池透明。pgxpool 的配置项和状态都很直接：MaxConns、MinConns、MaxConnLifetime、MaxConnIdleTime、HealthCheckPeriod、Stat()。

pgxpool 的连接管理#

config, _ := pgxpool.ParseConfig(os.Getenv("DATABASE_URL"))
config.MaxConns = 20
config.MinConns = 5
config.MaxConnLifetime = 30 * time.Minute
config.MaxConnIdleTime = 5 * time.Minute

pool, _ := pgxpool.NewWithConfig(ctx, config)

pgxpool 还支持 AfterConnect hook——连接建立后自动注册自定义类型、设置 search_path、执行初始化 SQL。这在多租户场景下很有用。

目录结构#

.
├── go.mod
├── sqlc.yaml
├── schema.sql
├── query/
│   └── todo.sql
├── internal/
│   └── db/          ← sqlc 生成的代码
├── handler/
│   └── todo.go
└── main.go

schema.sql#

CREATE TABLE todos (
  id         BIGSERIAL PRIMARY KEY,
  title      TEXT NOT NULL,
  done       BOOLEAN NOT NULL DEFAULT false,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

query/todo.sql#

-- name: CreateTodo :one
INSERT INTO todos (title)
VALUES ($1)
RETURNING id, title, done, created_at;

-- name: ListTodos :many
SELECT id, title, done, created_at
FROM todos
ORDER BY created_at DESC
LIMIT $1;

-- name: MarkDone :execrows
UPDATE todos SET done = true WHERE id = $1;

main.go#

package main

import (
  "context"
  "os"

  "github.com/cloudwego/hertz/pkg/app/server"
  "github.com/jackc/pgx/v5/pgxpool"
  "example.com/todo-api/handler"
)

func main() {
  ctx := context.Background()

  pool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
  if err != nil {
    panic(err)
  }
  defer pool.Close()

  if err := pool.Ping(ctx); err != nil {
    panic(err)
  }

  h := server.Default(server.WithHostPorts(":8080"))

  todoHandler := handler.NewTodoHandler(pool)
  h.POST("/todos", todoHandler.Create)
  h.GET("/todos", todoHandler.List)
  h.PUT("/todos/:id/done", todoHandler.MarkDone)

  h.Spin()
}

handler/todo.go#

package handler

import (
  "context"
  "strconv"
  "strings"

  "github.com/cloudwego/hertz/pkg/app"
  "github.com/cloudwego/hertz/pkg/protocol/consts"
  "github.com/jackc/pgx/v5/pgxpool"
  "example.com/todo-api/internal/db"
)

type TodoHandler struct {
  pool *pgxpool.Pool
  q    *db.Queries
}

func NewTodoHandler(pool *pgxpool.Pool) *TodoHandler {
  return &TodoHandler{
    pool: pool,
    q:    db.New(pool),
  }
}

func (h *TodoHandler) Create(ctx context.Context, c *app.RequestContext) {
  var req struct {
    Title string `json:"title"`
  }
  if err := c.BindJSON(&req); err != nil {
    c.JSON(consts.StatusBadRequest, map[string]string{"error": err.Error()})
    return
  }

  req.Title = strings.TrimSpace(req.Title)
  if req.Title == "" {
    c.JSON(consts.StatusBadRequest, map[string]string{"error": "title is required"})
    return
  }

  todo, err := h.q.CreateTodo(ctx, req.Title)
  if err != nil {
    c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
    return
  }
  c.JSON(consts.StatusCreated, todo)
}

func (h *TodoHandler) List(ctx context.Context, c *app.RequestContext) {
  limit, err := strconv.ParseInt(c.DefaultQuery("limit", "20"), 10, 32)
  if err != nil || limit < 1 || limit > 100 {
    c.JSON(consts.StatusBadRequest, map[string]string{"error": "limit must be between 1 and 100"})
    return
  }

  todos, err := h.q.ListTodos(ctx, int32(limit))
  if err != nil {
    c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
    return
  }
  c.JSON(consts.StatusOK, todos)
}

func (h *TodoHandler) MarkDone(ctx context.Context, c *app.RequestContext) {
  id, err := strconv.ParseInt(c.Param("id"), 10, 64)
  if err != nil || id < 1 {
    c.JSON(consts.StatusBadRequest, map[string]string{"error": "invalid todo id"})
    return
  }

  rowsAffected, err := h.q.MarkDone(ctx, id)
  if err != nil {
    c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
    return
  }
  if rowsAffected == 0 {
    c.JSON(consts.StatusNotFound, map[string]string{"error": "todo not found"})
    return
  }

  c.Status(consts.StatusNoContent)
}

跑起来：

go mod init example.com/todo-api
go get github.com/cloudwego/hertz github.com/jackc/pgx/v5
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest

export DATABASE_URL='postgres://postgres:postgres@localhost:5432/todos?sslmode=disable'
createdb todos
sqlc generate
psql "$DATABASE_URL" -f schema.sql
go run .

如果你已经安装过 sqlc，go install 这一步可以跳过；如果数据库已经存在，createdb todos 也可以跳过。这里为了让示例最小化，直接用 psql -f schema.sql 建表；生产环境还是应该使用 migration 工具。除此之外，没有 ORM 初始化、没有 model 注册。SQL 写好，generate 一下，handler 里直接调用类型安全的函数。

事务怎么处理#

sqlc 生成的 Queries 有 WithTx 方法。下面假设你另外定义了 CreateAuditLog 这条 sqlc 查询：

func (h *TodoHandler) CreateWithAudit(ctx context.Context, c *app.RequestContext) {
  var req struct {
    Title string `json:"title"`
  }
  if err := c.BindJSON(&req); err != nil {
    c.JSON(consts.StatusBadRequest, map[string]string{"error": err.Error()})
    return
  }

  req.Title = strings.TrimSpace(req.Title)
  if req.Title == "" {
    c.JSON(consts.StatusBadRequest, map[string]string{"error": "title is required"})
    return
  }

  tx, err := h.pool.Begin(ctx)
  if err != nil {
    c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
    return
  }
  defer tx.Rollback(ctx)

  qtx := h.q.WithTx(tx)
  todo, err := qtx.CreateTodo(ctx, req.Title)
  if err != nil {
    c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
    return
  }

  if err := qtx.CreateAuditLog(ctx, db.CreateAuditLogParams{
    Action:   "create_todo",
    EntityID: todo.ID,
  }); err != nil {
    c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
    return
  }

  if err := tx.Commit(ctx); err != nil {
    c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
    return
  }

  c.JSON(consts.StatusCreated, todo)
}

事务边界完全显式——你能看到哪些操作在同一个事务里，不存在 GORM 那种”不知道这个 .Save() 有没有开事务”的困惑。

Migration#

sqlc 不管 migration。推荐搭配：

• golang-migrate/migrate：最成熟，支持 SQL 文件，CLI + Go 库双模式
• Atlas：声明式 schema diff，自动生成 migration，更现代但学习成本稍高
• goose：轻量，纯 SQL migration，跟 sqlc 的 SQL-first 哲学一致

# goose 示例
goose -dir migrations postgres "$DATABASE_URL" up

可观测性#

pgx 支持 tracer hook，可以接入 OpenTelemetry。常见做法是接一个 pgx tracer，例如：

import "github.com/exaring/otelpgx"

config, _ := pgxpool.ParseConfig(dbURL)
config.ConnConfig.Tracer = otelpgx.NewTracer()

每条 SQL 的执行时间和错误可以进入 tracing 系统。参数是否上报要谨慎配置，生产环境默认不要记录完整参数，尤其是用户输入、token、手机号、邮箱等敏感数据。配合 Hertz 的 middleware 做请求级 tracing，整条链路就能串起来。

连接池调优#

生产环境的 pgxpool 配置要从 PostgreSQL 的 max_connections、应用副本数、慢查询比例和 PgBouncer 部署方式一起推。可以先从保守值开始：

config.MaxConns = 20                         // 单个应用实例最多持有的连接数
config.MinConns = 5                          // 避免冷启动
config.MaxConnLifetime = 30 * time.Minute    // 防止连接长期不释放
config.MaxConnIdleTime = 5 * time.Minute     // 回收闲置连接
config.HealthCheckPeriod = 30 * time.Second  // 定期检查连接可用性

runtime.NumCPU() * 2 可以作为压测前的粗略起点，但不要按 QPS 线性放大连接数。PostgreSQL 连接本身很重，连接太多会让数据库先被调度和内存拖垮。

如果并发量特别大，可以在 pgxpool 前面加一层 PgBouncer。使用 transaction pooling 时要特别注意 prepared statement cache：pgx 默认会缓存 prepared statement，而 transaction mode 下同一个逻辑连接可能换到不同后端连接。除非你的 PgBouncer 版本和配置明确支持，否则建议关闭 statement cache 或改查询执行模式，例如：

import "github.com/jackc/pgx/v5"

config.ConnConfig.DefaultQueryExecMode = pgx.QueryExecModeExec

错误处理#

pgx 的错误类型是结构化的，可以精确匹配：

import "github.com/jackc/pgx/v5/pgconn"

var pgErr *pgconn.PgError
if errors.As(err, &pgErr) {
  switch pgErr.Code {
  case "23505": // unique_violation
    c.JSON(409, map[string]string{"error": "already exists"})
  case "23503": // foreign_key_violation
    c.JSON(400, map[string]string{"error": "referenced entity not found"})
  }
}

比 GORM 的 errors.Is(err, gorm.ErrDuplicatedKey) 更精确——你能拿到具体是哪个约束冲突了。

动态查询的补充方案#

sqlc 处理不了的动态查询场景（搜索、多条件过滤），可以局部引入 squirrel：

func (h *TodoHandler) Search(ctx context.Context, c *app.RequestContext) {
  qb := sq.Select("id", "title", "done", "created_at").From("todos")

  if title := c.Query("title"); title != "" {
    qb = qb.Where("title ILIKE ?", "%"+title+"%")
  }
  if done := c.Query("done"); done != "" {
    doneValue, err := strconv.ParseBool(done)
    if err != nil {
      c.JSON(consts.StatusBadRequest, map[string]string{"error": "done must be true or false"})
      return
    }
    qb = qb.Where("done = ?", doneValue)
  }

  query, args, err := qb.PlaceholderFormat(sq.Dollar).ToSql()
  if err != nil {
    c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
    return
  }

  rows, err := h.pool.Query(ctx, query, args...)
  if err != nil {
    c.JSON(consts.StatusInternalServerError, map[string]string{"error": err.Error()})
    return
  }
  defer rows.Close()

  // ...手动 scan
}

这不是”放弃 sqlc”，而是承认不同场景用不同工具。静态查询用 sqlc（类型安全），动态查询用 squirrel（灵活性），两者共存没有冲突。