本文详解 go 中 sqlite3“database is locked”错误的常见成因——特别是因未及时关闭查询结果集（*sql.rows）导致连接句柄泄漏和写锁滞留，并提供基于 defer rows.close() 的标准修复模式及最佳实践。
本文详解 go 中 sqlite3“database is locked”错误的常见成因——特别是因未及时关闭查询结果集（*sql.rows）导致连接句柄泄漏和写锁滞留，并提供基于 defer rows.close() 的标准修复模式及最佳实践。
在 Go 中使用 github.com/mattn/go-sqlite3 驱动操作 SQLite3 时，出现 database is locked 错误是高频问题。许多开发者误以为只要“只创建一个 *sql.DB 实例”并调用 database.Close() 就足够安全，却忽略了 SQLite3 的 序列化事务模型 与 Go database/sql 包中资源生命周期管理的关键细节。
核心问题在于：*未显式、及时关闭 sql.Rows 实例 **。
SQLite3 是文件级数据库，其写操作（如 INSERT、UPDATE、DELETE 或事务提交）需获取排他锁（EXCLUSIVE lock），而该锁会持续到所有关联的读操作（即未关闭的 rows）释放为止。即使你已调用 tx.Commit()，只要 rows 仍处于打开状态，底层连接就无法归还至连接池，且锁不会释放——这直接导致后续操作（尤其是写操作）被阻塞并最终超时抛出 database is locked。
观察你提供的代码片段：
func dosomething(database *sql.DB, tx *sql.Tx) error {rows, err := database.Query("select * from sometable where name=?", "some") if err != nil {return err} if rows.Next() { // …… scan logic} rows.Close() // ❌ 关闭位置靠后，且无错误处理 tx.Commit() // ⚠️ 此时 rows 可能尚未关闭，锁未释放！}此处 rows.Close() 被放在逻辑判断之后，若 rows.Next() 返回 false（无数据），或中间发生 panic，rows.Close() 将被跳过；更严重的是，它在 tx.Commit() 之后 执行，而事务提交依赖于底层连接空闲——形成死锁风险。
✅ 正确做法是：立即 defer 关闭 rows，确保其在函数退出前必被释放，无论执行路径如何：
func dosomething(database *sql.DB, tx *sql.Tx) error {rows, err := database.Query("SELECT * FROM sometable WHERE name = ?", "some") if err != nil {return err} defer rows.Close() // ✅ 紧随 Query 后 defer，强制保障释放 for rows.Next() {var id int var name string if err := rows.Scan(&id, &name); err != nil {return err} // 处理数据…… } // 检查 rows.Err() —— 遍历过程中可能发生的错误（如类型不匹配）if err := rows.Err(); err != nil {return err} // 此时 rows 已安全关闭，可安全提交事务 return tx.Commit()}⚠️ 补充关键注意事项：
- 永远检查 rows.Err()：rows.Next() 的循环结束后，必须调用 rows.Err() 判断遍历是否完整成功。未检查可能导致静默错误（例如部分行解析失败但程序继续）。
- 避免跨 goroutine 复用 rows：*sql.Rows 不是并发安全的，不可在多个 goroutine 中同时操作。
- 慎用 database.Query() 于事务内：若需在事务中执行查询，建议统一使用 tx.Query()（通过事务对象），以确保查询与事务绑定在同一连接上，避免连接竞争。
- 配置连接池参数（可选但推荐）：
database.SetMaxOpenConns(1) // SQLite3 单文件推荐设为 1，避免多连接争抢 database.SetMaxIdleConns(1) database.SetConnMaxLifetime(0) // SQLite3 无需连接过期
总结：Go 中 SQLite3 的 database is locked 本质是资源管理失当引发的锁竞争。解决之道不在于规避并发，而在于 严格遵循“创建即 defer 关闭”原则——对 *sql.Rows、*sql.Tx、甚至 *sql.Stmt 均应如此。将 defer rows.Close() 作为 database.Query() 或 tx.Query() 的强制配套语句，是编写健壮 SQLite3 Go 应用的第一道防线。
