一个列表接口上线第一天正常,第二天下午开始大量报错,数据库日志里是 FATAL: sorry, too many clients already。代码里每个请求都执行一次 sql.Open,用完没有 Close;开发者以为 Open 只是打开一个连接,实际上每次调用都可能创建一整套连接池。并发一上来,池套池,数据库的 max_connections 很快被耗尽。

另一台机器上,服务没有报连接数错误,但接口经常卡住几十秒,最后返回 context deadline exceeded。数据库连接数没满,应用侧却在排队等连接:SetMaxOpenConns 设成了一个很小的值,所有请求挤在同一批连接上,前面的事务还没提交,后面的请求只能等。连接数不足和连接数过多,表现完全不同,排查方向也相反。

这篇讲 Go 服务访问 PostgreSQL 的四个基本问题:连接池怎么建、参数怎么算;查询和 NULL 怎么处理;事务和死锁怎么重试;表结构怎么迁移。示例用 PostgreSQL 16 与 pgx/v5,本机没有数据库服务,凡是依赖数据库的返回都会明确标注「未在本机实测」,代码可以照着写,但结果要以你自己的环境为准。

sql.DB 本身就是一个池

sql.DB 不是一条连接,而是一个连接池的句柄。它可以在多个 goroutine 里安全共享,内部按需创建连接、复用空闲连接、在连接损坏时丢弃重建。正确用法是进程启动时创建一次,传给需要它的 store 或 repository,进程退出时关闭;不是每个请求创建一次。

sql.Open 本身不会立即连接数据库,它只校验驱动名和 DSN 格式,真正的连接在第一次使用时建立。所以「Open 成功」不代表数据库可用,启动时应该用 PingContext 做一次带超时的探活。探活失败就直接退出,比服务起来后每个请求都失败要好排查得多。

一次查询拿连接的顺序
请求进入
从池里取空闲连接
无空闲则等待或新建
执行 SQL
归还连接

池的意义是控制「同时打到数据库的连接数」,同时避免每次请求都做 TCP 握手和认证。连接建立是有成本的,频繁创建销毁会让数据库的认证和内存分配压力变大;但连接一直不释放,又会占住数据库的槽位。池参数就是在这两者之间找平衡。

池参数与取值算术

用 database/sql 时,四个参数最需要理解:

参数控制什么取值思路
SetMaxOpenConns同时打开的最大连接数,含正在使用和空闲按实例数乘出来,必须小于数据库上限并留余量
SetMaxIdleConns池里保留的空闲连接数不低于常见并发,避免反复建连;不要超过 MaxOpen
SetConnMaxLifetime一条连接从创建起最多活多久短于网络设备或数据库的空闲切断时间,便于轮换凭证
SetConnMaxIdleTime一条空闲连接最多留多久比 Lifetime 短,低峰期主动收缩,释放数据库槽位

算术从数据库上限倒推。PostgreSQL 的 max_connections 默认是 100,其中还有超级用户保留位;假设应用部署 4 个实例,每个实例最多 20 条连接,就是 80 条,再加上迁移任务、监控、运维登录,余量已经很小。更稳的做法是每个实例 15 条,总共 60 条,把剩下的留给其他用途。实例数会变,池参数也应该跟着发布配置走,而不是写死在代码里。

具体设多少要看实际并发、SQL 耗时和数据库规格,不能照搬一个数字。可以用一个简单的估算:单实例需要的连接数大约等于「并发请求数乘平均持有时长,再除以目标排队时间」,算出来后再留一倍余量,最后用压测验证。没有压测数据时,宁可从小开始,观察等待指标再逐步加。

生命周期要配合基础设施。云数据库、负载均衡器、防火墙经常会把长时间空闲的 TCP 连接悄悄切断,应用侧却以为连接还活着,下一次查询就报 connection reset by peer 或 unexpected EOF。SetConnMaxLifetime 设得比对方的空闲超时短,让连接在被动切断前主动退役,是成本最低的规避方式。凭证轮换时,较短的生命周期也能保证旧密码的连接逐步消失。

