go-sqlite3: sqlite3驱动程序for go using database/sql

go-sqlite3

最新的稳定版本是v1.14或更高版本，而不是v2。

注：增加到v2是一个意外。没有大的变化或特点。

Description

符合built-in数据库/sql接口的sqlite3驱动程序

支持的Golang版本：请参见.github/workflows/去吧。亚姆

此软件包遵循Golang官方发布政策。

Overview

• go-sqlite3
• Description
  • Overview
• Installation
• API Reference
• Connection String
  • DSN Examples
• 功能使用功能/扩展列表
• Compilation
  • Android
• ARM
• Cross Compile
• Google Cloud PlatformLinux Alpine Fedora Ubuntu Mac OSX Windows错误
• 用户身份验证编译用法创建受保护数据库密码编码可用编码器限制支持用户管理SQL示例*SQLiteConn附加数据库
• Extensions
  • Spatialite
• FAQ
• License
• Author

Installation

可以使用go-get命令安装此软件包：

go get github.com/mattn/go-sqlite3

go-sqlite3是cgo包。如果要使用go-sqlite3构建应用程序，则需要gcc。但是，在使用go install github.com/mattn/go-sqlite3（需要gcc）构建并安装了go-sqlite3之后，以后就可以不用依赖gcc来构建应用了。

重要提示：因为这是一个启用了CGO的包，因此需要设置环境变量CGO_ENABLED=1，并在路径中存在gcc编译。

API Reference

API文档可以在这里找到：http://godoc.org/github.com/mattn/go-sqlite3

示例可以在Examples目录下找到

Connection String

当创建新的SQLite数据库或与现有数据库的连接时，可以使用文件名提供其他选项。这也称为DSN字符串。（数据源名称）。

选项附加在SQLite数据库的文件名之后。数据库文件名和选项用?（问号）隔开。选项应该是URL-encoded（请参见url.queryscape).

这也适用于使用in-memory数据库而不是文件。

可以使用以下格式给出选项：KEYWORD=VALUE，并且可以将多个选项与&和号组合使用。

此库支持SQLite本身的dsn选项，并提供其他选项。

布尔值可以是：

• 0nofalseoff
• 1yestrueon

Name	Key	Value(s)	Description
UA-创建	_auth	-	创建用户身份验证，有关详细信息，请参阅用户身份验证
UA-用户名	_auth_user	string	用户名用于用户身份验证，有关详细信息，请参阅用户身份验证
UA-密码	_auth_pass	string	用户身份验证的密码，有关详细信息，请参阅用户身份验证
UA-地下室	_auth_crypt	SHA1 SSHA1 SHA256 SSHA256 SHA384 SSHA384 SHA512 SSHA512	用于用户身份验证的密码编码器，有关详细信息，请参阅用户身份验证
尿酸盐	_auth_salt	string	如果配置密码编码器需要Salt，则要使用Salt，对于用户身份验证，有关更多信息，请参阅用户身份验证
Auto Vacuum	_auto_vacuum_vacuum	0none1full2incremental	有关详细信息，请参见PRAGMAauto_vacuum
Busy Timeout	_busy_timeout_timeout	int	指定sqlite3_busy_timeout的值。有关详细信息，请参见PRAGMAbusy_timeout
Case Sensitive LIKE	_case_sensitive_like_cslike	boolean	有关详细信息，请参见PRAGMAcase_sensitive_like
Defer Foreign Keys	_defer_foreign_keys_defer_fk	boolean	有关详细信息，请参见PRAGMAdefer_foreign_keys
Foreign Keys	_foreign_keys_fk	boolean	有关详细信息，请参见PRAGMAforeign_keys
Ignore CHECK Constraints	_ignore_check_constraints	boolean	有关详细信息，请参见PRAGMAignore_check_constraints
Immutable	immutable	boolean	有关更多信息，请参见Immutable
Journal Mode	_journal_mode_journal	DELETE TRUNCATE PERSIST MEMORY WAL OFF	有关详细信息，请参见PRAGMAjournal_mode
Locking Mode	_locking_mode_locking	NORMAL EXCLUSIVE	有关详细信息，请参见PRAGMAlocking_mode
Mode	mode	ro-rw-rwc存储器	数据库的访问模式。有关详细信息，请参见SQLite Open
Mutex Locking	_mutex	no full	指定互斥模式。
Query Only	_query_only	boolean	有关详细信息，请参见PRAGMAquery_only
Recursive Triggers	_recursive_triggers_rt	boolean	有关详细信息，请参见PRAGMArecursive_triggers
Secure Delete	_secure_delete	booleanFAST	有关详细信息，请参见PRAGMAsecure_delete
Shared-Cache Mode	cache	shared private	有关更多信息，请参见sqlite.org
Synchronous	_synchronous_sync	0 |关1 |普通2 |满3 |额外	有关详细信息，请参见PRAGMA synchronous
Time Zone Location	_loc	auto	指定时间格式的位置。
Transaction Lock	_txlock	立即延迟独占	指定事务的锁定行为。
Writable Schema	_writable_schema	Boolean	启用此pragma时，SQLITE_MASTER表中的数据库可以使用普通的UPDATE、INSERT和DELETE语句进行更改。警告：误用此pragma很容易导致数据库文件损坏。

