SQLite 在 Go 中的正确使用指南：CGO 与连接验证是关键
核心结论：在 Go 语言中使用 SQLite 数据库是完全可行的，但整个流程中存在几个决定成败的关键环节。其中，启用 CGO 是基础前提，而 `db.Ping()` 方法是验证数据库连接是否成功的真正试金石。如果跳过这两步直接进行数据操作，90% 以上的连接异常问题都会随之而来。
CGO 启用与驱动导入必须同步完成
由于 go-sqlite3 驱动基于 C 语言库，因此编译时设置 `CGO_ENABLED=1` 不是可选项，而是强制要求。在 Alpine 容器、某些 CI/CD 环境或全局禁用了 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语言免费学习笔记（深入）”；
- 统一操作对象：事务内的所有 SQL 语句，都必须使用 `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 设置，则决定了门后的系统能否稳健、高效地运行起来。