MaxIdle 不要设成 0。设成 0 意味着每次查询结束都关连接,高并发下会不停建连,延迟和数据库压力都会上升。也不要让 MaxIdle 等于 MaxOpen 且长期保持,低峰期会白占数据库槽位。常见做法是 Idle 取 Open 的一半到全部,再配合 IdleTime 让空闲连接慢慢退掉。

pgx 与 database/sql 怎么选

pgx 是 PostgreSQL 的 Go 驱动,v5 提供两套用法:一套是原生接口,直接用 pgx.Conn 或 pgxpool.Pool,支持 PostgreSQL 特有的类型、批量协议和更细的控制;另一套是 database/sql 兼容层,通过 github.com/jackc/pgx/v5/stdlib 注册驱动,用标准的 sql.DB。

pgx 原生接口

类型支持更完整,批量查询和 Copy 更快,池参数直接用 pgxpool.Config 配置。代价是 API 与标准库不同,换数据库或换驱动时要改代码。新项目、只用 PostgreSQL 时优先考虑。

database/sql 兼容层

接口通用,团队熟悉,第三方库大多接受 *sql.DB。缺点是只能使用标准库抽象出来的能力,PostgreSQL 特有的类型和批量操作要额外处理。已有项目或需要保持驱动可替换时更合适。

本组示例用 database/sql 加 pgx 的兼容层,因为池参数、事务和查询的写法最通用;理解了这一套,换到 pgxpool 只是把 SetMaxOpenConns 换成 cfg.MaxConns,把 BeginTx 换成 pool.Begin。不要把两套 API 混在同一个 store 里,连接池会变成两个,容量规划直接失效。

import (
	"database/sql"
	_ "github.com/jackc/pgx/v5/stdlib"
)

db, err := sql.Open("pgx", dsn)
if err != nil {
	return err
}
db.SetMaxOpenConns(15)
db.SetMaxIdleConns(8)
db.SetConnMaxLifetime(30 * time.Minute)
db.SetConnMaxIdleTime(10 * time.Minute)

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
if err := db.PingContext(ctx); err != nil {
	return err
}

DSN 里至少要写清地址、库名和 SSL 模式。本地开发常用 sslmode=disable,生产必须开启并配置证书;不要把密码拼在日志里,也不要把完整 DSN 打进错误信息。连接超时用 connect_timeout,语句超时用数据库侧的 statement_timeout,两者作用不同:前者管建立连接,后者管 SQL 执行。

go mod init demo/ordersvc
go get github.com/jackc/pgx/v5@v5.7.1
go get github.com/jackc/pgx/v5/stdlib
module demo/ordersvc

go 1.27.3

require github.com/jackc/pgx/v5 v5.7.1
go mod tidy
$env:DATABASE_URL="postgres://app:secret@127.0.0.1:5432/appdb?sslmode=disable"
$env:APP_PORT="18091"
go run ./cmd/api

本机没有可用的 PostgreSQL 实例,服务器和查询示例都没有实际运行,下面只写预期形状,标注为未实测。你在本地起一个 PostgreSQL 16 容器后,把 DSN 换掉即可复现。

查询、NULL 与超时

单行查询用 QueryRowContext,它返回一个延迟执行的 Row,只有调用 Scan 时才真正读取。没有匹配行时返回 sql.ErrNoRows,这是正常的业务分支,不是系统错误;接口应该把它映射成 404,而不是 500。多行查询用 QueryContext,必须 defer rows.Close() 并在循环后检查 rows.Err(),否则连接可能没有归还,错误也可能被吞掉。

ctx, cancel := context.WithTimeout(c.Request.Context(), 3*time.Second)
defer cancel()

var status string
err := db.QueryRowContext(ctx,
	`SELECT status FROM orders WHERE id = $1`, orderID).Scan(&status)
