结论:必须用database/sql+pgx/v5驱动,开发配sslmode=disable、生产配sslmode=require,sql.Open后立即db.Ping()验证连接,否则仅完成配置解析而未建TCP连接,后续操作才会暴露connection refused等错误。

直接说结论:用 database/sql + pgx/v5 驱动,连接字符串必须带 sslmode=disable(开发)或 sslmode=require(生产),初始化后立刻 db.Ping(),否则你以为连上了,其实只是配了个空壳。
sql.Open 为什么没报错却连不上?
因为 sql.Open 只是初始化驱动和连接池参数,不建任何 TCP 连接。你看到的 “成功” 其实只是配置解析通过了。
- 必须紧接着调
db.Ping()(或db.PingContext(ctx))来真实握手;漏掉这步,后续Query才会突然崩出connection refused或sql: database is closed - 在 Kubernetes 等环境里,
Ping失败常因 DNS 没就绪,加个简单重试(比如最多 3 次、间隔 1s)比等 readiness probe 更快见效 - 用
pgxpool.Pool时,Ping是从池里取一个连接测,比lib/pq更快返回真实状态
import _ "github.com/lib/pq" 报 unknown driver "postgres"?
不是驱动没装,是驱动注册失败——database/sql 本身不带 PostgreSQL 实现,必须靠驱动包的 init() 函数注册自己。
- 别用
import "github.com/lib/pq"(带名字引用),必须用import _ "github.com/lib/pq"(空白导入),否则init()不执行,sql.Open("postgres", ...)就找不到驱动 -
lib/pq已归档,官方推荐pgx/v5;如果选它,导入的是import _ "github.com/jackc/pgx/v5"(兼容database/sql)或import _ "github.com/jackc/pgx/v5/pgxpool"(直连池) - 驱动名固定是
"postgres",无论你用pgx还是lib/pq,sql.Open("postgres", ...)的第一个参数不能写成"pgx"或"pq"
Scan 时 panic: unsupported Scan, storing driver.Value type into type *string?
这是 NULL 值扫进非指针类型导致的典型 panic。PostgreSQL 的 NULL 在 Go 里不会自动转成零值,而是需要显式处理。
- 字段允许 NULL?一律用
sql.NullString、sql.NullInt64等,别用*string——后者为 NULL 时Scan收到的是nil,但期望的是非 nil 指针 - 确定非空且是 TEXT/VARCHAR?直接传
&myStr(string变量地址),不是&myStrPtr(*string的地址) - 更省心的做法:定义结构体,打上
pgx:"column_name"tag,再用row.ToStructByName(&s)(需pgx原生接口),它自动适配 NULL 和类型转换,比手写Scan少踩一半坑
事务里第二条语句就报 current transaction is aborted?
PostgreSQL 的事务一旦出错(比如唯一约束冲突、类型转换失败),整个事务就进 “aborted” 状态,后续所有命令都会被拒绝,直到你显式 ROLLBACK。
- 用
tx, err := db.Begin()后,**每一条**tx.Query、tx.Exec、tx.QueryRow都必须检查err != nil - 只要出错,立刻
tx.Rollback(),不能再继续跑下一条;否则就会卡在 aborted 状态,报那个经典错误 - 别混用
db.XXX和tx.XXX:事务内所有操作必须走tx对象,否则读不到一致性视图,还可能锁表错位 - 习惯性在
Begin()后加defer tx.Rollback(),再在成功路径末尾tx.Commit(),避免忘记 commit 导致连接长期卡在idle in transaction
真正容易被忽略的点是:连接字符串里的 sslmode 不是可选项,而是开关——不显式声明,PostgreSQL 默认要求 SSL,本地开发不加 sslmode=disable 就会卡住或静默失败;而生产环境不加 sslmode=require,等于把密码明文扔在路上。


















