SetMaxOpenConns必须按TiDB实际max_connections(即MAX_SESSIONS)设置,如返回100则建议设60~80;SetConnMaxLifetime须设2~3分钟防connection reset;GORM v2中需用db.Session().Ping()做健康检查,且须显式处理JSON/ENUM类型及乐观事务重试。

SetMaxOpenConns 必须按 TiDB 实际 SESSIONS 限制来设,不能套 MySQL 经验
TiDB 默认 MAX_SESSIONS 是 100(部分版本甚至更低),远低于常见 MySQL 的 200+。直接沿用 MySQL 的“60%~80%”经验(比如设 160)会导致 Too many connections 报错,且错误常在高并发时集中爆发。
实操建议:
- 先查 TiDB 实际上限:
SHOW VARIABLES LIKE 'max_connections';或SELECT @@global.max_connections;(注意:TiDB 中该变量实际反映的是MAX_SESSIONS) - 若返回 100,则
SetMaxOpenConns建议设为 60~80;若集群启用了tidb_max_tso_wait_time或开启了热点调度,留更多余量(如 50)更稳妥 - 云托管 TiDB(如阿里云 PolarDB-X 兼容版、TiDB Cloud)需查控制台配额,有些实例默认仅 50 可用会话
SetConnMaxLifetime 必须设为 2~3 分钟,否则云环境必现 connection reset
TiDB 的 PD 调度和 TiKV Region 迁移可能在无感知下切断空闲连接;云厂商 NAT 网关或 SLB 通常 3 分钟自动回收空闲 TCP 连接。不设 SetConnMaxLifetime,或设成 time.Hour,会让连接池长期持有已断开的句柄,复用时直接报 read: connection reset by peer。
实操建议:
-
sqlDB.SetConnMaxLifetime(time.Minute * 2)是生产推荐值;自建离线集群可放宽至 5 分钟,但不建议超过 - 必须与
SetMaxIdleConns配对设置:后者设为前者的 1/2~2/3(例如最大 80 → 空闲 30~50) - 别依赖
SetConnMaxIdleTime单独保活——TiDB 不支持服务端 idle timeout 主动通知,客户端主动淘汰更可靠
GORM v2 中 db.Ping() 已废弃,必须用 Session().Ping()
db.Ping() 在 GORM v2.2.0+ 中已被移除,但很多文档没更新。若仍调用,编译不报错但运行时静默失败,首请求仍会卡住并 panic,表现为服务启动后首次 API 调用超时或 500。
实操建议:
- 正确写法:
if err := db.Session(&gorm.Session{}).Ping(); err != nil { log.Fatal("DB health check failed:", err) } - 务必放在
gorm.Open()之后、服务正式 Accept 请求之前,否则等于没验 - 建议封装为启动检查函数,配合
context.WithTimeout控制最长等待(如 5 秒),避免阻塞整个初始化流程
TiDB 特有字段(JSON/ENUM)在 GORM 中需显式注册 Scan 方法
TiDB 支持 JSON 和 ENUM 类型,但 GORM 默认无法自动解析到 Go struct 字段。不处理会导致查询时 panic 或字段为空,尤其在 Preload 关联查询中容易漏掉。
实操建议:
- 对
JSON字段,定义自定义类型并实现Scanner/Valuer接口,例如:type JSONB map[string]interface{} - 对
ENUM,避免用字符串直存;改用int+iota枚举,并在模型中加gorm:columnType:enum('a','b')标签 - 批量插入禁用
ON DUPLICATE KEY UPDATE:TiDB 对该语法支持不稳定,v6.5 前版本可能降级为单条执行,建议改用INSERT IGNORE或应用层 upsert 控制
最易被忽略的一点:TiDB 的事务模型是乐观锁 + TSO 时间戳,GORM 默认的 Save 或 Update 不带重试逻辑。遇到 WriteConflict 错误时不会自动重试,业务侧需捕获 IsRetryableError 并手动重试——这点和 MySQL 完全不同。


