if errors.Is(err, sql.ErrNoRows) {
	c.JSON(http.StatusNotFound, gin.H{"error": "order not found"})
	return
}
if err != nil {
	c.JSON(http.StatusInternalServerError, gin.H{"error": "query failed"})
	return
}
curl -i -X POST http://127.0.0.1:18091/v1/orders \
  -H "Content-Type: application/json" \
  -d '{"user_id":"u_42","product_id":"p_1","qty":1}'
# 未在本机实测,预期 201 与下面的响应形状
{"id":"ord_1001","status":"created"}

curl -i http://127.0.0.1:18091/v1/orders/ord_1001
# 未在本机实测,预期 200
{"id":"ord_1001","status":"created","note":null}

NULL 是查询里最容易踩的类型问题。数据库列允许 NULL,Go 的 string 和 int 不能接收 NULL,Scan 会直接报 converting NULL to string is unsupported。解决办法有三种:用 sql.NullString 这类包装类型,用指针类型,或者用 pgx 的 pgtype 类型。选一种在项目里统一,不要一会儿指针一会儿 NullString,调用方会很难判断。

context 超时要从请求上下文传下来。c.Request.Context() 在客户端断开时会取消,数据库查询也能随之结束,避免为一个已经没人等的请求继续消耗连接。再包一层 WithTimeout,给单次查询设一个上限。注意超时值要大于正常查询耗时,否则高峰期会把慢一点的正常查询也杀掉;日志里要记录超时发生在哪条 SQL,否则只能看到一句 context deadline exceeded。

不要把 context.Background() 直接传进查询。它没有截止时间,也无法随请求取消,一旦数据库卡住,连接会被长期占住。后台任务可以用独立的上下文,但同样要设总超时,并且和请求上下文分开,避免请求结束时把后台任务也取消掉。

事务:提交、回滚与死锁重试

事务用 BeginTx 开启,成功路径 Commit,失败路径 Rollback。常见写法是 defer tx.Rollback(),提交成功后再执行一次 Rollback 会返回 sql.ErrTxDone,可以忽略。这个 defer 的意义是:任何提前 return、panic 或错误分支,都不会把事务一直挂着占连接。

tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
if err != nil {
	return err
}
defer func() { _ = tx.Rollback() }()

var stock int
if err := tx.QueryRowContext(ctx,
	`SELECT stock FROM products WHERE id = $1 FOR UPDATE`, productID).Scan(&stock); err != nil {
	return err
}
if stock < qty {
	return ErrOutOfStock
}
if _, err := tx.ExecContext(ctx,
	`UPDATE products SET stock = stock - $1 WHERE id = $2`, qty, productID); err != nil {
	return err
}
if _, err := tx.ExecContext(ctx,
	`INSERT INTO orders (id, product_id, qty) VALUES ($1, $2, $3)`, orderID, productID, qty); err != nil {
	return err
}
return tx.Commit()

隔离级别不是越高越好。读已提交(Read Committed)是 PostgreSQL 的默认级别,能满足大多数业务;可重复读和串行化会增加冲突和重试概率。选择之前先想清楚要防的是脏读、丢失更新还是写偏斜,不要为了「更安全」直接上串行化,然后靠大量重试掩盖设计问题。

死锁不是异常,是并发写入的正常结果。两个事务以相反顺序更新同一批行,数据库会检测到循环等待,牺牲其中一个并返回错误码 40P01;串行化冲突的错误码是 40001。这类错误应该重试整个事务,而不是只重试最后一条 SQL,因为事务里的读取结果可能已经失效。

func isRetryable(err error) bool {
	var pgErr *pgconn.PgError
	if errors.As(err, &pgErr) {
		return pgErr.Code == "40P01" || pgErr.Code == "40001"
	}
	return false
}

重试要有限次数、有退避,并且只对可重试错误重试。连接超时、语法错误、唯一键冲突都不该盲目重试;唯一键冲突往往说明请求重复,应该先查幂等键。重试次数用完后返回明确的错误,不要无限循环。日志里记录每次重试的错误码和事务标识,才能判断是偶发死锁还是锁顺序设计有问题。

