Go database/sql TxOptions ReadOnly 如何传递只读意图

在 Go 里把查询事务标成只读，入口不是给 SQL 字符串加注释，而是把 sql.TxOptions.ReadOnly 设为 true 后交给 DB.BeginTx。这个布尔值能否变成数据库会话的只读属性，取决于底层驱动是否实现 driver.ConnBeginTx：支持时由驱动设置只读事务，不支持时 database/sql 会直接返回错误，而不是悄悄把请求当成普通事务。

只读意图的传递链是 DB.BeginTx → database/sql → driver.ConnBeginTx.BeginTx → 数据库驱动。应用层只负责表达意图，最终是否执行只读约束由驱动和数据库能力决定。

先把 TxOptions.ReadOnly 的输入边界写对

ReadOnly 是事务创建参数，不是对某一条 SELECT 的提示。实际代码应从 BeginTx 开始，并为失败路径保留回滚；即使当前事务只读，也不要省略结束事务的动作，因为事务仍然占用连接。

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

// ReadOnly 表达“这个事务不应写入”的意图，Isolation=0 使用驱动默认级别。
tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
if err != nil {
	// 驱动不支持只读事务时，这里会收到明确错误，不能把它当成普通查询继续。
	return fmt.Errorf("begin read-only tx: %w", err)
}
defer tx.Rollback() // Commit 成功后 Rollback 只会返回已完成状态，可安全兜底。

var total int
if err := tx.QueryRowContext(ctx,
	"SELECT COUNT(*) FROM orders WHERE status = ?", "pending").Scan(&total); err != nil {
	return fmt.Errorf("count pending orders: %w", err)
}
if err := tx.Commit(); err != nil {
	return fmt.Errorf("finish read-only tx: %w", err)
}
return nil

这里的“只读”不是编译器对 SQL 的静态检查。应用仍可能构造出写语句，真正的拒绝动作要看驱动有没有把该属性传给数据库。因此，ReadOnly 更适合被当作连接会话的能力协商，而不是 SQL 审计替代品。

database/sql 如何把只读意图交给驱动

标准库内部创建事务时会先判断底层连接是否实现 driver.ConnBeginTx。如果实现了，sql.TxOptions 的隔离级别转换成 driver.IsolationLevel，ReadOnly 原样复制到 driver.TxOptions，再调用驱动的 BeginTx。

因此排查时要看“驱动连接接口”这一层，而不是只看业务代码里是否写了 true。这条边界可以概括为：

三种结果要分开判断，不要只看 BeginTx 是否成功

第一种是驱动支持只读事务，并把属性转换成数据库方言或会话设置，创建成功后查询可以继续。第二种是驱动明确返回不支持错误，应用可以降级为普通事务，但必须把这个选择写进策略，不能默默降级。第三种是调用方根本没有把 ReadOnly 设为 true，这属于输入缺失，和“驱动支持但数据库拒绝”不是一回事。

建议在适配层统一判断错误并记录驱动名、事务用途和降级策略；不要把所有 BeginTx 错误都改写成“数据库连接失败”。如果使用固定驱动，进一步查看它的事务选项文档，确认只读属性对应的是数据库级只读事务、会话变量，还是仅用于路由。

常见问题

ReadOnly=true 能阻止所有写 SQL 吗？

不能直接这样保证。它首先是传给驱动的事务属性；驱动和数据库是否拒绝写入、拒绝到什么粒度，需要看具体实现。

为什么我的驱动返回不支持只读事务？

常见原因是驱动没有实现 driver.ConnBeginTx，标准库无法安全地把只读意图交给旧式 Begin 接口，所以选择报错而不是静默丢失约束。

只读事务还需要 Commit 或 Rollback 吗？

需要。事务结束后连接才会回到连接池；用 defer tx.Rollback() 做兜底，再在成功路径显式 Commit，可以覆盖查询失败和上下文取消。