在Golang后端中如何接入SQLite作为零配置本地元数据仓

Go连接SQLite必须用mattn/go-sqlite3驱动（需CGO和gcc），DSN示例：./meta.db?_foreign_keys=1&cache=shared&mode=rwc&_journal_mode=WAL&_busy_timeout=5000；建表主键用INTEGER PRIMARY KEY即可，勿加AUTOINCREMENT；事务须显式tx.Commit()；WAL模式提升并发读写。

SQLite 在 Go 中不需要安装服务，但必须显式打开数据库文件

Go 本身不内置 SQLite 支持，得靠 github.com/mattn/go-sqlite3 这个 CGO 驱动。它不是纯 Go 实现，编译时需要本地有 C 编译器（如 gcc 或 clang），否则会报错：exec: "gcc": executable file not found in $PATH。Windows 用户尤其容易卡在这步——即使装了 MinGW，也要确保 gcc 在环境变量里，且 Go 构建时没禁用 CGO（CGO_ENABLED=1）。

初始化连接最简写法是：

db, err := sql.Open("sqlite3", "./meta.db?_foreign_keys=1&cache=shared&mode=rwc")

注意三点：

• mode=rwc 表示读写创建，比默认的 mode=rw 更稳妥，避免首次运行因目录不存在或权限不足而静默失败
• _foreign_keys=1 必须显式开启外键约束，SQLite 默认关着，不然 FOREIGN KEY 定义形同虚设
• cache=shared 允许多连接共享页缓存，对并发读写有实际帮助，尤其在多 goroutine 操作同一 DB 文件时

用 sql.Exec 建表时，主键自增字段别写 AUTOINCREMENT

SQLite 的 INTEGER PRIMARY KEY 本身就隐含自增行为；加上 AUTOINCREMENT 反而会多一层额外计数器维护，导致性能略降、且无法复用已删除的 rowid。日常元数据场景完全没必要。

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

典型错误写法：

CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)

推荐写法：

CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)

如果你确实需要严格单调递增（比如审计日志序号），再考虑 AUTOINCREMENT；但绝大多数配置项、任务记录、版本快照类元数据，用裸 PRIMARY KEY 足够。

另外，SQLite 不支持 ALTER COLUMN，字段类型变更只能靠重建表。建议初期就定好字段类型：文本统一用 TEXT（别用 VARCHAR(255)，SQLite 不校验长度），数值优先用 INTEGER 或 REAL，避免后期迁移麻烦。

事务提交前务必调用 tx.Commit()，否则数据不落盘

SQLite 是文件级持久化，但 Go 的 *sql.Tx 默认延迟写入。常见误区是开了事务、执行了 tx.Exec、然后直接 return 或 panic，忘了 tx.Commit() —— 此时数据只在内存 WAL 日志里，进程退出后全丢。

正确模式是：

tx, err := db.Begin()if err != nil {    return err}_, err = tx.Exec("INSERT INTO ...", ...)if err != nil {    tx.Rollback() // 记得回滚    return err}return tx.Commit() // 关键：必须显式 commit

更安全的做法是用 defer tx.Rollback() 配合提前 return，但要注意：一旦 Commit() 成功，再调 Rollback() 会报错 sql: Transaction has already been committed or rolled back。所以最佳实践是 commit 后立即将 tx 置为 nil，避免误操作。

并发读写同一个 SQLite 文件时，写操作会阻塞所有读

SQLite 的 WAL 模式能缓解这个问题，但默认是 DELETE 模式。启动时必须加 journal_mode=WAL 参数，否则高频率写入（比如每秒多次更新配置）会导致读请求卡住甚至超时。

完整推荐 DSN 示例：

./meta.db?_foreign_keys=1&cache=shared&mode=rwc&_journal_mode=WAL&_busy_timeout=5000

其中 _busy_timeout=5000 表示写锁等待上限 5 秒，避免无限阻塞；WAL 模式下读写可并行，但注意：WAL 文件（meta.db-wal 和 meta.db-shm）必须和主库在同一文件系统，跨 NFS 或某些容器挂载方式可能出问题。

如果应用部署在无状态容器里，且元数据只是临时缓存，可以接受重启丢失，那 SQLite 很合适；但如果要求强一致性或多实例共享，就得换 PostgreSQL 或 etcd —— SQLite 的并发模型本质是单写多读，不是分布式方案。