减少死锁最有效的办法是统一加锁顺序。所有事务都按同一个字段或同一批主键顺序更新,交叉等待的概率会大幅下降。另一个办法是缩短事务:不要在事务里发 HTTP 请求、等用户输入或做大量计算,连接和锁都被占着,别人只能排队。

迁移:版本化、顺序与发布

表结构变更不要靠手写 SQL 在数据库里执行。用 golang-migrate 这类工具,把每次变更写成带版本号的文件,提交进版本库,按顺序执行。文件名通常是 000001_create_orders.up.sql 和对应的 .down.sql;up 做变更,down 负责回退。工具会在数据库里维护一张版本表,记录当前执行到哪一版。

migrate create -ext sql -dir migrations -seq create_orders
migrate -path ./migrations -database $env:DATABASE_URL up
migrate -path ./migrations -database $env:DATABASE_URL version

迁移和代码发布的顺序要按「兼容」来排,而不是按「谁先谁后无所谓」。安全的顺序是:先加新列或新表,允许为空;发布同时写新旧两套的代码;回填历史数据;切换读取到新列;确认无回滚需求后,再在后续版本删除旧列。这个模式叫扩展与收缩,好处是任何一个中间状态,新旧代码都能跑。

不要在同一个发布里既删列又改代码。旧实例还在跑,删列会让它们立刻报错;滚动发布期间新旧版本并存,数据库必须同时满足两边。破坏性变更拆成两次发布,中间留一个观察期,是零停机的基本代价。

迁移任务只能有一个执行者。让每个应用实例启动时都跑 migrate up,并发执行可能互相阻塞,甚至留下半完成状态。正确做法是把迁移放进独立的发布步骤,或者用数据库 advisory lock 保证只有一个进程在改结构。迁移失败后状态会标记为 dirty,此时不要直接 force 到新版本假装成功;先看清哪条语句失败、数据库实际改到哪一步,手工修复后再把版本对上。

回退脚本也要写,但不要假设它一定能用。删表、删列的回退会丢数据;数据回填的回退往往无法还原。对这类变更,回退方案应该是「从备份恢复」或「向前修复」,而不是机械执行 down。迁移文件一旦合并到主干并被环境执行,就不要修改内容,新增一个版本去修正,否则不同环境的版本号相同、结构却不同。

N+1 与批量查询

列表页最常见的慢查询不是单条 SQL 慢,而是循环里查。先查 20 个订单,再为每个订单查一次用户,总共 21 次往返;接口在本地测很快,线上网络延迟一放大就变成几百毫秒。这类模式叫 N+1,ORM 的关联加载最容易产生,手写代码在 for 循环里调用查询也一样。

解决办法是批量。能用 JOIN 一次拿到的,就用 JOIN;不能 JOIN 的,把需要的 id 收集起来,用一条 WHERE id = ANY($1) 或 IN 查询,再在内存里做映射。批量查询的个数要有上限,一次查几千个 id 会撑大内存和 SQL 长度;超过上限就分批,每批几百个。

分页也有代价。OFFSET 很大时,数据库要扫描并丢弃前面的行,越翻越慢。数据量上来后改用基于游标的分页,比如按创建时间和 id 排序,下一页从上一页最后一条之后开始。这个改动会影响接口契约,前端要接受「不能直接跳到第 100 页」,但换来的是稳定的响应时间。

索引不是万能的。给低选择性的列建索引,查询优化器可能仍然选择全表扫描;给太多列建联合索引,写入会变慢、占用空间。加索引前用 EXPLAIN ANALYZE 看实际执行计划,确认瓶颈在扫描、排序还是锁等待,再决定加什么。

现象、原因与第一步

