Golang如何使用SQLite嵌入式数据库

在Go中使用SQLite嵌入式数据库远不止简单调用sql.Open——必须启用CGO、正确导入驱动、用绝对路径初始化数据库文件、手动创建父目录，并在db.Ping()成功后立即配置WAL模式、外键、忙等待超时和UTF-8编码等关键PRAGMA，否则90%的“连不上”“锁表”“外键失效”“中文乱码”问题将悄然而至；事务操作必须全程使用tx对象，混用db方法将彻底破坏一致性；真正可靠的连接始于db.Ping()，而稳健的并发与数据完整性，全系于那几行看似可选实则不可或缺的PRAGMA设置。

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

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

go-sqlite3 是基于 C 的驱动，CGO_ENABLED=1 不只是建议，是硬性前提。Alpine 容器、CI 环境、禁用 CGO 的构建都会直接报 undefined reference to 'sqlite3_open_v2'。

• macOS：装完 brew install sqlite3 后，确保 PKG_CONFIG_PATH 指向正确（比如 /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()；写成 import sqlite3 "github.com/mattn/go-sqlite3" 或漏掉导入，sql.Open 会返回 unknown driver "sqlite3"

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

sql.Open 只是初始化连接池对象，哪怕 DSN 写成 "sqlite3", "xxx://invalid" 也不会 panic。真正校验路径、权限、磁盘空间、文件系统支持，全靠第一次 db.Ping()。

• 常见错误现象：unable to open database file（目录不存在或无写权限）、no such table（其实是 DB 文件根本没创建成功）、disk I/O error（挂载点只读或满）
• 路径务必用绝对路径或显式拼接：filepath.Join(os.TempDir(), "app.db")，避免 "./data.db" 在不同工作目录下失效
• 目录必须手动创建：os.MkdirAll(filepath.Dir(dbPath), 0755)，SQLite 驱动不会帮你建父目录
• 外键、WAL、UTF-8 这些关键行为，都得在 db.Ping() 成功后立刻执行 db.Exec("PRAGMA ...")，否则可能不生效

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

开了 tx, _ := db.Begin()，却在事务体里继续调 db.Query("SELECT ...")，查到的是快照数据，不受事务隔离保护，回滚后也看不出变化——这不是 bug，是设计如此。

• 所有语句必须用 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")，否则 FOREIGN KEY 语法被忽略
• 忙等待超时：_, _ = db.Exec("PRAGMA busy_timeout = 5000")（毫秒），避免短时锁直接报错
• 字符编码：_, _ = db.Exec("PRAGMA encoding = 'UTF-8'")，尤其 Windows 下防止中文变 ???
• 这些 PRAGMA 必须在建表前执行，且每个新连接都要重设；连接池中复用连接时，靠 db.SetConnMaxLifetime + 自定义 init 函数兜底

最常被跳过的一步，是以为 sql.Open 返回非 nil 就万事大吉；其实 db.Ping() 才是真实世界的第一道门，而 PRAGMA 设置决定了这扇门后面能不能跑起来。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~