golang如何使用SQLite嵌入式数据库_golang SQLite嵌入式数据库使用方法

能用，但必须过 CGO 这关；不检查 `db.Ping()` 就开干，90% 的“连不上”问题都在这儿暴露

先说一个核心判断：在 Go 里用 SQLite，技术上完全可行，但整个流程里藏着几个“一票否决”的关键环节。其中，CGO 是入场券，而 `db.Ping()` 则是连接成功与否的真正试金石。跳过这两步直接操作，90% 的诡异连接问题都会找上门。

CGO 启用和驱动导入必须同步做

go-sqlite3 驱动基于 C 库，这意味着 `CGO_ENABLED=1` 不是可选项，而是硬性前提。在 Alpine 容器、某些 CI 环境，或者全局禁用了 CGO 的构建脚本里，你会直接撞上 `undefined reference to 'sqlite3_open_v2'` 这类编译错误。

• macOS：用 Homebrew 安装 `sqlite3` 后，关键是要确保 `PKG_CONFIG_PATH` 环境变量指向正确的 pkgconfig 目录（例如 `/opt/homebrew/lib/pkgconfig`），否则编译器可能找不到库文件。
• Linux（Debian/Ubuntu）：务必执行 `sudo apt install libsqlite3-dev`。只安装 `sqlite3` 命令行工具是不够的，开发头文件同样不可或缺。
• Windows（MSVC）：必须显式设置 `CGO_ENABLED=1`。如果忘记，`sql.Open("sqlite3", ...)` 时会直接 panic。
• 导入写法：必须是 `import _ "github.com/mattn/go-sqlite3"`。这个下划线前缀至关重要，它会触发驱动的 `init()` 注册函数。如果写成具名导入或者漏掉导入，`sql.Open` 时会返回 `unknown driver "sqlite3"` 错误。

`sql.Open` 不等于连接成功，`db.Ping()` 才是第一道门槛

这里有个常见的误解：`sql.Open` 返回了数据库对象，就代表连接成功了。其实不然，`sql.Open` 仅仅是初始化了一个连接池对象，即使你给一个完全无效的 DSN（比如 `"xxx://invalid"`），它也不会立即报错。真正的校验工作——检查文件路径是否存在、是否有读写权限、磁盘空间是否充足、文件系统是否支持——全都发生在第一次调用 `db.Ping()` 的时候。

• 典型错误：`unable to open database file`（目录不存在或无写权限）、`no such table`（背后可能是数据库文件根本没创建成功）、`disk I/O error`（挂载点只读或磁盘已满）。
• 路径处理：务必使用绝对路径，或者通过 `filepath.Join(os.TempDir(), "app.db")` 等方式显式拼接。避免使用 `"./data.db"` 这种相对路径，否则程序工作目录一变，连接就失效。
• 目录创建：SQLite 驱动不会自动创建不存在的父目录。因此，必须先执行 `os.MkdirAll(filepath.Dir(dbPath), 0755)` 来确保目录存在。
• 关键配置时机：外键、WAL 模式、UTF-8 编码这些关键 PRAGMA 设置，都必须在 `db.Ping()` 成功之后、执行任何业务操作之前，立刻通过 `db.Exec("PRAGMA ...")` 来设置，否则可能无法生效。

事务里所有操作必须走 `tx` 对象，混用 `db.Query` 就等于没事务

开启一个事务 `tx, _ := db.Begin()` 后，如果在事务体内继续调用 `db.Query("SELECT ...")`，会发生什么？你查到的数据将是数据库的快照，不受当前事务的隔离级别保护，事务回滚后这些查询也看不到变化——这并非 Bug，而是 SQLite 事务机制的设计如此。

立即学习“go语言免费学习笔记（深入）”；

• 统一操作对象：事务内的所有语句，都必须使用 `tx.Query`、`tx.Exec`、`tx.Prepare`，绝不能穿插使用 `db.*` 方法。
• 避免交叉调用：尽量不要在同一个事务里混合使用 `tx.QueryRow` 和 `tx.Exec`，在某些 SQLite 版本中，这可能导致静默失败或死锁。
• 显式提交与回滚：`tx.Commit()` 和 `tx.Rollback()` 都必须被显式调用。使用 `defer tx.Rollback()` 时，要加上 `if tx != nil` 的判断，否则在事务创建失败时可能引发 panic。
• 强一致性写入：当需要强一致性保证时，可以使用 `db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelExclusive})` 来开启事务。默认的 `DEFERRED` 模式是在首次读写时才加锁。

PRAGMA 设置不是可选项，是并发和数据一致性的基础配置

SQLite 出厂默认配置（`DELETE` 日志模式、外键关闭、编码未强制指定）并不适合生产环境。如果不做 PRAGMA 初始化，高并发场景下大概率会遇到 `database is locked`，外键约束也会形同虚设。

• WAL 模式：执行 `_, _ = db.Exec("PRAGMA journal_mode = WAL")`。这是支持读写并行的关键，能极大缓解多 goroutine 写入时的阻塞问题。
• 外键约束：执行 `_, _ = db.Exec("PRAGMA foreign_keys = ON")`。否则，你在 DDL 中定义的 `FOREIGN KEY` 语法将被静默忽略。
• 忙等待超时：执行 `_, _ = db.Exec("PRAGMA busy_timeout = 5000")`（单位毫秒）。这可以避免数据库短暂锁定时直接返回错误，而是重试一段时间。
• 字符编码：执行 `_, _ = db.Exec("PRAGMA encoding = 'UTF-8'")`。这对于确保数据，尤其是中文等非 ASCII 字符的正确存储至关重要，特别是在 Windows 环境下。
• 执行时机与连接管理：这些 PRAGMA 必须在建表之前执行，并且每个新的数据库连接都需要重新设置。当使用连接池时，可以通过设置合理的 `db.SetConnMaxLifetime` 并结合自定义的连接初始化函数来确保配置生效。

总而言之，最容易被忽略的一步，就是误以为 `sql.Open` 返回非 nil 对象就万事大吉。实际上，`db.Ping()` 才是通往真实数据库世界的第一道安检门，而紧随其后的 PRAGMA 设置，则决定了门后的系统能否稳健、高效地跑起来。