现象真实原因第一步查什么
too many clients already每个请求新建池、池上限过大,或实例数超出数据库容量查 pg_stat_activity 的连接来源,核对实例数与池上限
请求长时间等待后超时池上限太小,连接被长事务或慢查询占住看应用侧池等待指标和数据库里正在执行的语句
converting NULL to string is unsupported列允许 NULL,Scan 目标是不可空类型核对表结构里的 NULL 约束,改用包装类型或指针
sql: no rows in result set查询没有匹配行,代码把正常分支当成系统错误确认是否用 errors.Is(err, sql.ErrNoRows) 单独处理
deadlock detected两个事务以相反顺序锁同一批行看错误码 40P01,检查事务内的更新顺序
迁移报 dirty上一次迁移中途失败,版本表记录了未完成状态看失败语句和当前结构,手工修复后再同步版本
列表接口越翻越慢深分页 OFFSET,或循环查询造成 N+1用 EXPLAIN ANALYZE 看计划,统计一次请求的 SQL 条数
context deadline exceeded查询超时、锁等待,或客户端提前断开看超时设置、慢查询日志和数据库锁等待视图
连接偶发 unexpected EOF连接被防火墙或数据库空闲切断,生命周期设置过长核对中间设备的空闲超时与 ConnMaxLifetime

边界与代价

连接池能限制并发,但不能消除排队。池越小,数据库越稳,应用侧等待越明显;池越大,吞吐上限提高,锁竞争和内存压力也上来。没有一组放之四海皆准的参数,只有「按数据库容量算上限、按实际并发调、用指标验证」这一条路。

事务不是免费的。每个打开的事务都占一条连接,长事务还会持有锁和旧版本数据,阻塞别人、拖慢清理。事务里只放必须原子执行的数据库操作,把网络调用、文件读写、消息发送移到事务外;如果必须一起成功,用本地消息表或补偿,而不是让数据库事务等外部系统。

重试会放大副作用。一个写请求失败后重试,如果第一次其实已经成功、只是响应丢了,就会产生两条记录。所以重试要配幂等键或唯一约束,读操作可以放心重试,写操作要先想清楚重复执行的后果。死锁重试也一样,重试的是整个事务,里面的每条写都可能再执行一次。

迁移工具不是备份。它能回退结构,不能恢复被删的数据;它能记录版本,不能保证每个环境的结构完全一致。生产变更前做备份、在预发环境演练、把迁移 SQL 当作代码评审,这三件事不能省。不确定的变更宁可拆小、分多次发布。

当天能自己验证的练习

  1. 启动一个 PostgreSQL 16 实例,用 sql.Open 创建一次 *sql.DB 并 PingContext,然后连续调用两次 sql.Open 不关闭,在 pg_stat_activity 里数连接数,观察差异。
  2. 把 SetMaxOpenConns 设为 1,并发发 10 个查询,记录每个请求的耗时;再调到 10,重复一次,对比等待时间而不是只看平均值。
  3. 建一张允许 NULL 的表,插入一行空值,分别 Scan 到 string 和 sql.NullString,记录两次的错误和结果。
  4. 开两个事务,按相反顺序更新同一组行,观察其中一个返回 40P01;给其中一个加统一顺序后重跑,确认死锁消失。
  5. 用 golang-migrate 建两版迁移,执行 up、down、再 up,查看版本表的变化;故意让一条 SQL 失败,观察 dirty 状态并记录修复步骤。

小结

三句话:sql.DB 是池,进程内只建一次,池上限按数据库容量和实例数倒推;查询要带上下文超时,NULL 和 ErrNoRows 都要显式处理;事务尽量短,死锁重试整个事务,迁移按扩展与收缩的顺序发布。

数据能稳定读写之后,下一个问题是「谁能读、谁能写」。下一篇从 JWT 过期导致前端无限 401、以及把用户塞进上下文用字符串 key 撞车开始,讲鉴权中间件、令牌校验、权限判断应该放在哪一层;数据访问决定请求能不能完成,鉴权决定请求该不该被允许。