Gin实战

Go 报错 sql: database is closed 怎么解决?连接池生命周期与并发复用的三大排查路径

报错现场

线上接口偶发这个错误,本地却怎么也复现不出来:

sql: database is closed

它的高发场景有三个:在 HTTP handler 或业务函数里写了 defer db.Close();服务优雅退出时先关了连接池再处理在途请求;测试清理逻辑把共享的连接池提前关闭。本文先讲清 *sql.DB 的关闭语义,再逐个场景给出修复代码,最后附一份排查清单。

一、原理:*sql.DB 是连接池,Close 关的是整个池

sql.Open() 返回的 *sql.DB 不是一条连接,而是一个连接池:它内部维护空闲连接队列,每次 Query/Exec 借一条连接、用完归还。因此两条语义必须记牢(来自 database/sql 官方文档):

  1. Close() 阻止新查询启动——此后所有操作立即返回 sql: database is closed(即 sql.ErrDBClosed);
  2. Close() 会等待已启动的查询在服务端执行完毕后返回——所以正在跑的请求不会被打断,但请求里如果再发起第二次查询,就会撞上 ErrDBClosed。

这就解释了这个报错最常见的成因:一个请求处理中有人把池关了。第一个查询还正常,后续的写入/查询全部报错;并发稍高一点,报错就呈「偶发」形态,极难排查。

二、场景一:请求里 defer db.Close()(最经典反例)

有人沿用「打开资源就用 defer 关」的习惯,在 handler 或 DAO 方法里写:

// ❌ 反例:每个请求都把整个连接池关掉
func (h *Handler) GetUser(c *gin.Context) {
	db, _ := sql.Open("mysql", dsn) // 或者从包级变量拿 db
	defer db.Close()                // 第二个请求进来:sql: database is closed
	// ... 查询逻辑
}

即使 db 是包级单例,这条 defer db.Close() 也是灾难:第一个请求结束时整个池被关闭,第二个请求的所有查询全部报错;如果库里有多条连接在途,报错还会和「正常返回」交错出现。

修复:*sql.DB 与进程同生命周期,只打开一次、只在 main 退出时关一次,业务层任何位置都不允许调用 Close:

// ✅ 正例:池由 main 持有,逐层注入,禁止下层 Close
func main() {
	db, err := sql.Open("mysql", dsn)
	if err != nil {
		log.Fatal(err)
	}
	// 池参数按业务压测设置,而不是靠默认值碰运气
	db.SetMaxOpenConns(50)
	db.SetMaxIdleConns(10)
	db.SetConnMaxLifetime(time.Hour)
	defer db.Close() // 整个进程唯一的一处 Close

	svc := service.New(db)      // 注入给 service
	r := gin.Default()
	r.GET("/user", handler.GetUser(svc))
	// ...
}

三、场景二:优雅退出顺序错了

Kubernetes 滚动更新、进程收到 SIGTERM 时,如果处理顺序是「先 db.Close() 再停 HTTP 服务」,在途请求就会大面积撞上 ErrDBClosed。正确顺序是先停流量,再清资源:

// ✅ 先 Shutdown 停止接收新请求并等待在途请求完成,最后才关池
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil { // 1. 停 HTTP:拒绝新连接,等在途请求
	log.Printf("server shutdown: %v", err)
}
db.Close() // 2. 此时已无在途查询,安全关闭连接池

注意 srv.Shutdown 内部的等待有上限(上面给了 10 秒),在途请求超时后仍会被强杀,这时 db.Close() 的「等待在途完成」语义已经无碍——池内残留连接由 Close 统一回收。

四、场景三:事务与 Rows 的连带坑

还有两个容易被误认为「池被关了」的兄弟报错:

报错 真实原因 修复
sql: transaction has already been committed or rolled back Commit/Rollback 之后又用旧 tx 执行语句 事务对象用后即弃,后续操作开新事务
sql: database is closed 且只在高峰期出现 rows.Next() 没走完、或忘记 rows.Close(),连接被泄漏,池耗尽后新请求拿不到连接而超时/报错(不同驱动报错各异) 用 defer rows.Close();扫描完再判断
driver: bad connection 拿到的是已被服务端断开的空闲连接(如 wait_timeout) 设 SetConnMaxLifetime 小于数据库的闲置超时

最后一个值得展开:defer rows.Close() 的位置。常见错误是写成「拿到 rows 后先判断 err 再 defer」,err 非空时 rows 为 nil 会 panic;正确姿势是查完 err 再 defer:

