go-sqlite3 完全指南Go 语言 SQLite3 驱动的 DSN 配置、构建标签与用户认证实战【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost导读本文以当前仓库中 vendored 的github.com/mattn/go-sqlite3版本 v1.14.22见 go.mod官方 README 为骨架系统讲解这个符合 Go 标准库database/sql接口的 SQLite3 驱动从安装前提、DSN 连接串的全部参数、按构建标签裁剪特性的机制到编译跨平台产物与 SQLite 用户认证模块的完整用法。读完本文你将能够独立配置 go-sqlite3 的各类连接参数、按需开启 FTS5/ICU/JSON 等扩展并在项目中落地带用户认证的 SQLite 数据库同时可以看到该驱动在 nhost 项目 Constellation SQL 连接器中的真实接入方式sqlite.go。一、驱动概览一个符合 database/sql 接口的 SQLite3 驱动go-sqlite3 是一个符合 Go 内置database/sql接口的 SQLite3 驱动。这意味着你可以通过标准库database/sql的sql.Open、sql.DB、sql.Tx等抽象来使用它无需引入非标准的数据访问 API上层代码也因此可以无缝替换为其他驱动。需要特别注意的是该包是cgo 包构建依赖gcc编译器与CGO_ENABLED1环境变量版本语义上最新稳定版本是 v1.14 及之后而非 v2。README 明确说明 v2 版本号的提升是一次意外事故其中并无重大变更或新特性项目遵循官方 Golang Release Policy支持的具体 Go 版本范围以仓库 CI 配置为准。在 nhost 仓库中该依赖被锁定为v1.14.22见 go.mod与稳定版本是 v1.14 系列的声明一致。二、安装与构建前提使用go get即可安装go get github.com/mattn/go-sqlite3由于 go-sqlite3 是cgo 包构建你的应用需要系统中有gcc。不过一旦你使用go install github.com/mattn/go-sqlite3此步需要 gcc完成构建安装后续构建你的应用就不再需要依赖 gcc。重要提醒因为这是启用CGO的包你必须设置环境变量CGO_ENABLED1并确保gcc编译器位于 PATH 中否则会报错或静默回退到不可用的构建路径。三、Connection StringDSN连接串全解析创建新的 SQLite 数据库或连接已有数据库时除了文件名还可以追加额外选项这串参数即 DSNData Source Name数据源名称。3.1 DSN 基本格式选项追加在 SQLite 数据库文件名之后文件名与选项之间用?问号分隔选项应做 URL 编码对应 Go 标准库net/url的QueryEscape该规则同样适用于内存数据库in-memory database选项格式为KEYWORDVALUE多个选项之间用连接该库既支持 SQLite 自身提供的 DSN 选项也提供了一批额外的私有选项。布尔值的合法写法有两种集合假值0、no、false、off真值1、yes、true、on3.2 DSN 选项完整参数表名称键Key取值Value说明UA - 创建_auth-启用用户认证并创建数据库详见第六章UA - 用户名_auth_userstring用户认证的用户名UA - 密码_auth_passstring用户认证的密码UA - 加密方式_auth_cryptSHA1、SSHA1、SHA256、SSHA256、SHA384、SSHA384、SHA512、SSHA512用户认证使用的密码编码器UA - 盐_auth_saltstring当所选密码编码器需要盐salt时使用自动清理_auto_vacuum/_vacuum0/none、1/full、2/incremental对应 SQLite 的PRAGMA auto_vacuum忙等待超时_busy_timeout/_timeoutint指定sqlite3_busy_timeout的值对应PRAGMA busy_timeout区分大小写 LIKE_case_sensitive_like/_cslikeboolean对应PRAGMA case_sensitive_like延迟外键_defer_foreign_keys/_defer_fkboolean对应PRAGMA defer_foreign_keys外键约束_foreign_keys/_fkboolean对应PRAGMA foreign_keys忽略 CHECK 约束_ignore_check_constraintsboolean对应PRAGMA ignore_check_constraints不可变immutableboolean对应 SQLite 打开标志中的 Immutable 选项日志模式_journal_mode/_journalDELETE、TRUNCATE、PERSIST、MEMORY、WAL、OFF对应PRAGMA journal_mode锁定模式_locking_mode/_lockingNORMAL、EXCLUSIVE对应PRAGMA locking_mode访问模式modero、rw、rwc、memory数据库访问模式对应 SQLite Open 标志互斥锁_mutexno、full指定互斥模式只查询_query_onlyboolean对应PRAGMA query_only递归触发器_recursive_triggers/_rtboolean对应PRAGMA recursive_triggers安全删除_secure_deleteboolean/FAST对应PRAGMA secure_delete共享缓存cacheshared、private设置缓存模式shared-cache同步级别_synchronous/_sync0/OFF、1/NORMAL、2/FULL、3/EXTRA对应PRAGMA synchronous时区位置_locauto指定时间格式的时区位置事务锁_txlockimmediate、deferred、exclusive指定事务的锁定行为可写 Schema_writable_schemaboolean开启后SQLITE_MASTER表可用普通 UPDATE/INSERT/DELETE 修改警告滥用该选项极易损坏数据库文件缓存大小_cache_sizeint最大缓存大小默认 2000K2M对应PRAGMA cache_size这些参数的解析逻辑可以在驱动的 DSN 解析源码中直接看到sqlite3.go例如_loc的时区解析、_txlock的事务锁映射、_journal_mode/_locking_mode的 PRAGMA 透传、_auth*系列的用户认证参数读取等均有对应的params.Get(...)分支与错误处理。3.3 DSN 示例file:test.db?cachesharedmodememory该示例同时指定了共享缓存cacheshared与内存访问模式modememory是构造多连接共享同一内存数据库的经典写法详见第七章 FAQ 中:memory:的讨论。四、特性Features与构建标签该包允许通过 Go 的构建约束build tags又称构建标签来启用或禁用 SQLite3 内可用的各项特性。4.1 使用方式如需携带额外扩展/特性构建该库使用如下命令go build -tags FEATURE可用的特性见下方扩展列表。使用多个构建标签时标签之间以空格分隔例如go build -tags icu json1 fts5 secure_delete4.2 特性 / 扩展完整列表扩展构建标签说明附加统计信息sqlite_stat4为 ANALYZE 命令与查询规划器增加额外逻辑从每个索引的全部列收集直方图数据存入sqlite_stat4表帮助 SQLite 在特定场景下选择更优查询计划。代价是破坏查询规划器稳定性保证难以在大规模应用中保证一致性能。SQLITE_ENABLE_STAT3是SQLITE_ENABLE_STAT4的早期增强仅记录每个索引最左列且当启用 STAT4 时 STAT3 会被忽略允许 URI 权限段sqlite_allow_uri_authorityURI 文件名通常会在权限段authority 部分非空且非 localhost 时报错启用该选项后 URI 会被转换为 UNC 文件名传给底层操作系统App Armorsqlite_app_armor激活检测 SQLite API 误用的额外代码如向必需参数传 NULL、使用已销毁对象等。Windows 下不可用禁用加载扩展sqlite_omit_load_extension默认允许加载外部扩展添加该标签可禁用扩展加载能力启用序列化sqlite_serializeSQLite 数据库的序列化/反序列化默认可用当设置libsqlite3标签时需额外加sqlite_serialize才能启用外键sqlite_foreign_keys决定新数据库连接默认是否强制外键约束默认关闭运行期可用foreign_keyspragma 随时开关完全自动清理sqlite_vacuum_full将默认 auto vacuum 设为 full增量自动清理sqlite_vacuum_incr将默认 auto vacuum 设为 incremental全文搜索引擎sqlite_fts5将全文搜索引擎 FTS5 加入构建Unicode 国际组件sqlite_icu将 ICUInternational Components for Unicode扩展加入构建内省 PRAGMAsqlite_introspect增加额外的 PRAGMA 语句PRAGMA function_list、PRAGMA module_list、PRAGMA pragma_listJSON SQL 函数sqlite_json将 JSON SQL 函数加入构建数学函数sqlite_math_functions启用内置标量数学函数操作系统追踪sqlite_os_trace启用 OSTRACE() 调试日志输出冗长不应在生产环境使用预更新钩子sqlite_preupdate_hook在每次 INSERT、UPDATE、DELETE 之前注册回调安全删除sqlite_secure_delete改变secure_deletepragma 的默认值默认关启用后默认开删除内容会被零覆盖有少量 I/O 性能代价但可防止敏感信息残留于数据库文件中未使用的区域安全删除FASTsqlite_secure_delete_fast对应PRAGMA secure_delete的 FAST 模式追踪 / 调试sqlite_trace激活 trace 函数用户认证sqlite_userauth启用 SQLite 用户认证详见第六章虚拟表sqlite_vtable启用 SQLite 虚拟表支持这些构建标签在 vendored 源码中都有对应的实现文件可以作为逐个特性开启与否的直接证据例如sqlite_opt_stat4.go、sqlite_opt_allow_uri_authority.go、sqlite_opt_app_armor.go、sqlite_opt_foreign_keys.go、sqlite_opt_fts5.go、sqlite_opt_icu.go、sqlite_opt_introspect.go、sqlite_opt_math_functions.go、sqlite_opt_os_trace.go、sqlite_opt_preupdate_hook.go、sqlite_opt_secure_delete.go、sqlite_opt_secure_delete_fast.go、sqlite_opt_serialize.go、sqlite_opt_userauth.go、sqlite_opt_vacuum_full.go、sqlite_opt_vacuum_incr.go、sqlite_opt_vtable.go以及加载扩展开关对应的sqlite3_load_extension.go/sqlite3_load_extension_omit.go等均在 vendor/github.com/mattn/go-sqlite3 目录下。五、编译Compilation指南编译本包需要CGO_ENABLED1环境变量若未默认设置以及gcc编译器。如果需要额外添加 CFLAGS 或 LDFLAGS 而又不想修改本包可以通过CGO_CFLAGS与CGO_LDFLAGS环境变量实现。5.1 Androidgo build -tags android5.2 ARM使用如下环境变量交叉编译 ARM 目标env CCarm-linux-gnueabihf-gcc CXXarm-linux-gnueabihf-g \ CGO_ENABLED1 GOOSlinux GOARCHarm GOARM7 \ go build -v5.3 交叉编译Cross Compile该库支持交叉编译某些场景下需要设置CC环境变量指向交叉编译器。从 macOS 交叉编译的最简单方式是使用 xgo 工具安装 musl-crossbrew install FiloSottile/musl-cross/musl-cross执行CCx86_64-linux-musl-gcc CXXx86_64-linux-musl-g GOARCHamd64 GOOSlinux CGO_ENABLED1 go build -ldflags -linkmode external -extldflags -static5.4 Google Cloud PlatformGCPGCP 不允许执行gcc因此无法在 GCP 上构建本包请只使用预先编译好的最终二进制。5.5 Linux编译 Linux 版本需先安装对应发行版的开发工具并使用构建标签linuxgo build -tags linux如果希望直接链接系统 libsqlite3可使用libsqlite3标签go build -tags libsqlite3 linux各发行版的工具安装Alpine容器内构建前执行apk add --update gcc musl-devFedorasudo yum groupinstall Development Tools Development LibrariesUbuntusudo apt-get install build-essential5.6 macOSmacOS 通常已具备编译本包所需的全部工具若缺失安装 Xcode 即可。所需依赖brew install sqlite3若需构建icu扩展还需额外升级 icu4cbrew upgrade icu4c编译命令# x86 go build -tags darwin amd64 # ARM 芯片 go build -tags darwin arm64 # 直接链接 libsqlite3 go build -tags libsqlite3 darwin amd64 go build -tags libsqlite3 darwin arm645.7 Windows编译本包需要安装gcc工具链如 TDM-GCC步骤安装 Windows 版gcc工具链若安装器未自动配置将bin目录加入 Windows PATH从 Windows 开始菜单打开 TDM-GCC 工具链终端进入项目目录并执行go build ...。5.8 常见编译错误can not be used when making a shared object; recompile with -fPIC你很可能在使用加固hardened系统。可在加固系统上使用如下命令编译go build -ldflags -extldflags-fno-PICWindows 64 位下无法构建 go-sqlite3很可能是使用了 Go 1.0Go 1.0 在 Windows 64 位上编译/链接存在问题。go get报编译错误gcc 抛internal compiler error删除已下载的仓库重新用go install github.com/mattn/go-sqlite3安装。六、用户认证User Authentication本包支持 SQLite 用户认证模块SQLite User Authentication。6.1 编译要使用用户认证模块必须以sqlite_userauth标签编译本包对应源码文件 sqlite3_opt_userauth.go未启用时使用 sqlite3_opt_userauth_omit.go 的桩实现。6.2 创建受保护数据库在连接串中提供_auth参数即可创建受用户认证保护的数据库该选项启用用户认证但还要求两个附加参数_auth_user_auth_pass当连接串中存在_auth时用户认证被启用提供的用户会被创建为admin管理员用户。首次创建之后_auth参数不再生效可以从连接串中省略。连接串示例# 创建用户 admin、密码 admin 的用户认证数据库 file:test.s3db?_auth_auth_useradmin_auth_passadmin # 创建用户 admin、密码 admin并使用 SHA1 做密码编码 file:test.s3db?_auth_auth_useradmin_auth_passadmin_auth_cryptsha16.3 密码编码Password EncodingSQLite 用户认证模块内的密码默认使用 SQLite 函数sqlite_cryp编码该函数基于凯撒密码相当不安全。本库提供若干额外的密码编码器可通过连接串配置用_auth_crypt指定编码器若所选编码器需要盐salt用_auth_salt配置。可用编码器SHA1SSHA1加盐 SHA1SHA256SSHA256加盐 SHA256SHA384SSHA384加盐 SHA384SHA512SSHA512加盐 SHA512这些编码器的实现位于 sqlite3_func_crypt.go。6.4 限制与支持限制关于用户管理的数据库操作只能由管理员用户执行。支持两类用户管理员administrators与普通用户regular users。6.5 用户管理用户管理可以直接使用*SQLiteConn也可以通过 SQL 完成。通过 SQL 管理用户函数参数说明authenticate用户名string、密码string认证用户由连接内部调用不应手动使用auth_user_add用户名string、密码string、adminint向数据库添加用户若数据库未受用户认证保护则启用之。admin为整数标识新用户是否为管理员。只有管理员能添加管理员auth_user_change用户名string、密码string、adminint修改用户。用户可改自己的密码但只有管理员能修改管理员标志位authUserDelete用户名string从数据库删除用户仅管理员可用当前登录的管理员不能被删除以确保始终至少保留一名管理员这些函数返回整数0SQLITE_OK成功23SQLITE_AUTH因认证失败或权限不足而失败SQL 示例-- 创建管理员用户 SELECT auth_user_add(admin2, admin2, 1); -- 修改用户密码 SELECT auth_user_change(user, userpassword, 0); -- 删除用户 SELECT user_delete(user);通过 *SQLiteConn 管理用户函数说明Authenticate(username, password string) error认证用户AuthUserAdd(username, password string, admin bool) error添加用户AuthUserChange(username, password string, admin bool) error修改用户AuthUserDelete(username string) error删除用户附加数据库Attached database使用附加数据库时SQLite 会沿用main数据库的认证信息来认证被附加的数据库。七、扩展ExtensionsSpatialite 可作为 SQLite 扩展与本仓库结合使用可参考 shaxbee/go-spatialite 项目。此外来自 SQLite3 Contrib 的extension-functions.c也提供了一批实用函数数学函数acos, asin, atan, atn2, atan2, acosh, asinh, atanh, difference, degrees, radians, cos, sin, tan, cot, cosh, sinh, tanh, coth, exp, log, log10, power, sign, sqrt, square, ceil, floor, pi字符串函数replicate, charindex, leftstr, rightstr, ltrim, rtrim, trim, replace, reverse, proper, padl, padr, padc, strfilter聚合函数stdev, variance, mode, median, lower_quartile, upper_quartile对应实现可参考 dinedal/go-sqlite3-extension-functions 项目。八、FAQ常见问题速查插入错误发生在查询打开时可以在连接串中传入一些参数例如 URI。想用 mingw 在 Linux 或 Mac 上交叉编译参见 mingw 交叉编译相关社区方案。想要带当前 locale 的 time.Time在 SQLite 文件名 schema 中使用_locauto如file:foo.db?_locauto。能否在多个 goroutine 中并发使用只读可以可写不行。为什么遇到no such table错误sql.Open(sqlite3, :memory:)为什么会竞态因为每次连接到:memory:都会打开一个全新的内存数据库如果标准库的 sql 引擎恰好打开了另一个连接而你又只指定了:memory:那个连接看到的就是一个全新数据库。解决办法是使用file::memory:?cacheshared或file:foobar?modememorycacheshared这样每个指向该串的连接都会指向同一个内存数据库。注意如果连接池中的最后一个连接关闭内存数据库会被删除。请确保最大空闲连接数DB.SetMaxIdleConns大于 0且连接生命周期DB.SetConnMaxLifetime为无限。OSX 上大量 goroutine 读数据库失败OS X 默认限制整个操作系统同时打开的文件数不超过 1000。执行.点命令报错报Error: near .: syntax error。点命令属于 SQLite3 CLI命令行工具的一部分不属于本库需要自行实现该功能或调用 sqlite3 命令行。报错database is locked先在 DSN 中加入cacheshareddb, err : sql.Open(sqlite3, file:locked.sqlite?cacheshared)然后把 SQL 包的数据库连接数设为 1db.SetMaxOpenConns(1)九、仓库实战go-sqlite3 在 nhost 中的接入方式回到当前仓库github.com/mattn/go-sqlite3被 nhost 的Constellation SQL 连接器用于实现 SQLite 方言支持版本 v1.14.22见 go.mod。在 sqlite.go 中可以看到一个教科书式的接入模式自定义驱动注册通过sync.Once保证进程级只注册一次使用sql.Register注册名为sqlite3_constellation的私有驱动避免与项目其他部分可能使用的驱动名冲突ConnectHook 统一设置连接级 PRAGMA利用 go-sqlite3 提供的SQLiteDriver.ConnectHook在每条新的物理连接建立时执行三条幂等 PRAGMA——PRAGMA foreign_keysON、PRAGMA case_sensitive_likeON、PRAGMA journal_modeWAL这些 PRAGMA 与本文第三章 DSN 参数表中的_foreign_keys、_case_sensitive_like、_journal_mode一一对应是连接串参数与编程式钩子两种配置路径的典型对照PRAGMA 的实际执行落在 cgo 构建变体 pragma_cgo.go 中通过conn.Exec(pragma, nil)完成——这正是 go-sqlite3 暴露*SQLiteConn能力的一个实例。此外该包在测试基础设施中也被广泛使用例如services/constellation/internal/lib/testdb与services/constellation/connector/sql/sqlite下的*_test.go印证了其薄封装database/sql的定位大量 SQL 生成逻辑并不在本包内而是由连接器上层的 dialect 实现完成。十、License 与作者本包采用MIT License。其中sqlite3-binding.c、sqlite3-binding.h、sqlite3ext.h是自 SQLite3 复制而来的代码融合amalgamation其许可证与 SQLite3 相同-binding后缀是为了避免在 gccgo 下的构建失败而添加的。作者Yasuhiro Matsumotoa.k.a mattn与 G.J.R. Timmer。本文所依赖的完整文档位于仓库 vendor/github.com/mattn/go-sqlite3/README.md核心源码可在 vendor/github.com/mattn/go-sqlite3 目录中继续深入阅读。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
go-sqlite3 完全指南：Go 语言 SQLite3 驱动的 DSN 配置、构建标签与用户认证实战
go-sqlite3 完全指南Go 语言 SQLite3 驱动的 DSN 配置、构建标签与用户认证实战【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost导读本文以当前仓库中 vendored 的github.com/mattn/go-sqlite3版本 v1.14.22见 go.mod官方 README 为骨架系统讲解这个符合 Go 标准库database/sql接口的 SQLite3 驱动从安装前提、DSN 连接串的全部参数、按构建标签裁剪特性的机制到编译跨平台产物与 SQLite 用户认证模块的完整用法。读完本文你将能够独立配置 go-sqlite3 的各类连接参数、按需开启 FTS5/ICU/JSON 等扩展并在项目中落地带用户认证的 SQLite 数据库同时可以看到该驱动在 nhost 项目 Constellation SQL 连接器中的真实接入方式sqlite.go。一、驱动概览一个符合 database/sql 接口的 SQLite3 驱动go-sqlite3 是一个符合 Go 内置database/sql接口的 SQLite3 驱动。这意味着你可以通过标准库database/sql的sql.Open、sql.DB、sql.Tx等抽象来使用它无需引入非标准的数据访问 API上层代码也因此可以无缝替换为其他驱动。需要特别注意的是该包是cgo 包构建依赖gcc编译器与CGO_ENABLED1环境变量版本语义上最新稳定版本是 v1.14 及之后而非 v2。README 明确说明 v2 版本号的提升是一次意外事故其中并无重大变更或新特性项目遵循官方 Golang Release Policy支持的具体 Go 版本范围以仓库 CI 配置为准。在 nhost 仓库中该依赖被锁定为v1.14.22见 go.mod与稳定版本是 v1.14 系列的声明一致。二、安装与构建前提使用go get即可安装go get github.com/mattn/go-sqlite3由于 go-sqlite3 是cgo 包构建你的应用需要系统中有gcc。不过一旦你使用go install github.com/mattn/go-sqlite3此步需要 gcc完成构建安装后续构建你的应用就不再需要依赖 gcc。重要提醒因为这是启用CGO的包你必须设置环境变量CGO_ENABLED1并确保gcc编译器位于 PATH 中否则会报错或静默回退到不可用的构建路径。三、Connection StringDSN连接串全解析创建新的 SQLite 数据库或连接已有数据库时除了文件名还可以追加额外选项这串参数即 DSNData Source Name数据源名称。3.1 DSN 基本格式选项追加在 SQLite 数据库文件名之后文件名与选项之间用?问号分隔选项应做 URL 编码对应 Go 标准库net/url的QueryEscape该规则同样适用于内存数据库in-memory database选项格式为KEYWORDVALUE多个选项之间用连接该库既支持 SQLite 自身提供的 DSN 选项也提供了一批额外的私有选项。布尔值的合法写法有两种集合假值0、no、false、off真值1、yes、true、on3.2 DSN 选项完整参数表名称键Key取值Value说明UA - 创建_auth-启用用户认证并创建数据库详见第六章UA - 用户名_auth_userstring用户认证的用户名UA - 密码_auth_passstring用户认证的密码UA - 加密方式_auth_cryptSHA1、SSHA1、SHA256、SSHA256、SHA384、SSHA384、SHA512、SSHA512用户认证使用的密码编码器UA - 盐_auth_saltstring当所选密码编码器需要盐salt时使用自动清理_auto_vacuum/_vacuum0/none、1/full、2/incremental对应 SQLite 的PRAGMA auto_vacuum忙等待超时_busy_timeout/_timeoutint指定sqlite3_busy_timeout的值对应PRAGMA busy_timeout区分大小写 LIKE_case_sensitive_like/_cslikeboolean对应PRAGMA case_sensitive_like延迟外键_defer_foreign_keys/_defer_fkboolean对应PRAGMA defer_foreign_keys外键约束_foreign_keys/_fkboolean对应PRAGMA foreign_keys忽略 CHECK 约束_ignore_check_constraintsboolean对应PRAGMA ignore_check_constraints不可变immutableboolean对应 SQLite 打开标志中的 Immutable 选项日志模式_journal_mode/_journalDELETE、TRUNCATE、PERSIST、MEMORY、WAL、OFF对应PRAGMA journal_mode锁定模式_locking_mode/_lockingNORMAL、EXCLUSIVE对应PRAGMA locking_mode访问模式modero、rw、rwc、memory数据库访问模式对应 SQLite Open 标志互斥锁_mutexno、full指定互斥模式只查询_query_onlyboolean对应PRAGMA query_only递归触发器_recursive_triggers/_rtboolean对应PRAGMA recursive_triggers安全删除_secure_deleteboolean/FAST对应PRAGMA secure_delete共享缓存cacheshared、private设置缓存模式shared-cache同步级别_synchronous/_sync0/OFF、1/NORMAL、2/FULL、3/EXTRA对应PRAGMA synchronous时区位置_locauto指定时间格式的时区位置事务锁_txlockimmediate、deferred、exclusive指定事务的锁定行为可写 Schema_writable_schemaboolean开启后SQLITE_MASTER表可用普通 UPDATE/INSERT/DELETE 修改警告滥用该选项极易损坏数据库文件缓存大小_cache_sizeint最大缓存大小默认 2000K2M对应PRAGMA cache_size这些参数的解析逻辑可以在驱动的 DSN 解析源码中直接看到sqlite3.go例如_loc的时区解析、_txlock的事务锁映射、_journal_mode/_locking_mode的 PRAGMA 透传、_auth*系列的用户认证参数读取等均有对应的params.Get(...)分支与错误处理。3.3 DSN 示例file:test.db?cachesharedmodememory该示例同时指定了共享缓存cacheshared与内存访问模式modememory是构造多连接共享同一内存数据库的经典写法详见第七章 FAQ 中:memory:的讨论。四、特性Features与构建标签该包允许通过 Go 的构建约束build tags又称构建标签来启用或禁用 SQLite3 内可用的各项特性。4.1 使用方式如需携带额外扩展/特性构建该库使用如下命令go build -tags FEATURE可用的特性见下方扩展列表。使用多个构建标签时标签之间以空格分隔例如go build -tags icu json1 fts5 secure_delete4.2 特性 / 扩展完整列表扩展构建标签说明附加统计信息sqlite_stat4为 ANALYZE 命令与查询规划器增加额外逻辑从每个索引的全部列收集直方图数据存入sqlite_stat4表帮助 SQLite 在特定场景下选择更优查询计划。代价是破坏查询规划器稳定性保证难以在大规模应用中保证一致性能。SQLITE_ENABLE_STAT3是SQLITE_ENABLE_STAT4的早期增强仅记录每个索引最左列且当启用 STAT4 时 STAT3 会被忽略允许 URI 权限段sqlite_allow_uri_authorityURI 文件名通常会在权限段authority 部分非空且非 localhost 时报错启用该选项后 URI 会被转换为 UNC 文件名传给底层操作系统App Armorsqlite_app_armor激活检测 SQLite API 误用的额外代码如向必需参数传 NULL、使用已销毁对象等。Windows 下不可用禁用加载扩展sqlite_omit_load_extension默认允许加载外部扩展添加该标签可禁用扩展加载能力启用序列化sqlite_serializeSQLite 数据库的序列化/反序列化默认可用当设置libsqlite3标签时需额外加sqlite_serialize才能启用外键sqlite_foreign_keys决定新数据库连接默认是否强制外键约束默认关闭运行期可用foreign_keyspragma 随时开关完全自动清理sqlite_vacuum_full将默认 auto vacuum 设为 full增量自动清理sqlite_vacuum_incr将默认 auto vacuum 设为 incremental全文搜索引擎sqlite_fts5将全文搜索引擎 FTS5 加入构建Unicode 国际组件sqlite_icu将 ICUInternational Components for Unicode扩展加入构建内省 PRAGMAsqlite_introspect增加额外的 PRAGMA 语句PRAGMA function_list、PRAGMA module_list、PRAGMA pragma_listJSON SQL 函数sqlite_json将 JSON SQL 函数加入构建数学函数sqlite_math_functions启用内置标量数学函数操作系统追踪sqlite_os_trace启用 OSTRACE() 调试日志输出冗长不应在生产环境使用预更新钩子sqlite_preupdate_hook在每次 INSERT、UPDATE、DELETE 之前注册回调安全删除sqlite_secure_delete改变secure_deletepragma 的默认值默认关启用后默认开删除内容会被零覆盖有少量 I/O 性能代价但可防止敏感信息残留于数据库文件中未使用的区域安全删除FASTsqlite_secure_delete_fast对应PRAGMA secure_delete的 FAST 模式追踪 / 调试sqlite_trace激活 trace 函数用户认证sqlite_userauth启用 SQLite 用户认证详见第六章虚拟表sqlite_vtable启用 SQLite 虚拟表支持这些构建标签在 vendored 源码中都有对应的实现文件可以作为逐个特性开启与否的直接证据例如sqlite_opt_stat4.go、sqlite_opt_allow_uri_authority.go、sqlite_opt_app_armor.go、sqlite_opt_foreign_keys.go、sqlite_opt_fts5.go、sqlite_opt_icu.go、sqlite_opt_introspect.go、sqlite_opt_math_functions.go、sqlite_opt_os_trace.go、sqlite_opt_preupdate_hook.go、sqlite_opt_secure_delete.go、sqlite_opt_secure_delete_fast.go、sqlite_opt_serialize.go、sqlite_opt_userauth.go、sqlite_opt_vacuum_full.go、sqlite_opt_vacuum_incr.go、sqlite_opt_vtable.go以及加载扩展开关对应的sqlite3_load_extension.go/sqlite3_load_extension_omit.go等均在 vendor/github.com/mattn/go-sqlite3 目录下。五、编译Compilation指南编译本包需要CGO_ENABLED1环境变量若未默认设置以及gcc编译器。如果需要额外添加 CFLAGS 或 LDFLAGS 而又不想修改本包可以通过CGO_CFLAGS与CGO_LDFLAGS环境变量实现。5.1 Androidgo build -tags android5.2 ARM使用如下环境变量交叉编译 ARM 目标env CCarm-linux-gnueabihf-gcc CXXarm-linux-gnueabihf-g \ CGO_ENABLED1 GOOSlinux GOARCHarm GOARM7 \ go build -v5.3 交叉编译Cross Compile该库支持交叉编译某些场景下需要设置CC环境变量指向交叉编译器。从 macOS 交叉编译的最简单方式是使用 xgo 工具安装 musl-crossbrew install FiloSottile/musl-cross/musl-cross执行CCx86_64-linux-musl-gcc CXXx86_64-linux-musl-g GOARCHamd64 GOOSlinux CGO_ENABLED1 go build -ldflags -linkmode external -extldflags -static5.4 Google Cloud PlatformGCPGCP 不允许执行gcc因此无法在 GCP 上构建本包请只使用预先编译好的最终二进制。5.5 Linux编译 Linux 版本需先安装对应发行版的开发工具并使用构建标签linuxgo build -tags linux如果希望直接链接系统 libsqlite3可使用libsqlite3标签go build -tags libsqlite3 linux各发行版的工具安装Alpine容器内构建前执行apk add --update gcc musl-devFedorasudo yum groupinstall Development Tools Development LibrariesUbuntusudo apt-get install build-essential5.6 macOSmacOS 通常已具备编译本包所需的全部工具若缺失安装 Xcode 即可。所需依赖brew install sqlite3若需构建icu扩展还需额外升级 icu4cbrew upgrade icu4c编译命令# x86 go build -tags darwin amd64 # ARM 芯片 go build -tags darwin arm64 # 直接链接 libsqlite3 go build -tags libsqlite3 darwin amd64 go build -tags libsqlite3 darwin arm645.7 Windows编译本包需要安装gcc工具链如 TDM-GCC步骤安装 Windows 版gcc工具链若安装器未自动配置将bin目录加入 Windows PATH从 Windows 开始菜单打开 TDM-GCC 工具链终端进入项目目录并执行go build ...。5.8 常见编译错误can not be used when making a shared object; recompile with -fPIC你很可能在使用加固hardened系统。可在加固系统上使用如下命令编译go build -ldflags -extldflags-fno-PICWindows 64 位下无法构建 go-sqlite3很可能是使用了 Go 1.0Go 1.0 在 Windows 64 位上编译/链接存在问题。go get报编译错误gcc 抛internal compiler error删除已下载的仓库重新用go install github.com/mattn/go-sqlite3安装。六、用户认证User Authentication本包支持 SQLite 用户认证模块SQLite User Authentication。6.1 编译要使用用户认证模块必须以sqlite_userauth标签编译本包对应源码文件 sqlite3_opt_userauth.go未启用时使用 sqlite3_opt_userauth_omit.go 的桩实现。6.2 创建受保护数据库在连接串中提供_auth参数即可创建受用户认证保护的数据库该选项启用用户认证但还要求两个附加参数_auth_user_auth_pass当连接串中存在_auth时用户认证被启用提供的用户会被创建为admin管理员用户。首次创建之后_auth参数不再生效可以从连接串中省略。连接串示例# 创建用户 admin、密码 admin 的用户认证数据库 file:test.s3db?_auth_auth_useradmin_auth_passadmin # 创建用户 admin、密码 admin并使用 SHA1 做密码编码 file:test.s3db?_auth_auth_useradmin_auth_passadmin_auth_cryptsha16.3 密码编码Password EncodingSQLite 用户认证模块内的密码默认使用 SQLite 函数sqlite_cryp编码该函数基于凯撒密码相当不安全。本库提供若干额外的密码编码器可通过连接串配置用_auth_crypt指定编码器若所选编码器需要盐salt用_auth_salt配置。可用编码器SHA1SSHA1加盐 SHA1SHA256SSHA256加盐 SHA256SHA384SSHA384加盐 SHA384SHA512SSHA512加盐 SHA512这些编码器的实现位于 sqlite3_func_crypt.go。6.4 限制与支持限制关于用户管理的数据库操作只能由管理员用户执行。支持两类用户管理员administrators与普通用户regular users。6.5 用户管理用户管理可以直接使用*SQLiteConn也可以通过 SQL 完成。通过 SQL 管理用户函数参数说明authenticate用户名string、密码string认证用户由连接内部调用不应手动使用auth_user_add用户名string、密码string、adminint向数据库添加用户若数据库未受用户认证保护则启用之。admin为整数标识新用户是否为管理员。只有管理员能添加管理员auth_user_change用户名string、密码string、adminint修改用户。用户可改自己的密码但只有管理员能修改管理员标志位authUserDelete用户名string从数据库删除用户仅管理员可用当前登录的管理员不能被删除以确保始终至少保留一名管理员这些函数返回整数0SQLITE_OK成功23SQLITE_AUTH因认证失败或权限不足而失败SQL 示例-- 创建管理员用户 SELECT auth_user_add(admin2, admin2, 1); -- 修改用户密码 SELECT auth_user_change(user, userpassword, 0); -- 删除用户 SELECT user_delete(user);通过 *SQLiteConn 管理用户函数说明Authenticate(username, password string) error认证用户AuthUserAdd(username, password string, admin bool) error添加用户AuthUserChange(username, password string, admin bool) error修改用户AuthUserDelete(username string) error删除用户附加数据库Attached database使用附加数据库时SQLite 会沿用main数据库的认证信息来认证被附加的数据库。七、扩展ExtensionsSpatialite 可作为 SQLite 扩展与本仓库结合使用可参考 shaxbee/go-spatialite 项目。此外来自 SQLite3 Contrib 的extension-functions.c也提供了一批实用函数数学函数acos, asin, atan, atn2, atan2, acosh, asinh, atanh, difference, degrees, radians, cos, sin, tan, cot, cosh, sinh, tanh, coth, exp, log, log10, power, sign, sqrt, square, ceil, floor, pi字符串函数replicate, charindex, leftstr, rightstr, ltrim, rtrim, trim, replace, reverse, proper, padl, padr, padc, strfilter聚合函数stdev, variance, mode, median, lower_quartile, upper_quartile对应实现可参考 dinedal/go-sqlite3-extension-functions 项目。八、FAQ常见问题速查插入错误发生在查询打开时可以在连接串中传入一些参数例如 URI。想用 mingw 在 Linux 或 Mac 上交叉编译参见 mingw 交叉编译相关社区方案。想要带当前 locale 的 time.Time在 SQLite 文件名 schema 中使用_locauto如file:foo.db?_locauto。能否在多个 goroutine 中并发使用只读可以可写不行。为什么遇到no such table错误sql.Open(sqlite3, :memory:)为什么会竞态因为每次连接到:memory:都会打开一个全新的内存数据库如果标准库的 sql 引擎恰好打开了另一个连接而你又只指定了:memory:那个连接看到的就是一个全新数据库。解决办法是使用file::memory:?cacheshared或file:foobar?modememorycacheshared这样每个指向该串的连接都会指向同一个内存数据库。注意如果连接池中的最后一个连接关闭内存数据库会被删除。请确保最大空闲连接数DB.SetMaxIdleConns大于 0且连接生命周期DB.SetConnMaxLifetime为无限。OSX 上大量 goroutine 读数据库失败OS X 默认限制整个操作系统同时打开的文件数不超过 1000。执行.点命令报错报Error: near .: syntax error。点命令属于 SQLite3 CLI命令行工具的一部分不属于本库需要自行实现该功能或调用 sqlite3 命令行。报错database is locked先在 DSN 中加入cacheshareddb, err : sql.Open(sqlite3, file:locked.sqlite?cacheshared)然后把 SQL 包的数据库连接数设为 1db.SetMaxOpenConns(1)九、仓库实战go-sqlite3 在 nhost 中的接入方式回到当前仓库github.com/mattn/go-sqlite3被 nhost 的Constellation SQL 连接器用于实现 SQLite 方言支持版本 v1.14.22见 go.mod。在 sqlite.go 中可以看到一个教科书式的接入模式自定义驱动注册通过sync.Once保证进程级只注册一次使用sql.Register注册名为sqlite3_constellation的私有驱动避免与项目其他部分可能使用的驱动名冲突ConnectHook 统一设置连接级 PRAGMA利用 go-sqlite3 提供的SQLiteDriver.ConnectHook在每条新的物理连接建立时执行三条幂等 PRAGMA——PRAGMA foreign_keysON、PRAGMA case_sensitive_likeON、PRAGMA journal_modeWAL这些 PRAGMA 与本文第三章 DSN 参数表中的_foreign_keys、_case_sensitive_like、_journal_mode一一对应是连接串参数与编程式钩子两种配置路径的典型对照PRAGMA 的实际执行落在 cgo 构建变体 pragma_cgo.go 中通过conn.Exec(pragma, nil)完成——这正是 go-sqlite3 暴露*SQLiteConn能力的一个实例。此外该包在测试基础设施中也被广泛使用例如services/constellation/internal/lib/testdb与services/constellation/connector/sql/sqlite下的*_test.go印证了其薄封装database/sql的定位大量 SQL 生成逻辑并不在本包内而是由连接器上层的 dialect 实现完成。十、License 与作者本包采用MIT License。其中sqlite3-binding.c、sqlite3-binding.h、sqlite3ext.h是自 SQLite3 复制而来的代码融合amalgamation其许可证与 SQLite3 相同-binding后缀是为了避免在 gccgo 下的构建失败而添加的。作者Yasuhiro Matsumotoa.k.a mattn与 G.J.R. Timmer。本文所依赖的完整文档位于仓库 vendor/github.com/mattn/go-sqlite3/README.md核心源码可在 vendor/github.com/mattn/go-sqlite3 目录中继续深入阅读。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