DSN Examples

file:test.db?cache=shared&mode=memory

Features

这个包允许SQLite3中可用特性的附加配置被golang构建约束（也称为buildtags）启用或禁用。

单击此处获取有关生成标记/约束的详细信息。

Usage

如果您希望使用其他扩展/功能构建此库。使用以下命令。

go build --tags "<FEATURE>"

有关可用功能，请参阅扩展列表。当使用多个构建标记时，所有不同的标记都应该是空格分隔的。

Example:

go build --tags "icu json1 fts5 secure_delete"

功能/扩展列表

Extension	Build Tag	Description
Additional Statistics	sqlite_stat4	此选项向ANALYZE命令和query planner添加了额外的逻辑，可以帮助SQLite在某些情况下选择更好的查询计划。ANALYZE命令得到了增强，可以从每个索引的所有列收集直方图数据，并将这些数据存储在sqlite_stat4表中。然后，查询规划器将使用直方图数据来帮助它做出更好的索引选择。这个compile-time选项的缺点是它违反了query planner稳定性保证，使得在mass-produced应用程序中确保一致的性能更加困难。SQLITE_ENABLE_STAT4是SQLITE_ENABLE_STAT3的增强。STAT3只记录每个索引的left-most列的直方图数据，而STAT4增强功能则记录每个索引的所有列的直方图数据。SQLITE_ENABLE_STAT3compile-time选项是一个无操作，如果使用SQLITE_ENABLE_STAT4compile-time选项，则将忽略该选项
Allow URI Authority	sqlite_allow_uri_authority	如果authority部分不是空的或“localhost”，URI文件名通常会抛出一个错误。但是，如果SQLite是用SQLITE_ALLOW_URI_AUTHORITYcompile-time选项编译的，那么URI将转换为统一命名约定（Uniform Naming Convention，UNC）文件名，并通过这种方式传递给底层操作系统
App Armor	sqlite_app_armor	定义后，C-preprocessor宏将激活额外的代码，这些代码试图检测SQLite API的滥用，例如传入指向所需参数的空指针或在对象被销毁后使用对象。{586下没有装甲。
Disable Load Extensions	sqlite_omit_load_extension	默认情况下启用加载外部扩展。要禁用扩展加载，请添加构建标记sqlite_omit_load_extension。
Foreign Keys	sqlite_foreign_keys	此宏确定默认情况下为新数据库连接启用还是禁用外键约束的强制执行。每个数据库连接总是可以使用foreign_keyspragma来打开和关闭外键约束的实施和run-time。外键约束的强制在默认情况下通常是关闭的，但是如果这个compile-time参数设置为1，则外键约束的强制将在默认情况下启用
Full Auto Vacuum	sqlite_vacuum_full	将默认自动真空设置为满
Incremental Auto Vacuum	sqlite_vacuum_incr	将默认的自动真空设置为增量
Full Text Search Engine	sqlite_fts5	当在合并中定义此选项时，full-text搜索引擎（fts5）的版本5将自动添加到构建中
Unicode的国际组件	sqlite_icu	此选项会导致将Unicode或“ICU”扩展的国际组件添加到构建中
Introspect PRAGMAS	sqlite_introspect	此选项添加一些额外的PRAGMA语句。PRAGMAfunction_list杂注module_list杂注pragma_list
JSON SQL Functions	sqlite_json	在合并中定义此选项时，JSON SQL函数将自动添加到构建中
Pre Update Hook	sqlite_preupdate_hook	注册一个回调函数，该函数在对数据库表执行每次插入、更新和删除操作之前调用。
Secure Delete	sqlite_secure_delete	此compile-time选项更改secure_delete杂注的默认设置。不使用此选项时，secure_delete默认为关闭。当这个选项存在时，secure_delete默认为打开。secure_delete设置导致删除的内容被零覆盖。由于必须进行额外的I/O操作，因此性能会受到较小的影响。另一方面，secure_delete可以防止敏感信息片段在数据库文件被删除后滞留在未使用的部分中。有关更多信息，请参阅secure_delete杂注的文档
安全删除（快速）	sqlite_secure_delete_fast	有关详细信息，请参见PRAGMAsecure_delete
跟踪/调试	sqlite_trace	激活跟踪功能
User Authentication	sqlite_userauth	SQLite用户身份验证有关详细信息，请参阅用户身份验证。

Compilation

此包需要CGO_ENABLED=1ennvironment变量（如果默认情况下未设置）以及gcc编译器的存在。

如果需要向build命令添加其他CFLAGS或LDFLAGS，并且不想修改此包。然后可以通过使用CGO_CFLAGS和CGO_LDFLAGS环境变量来实现。

Android

这个包可以为android编译。编译时使用：

go build --tags "android"

更多信息请参见#201

ARM

要为ARM编译，请使用以下环境。

env CC=arm-linux-gnueabihf-gcc CXX=arm-linux-gnueabihf-g++ \
    CGO_ENABLED=1 GOOS=linux GOARCH=arm GOARM=7 \
    go build -v

Additional information:

• #242
• #504

Cross Compile

这个库可以是cross-compiled。

在某些情况下，您需要使用交叉编译器CC环境变量。

从macosx交叉编译

从OSX交叉编译的最简单方法是使用xgo。

Steps:

• 安装xgo（go get github.com/karalabe/xgo）。
• 确保您的项目在GOPATH内。
• 运行xgo local/path/to/project。

请参阅该项目的自述文件了解更多信息。

Google Cloud Platform

在GCP上构建是不可能的，因为Google Cloud Platform不允许gcc执行。

请仅使用编译后的最终二进制文件。

Linux

要在Linux上编译这个包，必须为Linux发行版安装开发工具。

要在linux下编译，请使用build标记linux。

go build --tags "linux"

如果希望直接链接到libsqlite3，那么可以使用libsqlite3构建标记。

go build --tags "libsqlite3 linux"

Alpine

在alpine容器中构建时，请在生成之前运行以下命令。

apk add --update gcc musl-dev

Fedora

sudo yum groupinstall "Development Tools" "Development Libraries"

Ubuntu

sudo apt-get install build-essential

Mac OSX

OSX应该有编译这个包的所有工具，如果不安装XCode，这将添加所有的开发人员工具。

Required dependency

brew install sqlite3

对于OSX，如果希望构建icu扩展，则需要安装额外的包。

此附加软件包可以与homebrew一起安装。

brew upgrade icu4c

为macosx编译。

go build --tags "darwin"

如果希望直接链接到libsqlite3，那么可以使用libsqlite3构建标记。

go build --tags "libsqlite3 darwin"

Additional information:

• #206
• #404

Windows

要在Windows操作系统上编译这个软件包，必须安装gcc编译器。

1. 安装Windowsgcc工具链。
2. 如果默认情况下安装程序没有这样做，请将bin文件夹添加到Windows路径。
3. 打开TDM-GCC工具链的终端，可以在Windows开始菜单中找到。
4. 导航到项目文件夹并为此包运行go build ...命令。

例如，TDM-GCC工具链可以在这里找到。

Errors

• 编译错误：can not be used when making a shared object; recompile with -fPIC当收到引用-FPIC重新编译的编译时错误，那么您可能使用的是强化系统。可以使用以下命令在强化系统上编译库。{更多详情请参见}
• 无法在64位windows上生成go-sqlite3。很可能，您使用的是go1.0，在64位windows上编译/链接时，go1.0存在问题。参见：#27
• go get github.com/mattn/go-sqlite3引发编译错误。gcc抛出：internal compiler error从磁盘上删除下载存储库，然后尝试使用re-install:go install github.com/mattn/go-sqlite3

User Authentication

此包支持SQLite用户身份验证模块。

Compile

要使用用户身份验证模块，必须使用标记sqlite_userauth编译包。请参见功能。

Usage

创建受保护的数据库

要创建受用户身份验证保护的数据库，请为连接字符串_auth提供以下参数。这将启用数据库中的用户身份验证。但是，此选项需要两个附加参数：

• _auth_user
• _auth_pass

当_auth出现在连接字符串上时，将启用用户身份验证，并将提供的用户创建为admin用户。在初始创建之后，参数_auth不再有效，可以从连接字符串中省略。

连接字符串示例：

使用用户admin和密码admin创建一个用户身份验证数据库。

file:test.s3db?_auth&_auth_user=admin&_auth_pass=admin

使用用户admin和密码admin创建一个用户身份验证数据库，并使用SHA1作为密码编码。

file:test.s3db?_auth&_auth_user=admin&_auth_pass=admin&_auth_crypt=sha1

Password Encoding

SQLite用户认证模块中的密码使用SQLite函数sqlite_cryp进行编码。{ceasar-cypher这个函数很不安全。这个库提供了几个额外的密码编码器，可以通过连接字符串进行配置。

密码密码可以用_auth_crypt键配置。如果配置的密码编码器也需要salt，那么可以使用_auth_salt来配置它。

Available Encoders

• SHA1
• SSHA1（盐腌沙1）
• SHA256
• SSHA256（盐渍SHA256）
• SHA384
• SSHA384（盐腌沙384）
• SHA512
• SSHA512（盐渍SHA512）

Restrictions

数据库上有关用户管理的操作只能由管理员用户执行。

Support

用户认证支持两种用户

• administrators
• regular users

User Management

用户管理可以通过直接使用*SQLiteConn或SQL来完成。

SQL

以下sql函数可用于用户管理。

Function	Arguments	Description
authenticate	用户名string，密码string	将对用户进行身份验证，这是通过连接完成的；不应手动使用。
auth_user_add	用户名string，密码string，管理员int	此函数将向数据库添加用户。如果数据库不受用户身份验证的保护，它将启用它。参数admin是一个整数，标识添加的用户是否应该是管理员。只有管理员可以添加管理员。
auth_user_change	用户名string，密码string，管理员int	函数修改用户。用户可以更改自己的密码，但只有管理员才能更改管理员标志。
authUserDelete	username string	从数据库中删除用户。只能由管理员使用。无法删除当前登录的管理员。这是为了确保他们始终保留管理员身份。

这些函数将返回一个整数。

• 0 (SQLITE_OK)
• 23(SQLITE_AUTH）由于身份验证或权限不足而无法执行

Examples

// Autheticate user
// Create Admin User
SELECT auth_user_add('admin2', 'admin2', 1);

// Change password for user
SELECT auth_user_change('user', 'userpassword', 0);

// Delete user
SELECT user_delete('user');

*SQLiteConn

以下函数可用于*SQLiteConn的用户身份验证。

Function	Description
Authenticate(username, password string) error	Authenticate user
AuthUserAdd(username, password string, admin bool) error	Add user
AuthUserChange(username, password string, admin bool) error	Modify user
AuthUserDelete(username string) error	Delete user

Attached database

使用附加数据库时。SQLite将使用来自main数据库的身份验证来连接数据库。

Extensions

如果您希望在此处列出您自己的扩展名或要添加对扩展名的引用，请为此提交问题。

Spatialite

Spatialite是SQLite的扩展，可以与此存储库结合使用。有关示例，请参见shaxbee/go-spatialite。

extension-functions.c来自SQLite3 Contrib

extension-functions.c作为SQLite的扩展提供，并提供以下功能：

• 数学：acos，asin，atan，atn2，atan2，acosh，asinh，atanh，差，度，弧度，cos，sin，tan，cot，cosh，sinh，tanh，coth，exp，log，log10，power，sign，sqrt，正方形，天花板，地板，圆周率。
• 字符串：replicate，charindex，leftstr，right str，ltrim，rtrim，trim，replace，reverse，proper，padl，padr，padc，strfilter。
• 聚合：标准偏差，方差，模式，中值，lower_quartile，upper_quartile

有关示例，请参见dinedal/go-sqlite3-extension-functions。

FAQ

• 查询打开时出现插入错误。可以将一些参数传递到连接字符串中，例如，URI。参见：#39
• 是否要交叉编译？Linux还是Mac？参见：#106另见：http://www.limitlessfx.com/cross-compile-golang-app-for-windows-from-linux.html
• 想要使用当前语言环境获得time.Time，请在SQLite3文件名模式中使用_loc=auto，比如file:foo.db?_loc=auto。
• 我可以同时在多个例程中使用它吗？是，只读。但是，不适合写。见#50，#51，#209，#274。
• 为什么我得到no such table错误？如果我使用sql.Open("sqlite3", ":memory:")数据库，为什么会很活泼？到":memory:"的每个连接都会打开一个全新的in-memorysql数据库，因此，如果stdlib的sql引擎碰巧打开了另一个连接，而您只指定了":memory:"，则该连接将看到一个全新的数据库。解决方法是使用"file::memory:?cache=shared"（或"file:foobar?mode=memory&cache=shared"）。每个到这个字符串的连接都指向同一个in-memory数据库。注意，如果池中的最后一个数据库连接关闭，in-memory数据库将被删除。确保最大空闲连接限制>0，并且连接生存期是无限的。有关更多信息，请参见#204#511https://www.sqlite.org/sharedcache.html#shared_cache_and_in_memory_databaseshttps://www.sqlite.org/inmemorydb.html#sharedmemdb
• 在OSX上从包含大量goroutine的数据库中读取失败。OSX限制OS-wide在默认情况下同时打开的文件不超过1000个。更多信息请参见#289
• 尝试执行.（dot）命令会引发错误。错误：Error: near ".": syntax errorDot命令是SQLite3 CLI的一部分，而不是这个库的一部分。您需要实现该功能或调用sqlite3cli。更多信息请参见#305
• 错误：database is locked获取数据库时被锁定。请使用以下选项。添加到DSN:cache=shared示例：db, err := sql.Open("sqlite3", "file:locked.sqlite?cache=shared") 请将SQL包的数据库连接设置为1。db.SetMaxOpenConns(1) 更多信息请参见#209

Contributors

Code Contributors

这个项目的存在要感谢所有的贡献者。[贡献]。

Financial Contributors

成为一个财政贡献者，帮助我们维持我们的社区。[贡献]

Individuals

Organizations

与您的组织一起支持这个项目。您的徽标将显示在这里与您的网站链接。[贡献]

License

MIT: http://mattn.mit-license.org/2018

sqlite3-binding.c，sqlite3-binding.h，sqlite3ext.h

添加-binding后缀是为了避免gccgo下的构建失败。

在这个存储库中，这些文件是从SQLite3复制的代码的合并。该代码的许可证与SQLite3的许可证相同。

Author

松本康弘(a.k.amattn）

G.J.R. Timmer