rows, err := db.QueryContext(ctx, "SELECT id, name FROM user")
if err != nil {
	return err
}
defer rows.Close() // 必须在 err 检查之后

for rows.Next() {
	var u User
	if err := rows.Scan(&u.ID, &u.Name); err != nil {
		return err
	}
	// 处理 u
}
return rows.Err() // 别漏:循环正常结束也可能有错误

五、零依赖复现:亲眼看一次报错产生

下面的程序只用标准库就能复现 sql: database is closed——注册一个不真正连库的 dummy driver,关闭池后再查询即可(Query 在触碰 driver 之前就会返回 ErrDBClosed):

package main

import (
	"database/sql"
	"database/sql/driver"
	"errors"
	"fmt"
)

// dummyDriver 不建立真实连接,只为演示池关闭后的错误语义
type dummyDriver struct{}

func (dummyDriver) Open(string) (driver.Conn, error) {
	return nil, errors.New("dummy driver: no real connection")
}

func main() {
	sql.Register("dummy", dummyDriver{})
	db, _ := sql.Open("dummy", "")
	defer db.Close()

	// 先正常关闭池
	if err := db.Close(); err != nil {
		panic(err)
	}

	// 再查询:池已关闭,直接返回 sql.ErrDBClosed,不会触及 driver
	_, err := db.Query("SELECT 1")
	fmt.Println("原始报错:", err)

	// 正确姿势:用 errors.Is 判断,不要字符串比对
	if errors.Is(err, sql.ErrDBClosed) {
		fmt.Println("确认是: 连接池已关闭")
	}
}

输出:

原始报错: sql: database is closed
确认是: 连接池已关闭

errors.Is 而不是 err.Error() == "sql: database is closed"——后者在驱动包装错误、或 Go 版本调整错误措辞时会误判。

六、排查清单

线上遇到这个报错,按顺序查:

步骤 动作 怀疑对象
1 grep -rn "\.Close()" --include="*.go" 排除 server/rows/tx,只看 db.Close 除 main 外任何 db.Close 调用都是头号嫌疑
2 确认 sql.Open 的调用次数 每请求 Open 一个新池也是性能炸弹
3 查优雅退出代码顺序 db.Close 早于 srv.Shutdown 即顺序错误
4 查测试代码的 t.Cleanup/defer 顺序 测试提前关池,串行用例第二个开始全挂
5 用 errors.Is(err, sql.ErrDBClosed) 打点日志 区分「池关了」与「事务用完」「连接泄漏」

七、预防规范

  1. db.Close 全仓库只允许出现在 main:加一条 code review checklist,看到业务层 db.Close 直接打回;
  2. *sql.DB 全局单例、构造一次:用依赖注入下传,不要每请求 sql.Open(sql.Open 本身不建连,但它每次新建一个池);
  3. 退出顺序固化:先 srv.Shutdown(带超时)→ 再 db.Close → 最后退进程,写进服务模板;
  4. Rows 三件套:err 检查后 defer rows.Close()、rows.Next() 循环、return rows.Err(),缺一件都可能是连接泄漏的种子。

版本说明

本文基于 Go 1.27.4(2026-11-16 核对,go.dev/dl/?mode=json 最新稳定版)编写,示例代码仅使用标准库(database/sql、net/http、os/signal、errors),零第三方依赖,可直接 go run;文中关于 Close 等待在途查询、ErrDBClosed 等语义均出自 database/sql 官方文档与标准库实现。


相关阅读:《Go 报错 import cycle not allowed 怎么解决?循环依赖的三大修复方案与包分层规范》 · 《Go 报错 too many open files 怎么解决?文件句柄泄漏排查定位》 · 《GORM 数据库连接与连接池配置》

🛒 站长推荐(京东联盟)

以上链接含京东联盟推广代码;通过链接购买本站可能获得少量佣金,不影响你的购买价格。

📮 关注公众号「Go2AI之路」
Go2AI之路 公众号二维码

每周更新 Go + AI 应用开发实战:AI 面试官完整项目、MCP、Agent 工程化,完整源码随文章首发。

微信扫码,或搜索「Go2AI之路」关注,第一时间获取系列更新与源码,不再错过任何一篇。

wx

关注公众号

©2017-2026 鲁ICP备17023316号-1 Powered by Hugo · 隐私政策