本文详解 go 中使用 database/sql 操作 sqlite3 时出现“database is locked”错误的根本原因，重点指出未及时关闭 *sql.rows 导致连接句柄滞留、事务阻塞及锁竞争问题，并提供符合最佳实践的资源释放方案。
本文详解 go 中使用 database/sql 操作 sqlite3 时出现“database is locked”错误的根本原因，重点指出未及时关闭 *sql.rows 导致连接句柄滞留、事务阻塞及锁竞争问题，并提供符合最佳实践的资源释放方案。
在 Go 中通过 github.com/mattn/go-sqlite3 驱动操作 SQLite3 时，“database is locked”是高频且易被误解的错误。它 并非源于多线程并发写入同一数据库文件 （SQLite3 本身支持多线程安全访问），而更常因 资源未及时释放导致连接池中活跃句柄堆积、事务长期挂起或读写冲突 所致。
你提供的代码片段中存在一个关键隐患：rows.Close() 被显式调用在 rows.Next() 逻辑之后，但若 rows.Next() 返回 false（无数据）、或中间发生 panic、或后续插入逻辑出错提前 return，rows.Close() 就可能被跳过——这将使该查询持有的底层 SQLite 连接无法归还，进而阻塞后续操作（尤其是 tx.Commit() 所需的连接），最终触发锁等待超时。
✅ 正确做法是：始终使用 defer rows.Close() 紧随 Query 或 QueryRow 调用之后，确保无论函数如何退出，结果集都会被确定性关闭：
func dosomething(database *sql.DB, tx *sql.Tx) error {// ✅ 正确：defer 在声明后立即注册，保障执行 rows, err := database.Query("SELECT * FROM sometable WHERE name = ?", "some") if err != nil {return err} defer rows.Close() // ← 关键：此处确保关闭，不依赖执行路径 for rows.Next() {var id int var name string if err := rows.Scan(&id, &name); err != nil {return err} // 处理单行数据…… } // 检查 rows.Next() 循环后的潜在错误（如 I/O 错误）if err := rows.Err(); err != nil {return err} // 执行其他语句（INSERT/UPDATE）…… _, err = tx.Exec("INSERT INTO log (msg) VALUES (?)", "processed") if err != nil {return err} return tx.Commit()}⚠️ 同时需注意以下几点以彻底规避锁问题：
- 避免混合使用 *sql.DB 和 *sql.Tx 的查询：database.Query() 从连接池获取连接，而 tx.Query() 必须复用事务绑定的连接。混用可能导致事务连接被意外占用或提前释放。
- 事务生命周期应严格控制：Begin() 后必须明确 Commit() 或 Rollback()；建议使用 defer func(){if tx != nil { tx.Rollback() } }() 做兜底（注意判断 tx 是否已提交）。
- 合理配置连接池（对 SQLite3 可选但推荐）：
database.SetMaxOpenConns(1) // SQLite3 推荐设为 1，避免并发写冲突 database.SetMaxIdleConns(1) database.SetConnMaxLifetime(0) // SQLite3 无需连接过期 - 启用 WAL 模式提升并发读写能力（初始化时执行）：
_, _ = database.Exec("PRAGMA journal_mode = WAL")
总结：SQLite3 的“database is locked”在 Go 中绝大多数情况是 资源泄漏与事务管理失当的表象 。核心解决思路是—— 所有 *sql.Rows 必须 defer Close()，所有 *sql.Tx 必须有且仅有一次终态操作（Commit/Rollback），并避免跨事务边界复用连接。遵循这些原则，即可稳定驾驭 SQLite3 在 Go 应用中的嵌入式场景。
