SQLiteC/C++接口详细介绍（一）

上一篇：SQLiteC/C++接口简介

下一篇：SQLiteC/C++接口详细介绍（二）

引言：

SQLite C/C++ 数据库接口是一个流行的SQLite库使用形式，它允许开发者在C和C++代码中嵌入 SQLite 基本功能的解决方案。通过 SQLite C/C++ 数据库接口，开发者可以轻松地连接和使用 SQLite 数据库，并针对各种数据类型执行各种操作，以满足各种应用场景下的使用需求。

SQLite拥有超过225个API，本系列文章将深入介绍 SQLite C/C++ 数据库接口的基础知识，包括如何连接和打开 SQLite 数据库、执行查询和事务管理、提取查询结果集等等，帮助开发者更好地了解和使用 SQLite 数据库接口。

编写不易，有用的朋友点个赞或加粉一下万分感谢！300名内回关！

SQLite 接口元素可分为三类：

对象类:这是SQLite库。总共有几十个对象，但是两个最重要的对象是：数据库连接对象：sqlite3和预处理语句对象：sqlite3_stmt。
常量类:这是SQLite使用的数值常量列表，由 #defines sqlite3.h 头文件中。这些常量是诸如数字结果代码之类的东西传递的各种接口（例如：SQLITE_OK）或标志进入函数来控制行为（例如：SQLITE_OPEN_READONLY）。
函数类：这是对对象进行操作并使用和/或返回常量。那里是许多功能，但大多数应用程序只使用少数几个。

首先我们从对象类开始介绍本次未介绍完将分后续章节逐步介绍：

包含以下29个类型中的第一个：

sqlite3类：

3个构造函数(也是打开数据库函数)：

intsqlite3_open(
constchar*filename,/*Databasefilename(UTF-8)*/
sqlite3**ppDb/*OUT:SQLitedbhandle*/);
或
intsqlite3_open16(
constvoid*filename,/*Databasefilename(UTF-16)*/
sqlite3**ppDb/*OUT:SQLitedbhandle*/);
或者
intsqlite3_open_v2(
constchar*filename,/*Databasefilename(UTF-8)*/
sqlite3**ppDb,/*OUT:SQLitedbhandle*/
intflags,/*Flags*/
constchar*zVfs/*NameofVFSmoduletouse*/);

这些例程打开SQLite数据库文件，由filename参数。filename参数被解释为UTF-8sqlite3_open()和sqlite3_open_v2()以及本机字节中的UTF-16sqlite3_open16()的顺序。数据库连接句柄通常以*ppDb格式返回，即使发生错误也是如此。唯一的例外是如果SQLite无法分配内存来保存sqlite3对象，NULL将写入*ppDb而不是指向sqlite3对象的指针。如果数据库已成功打开（和/或创建），则返回SQLITE_OK。否则，将返回错误代码。sqlite3_errmsg()或sqlite3_errmsg16()例程可用于获取任何失败后错误的英文描述的sqlite3_open()例程。

对于使用sqlite3_open()或sqlite3_open_v2()。数据库的默认编码使用sqlite3_open16()创建的将按本机字节顺序为UTF-16。

无论打开时是否发生错误，资源与数据库连接句柄关联的应由当不再需要它时，将其传递给sqlite3_close()。

sqlite3_open_v2()接口的工作方式类似于sqlite3_open()除了它接受两个额外的参数以进行额外的控制通过新的数据库连接。flags参数设置为sqlite3_open_v2()必须至少包括以下内容之一三种旗帜组合：

SQLITE_OPEN_READONLY

数据库以只读模式打开。如果数据库这样做不存在，则返回错误。

SQLITE_OPEN_READWRITE

如果可能，将打开数据库进行读取和写入，或者仅当文件受操作系统。无论哪种情况，数据库都必须已存在，否则返回错误。由于历史原因，如果在读写模式由于操作系统级权限而失败，尝试用于以只读模式打开它。sqlite3_db_readonly()可以是用于确定数据库是否实际存在读写。

SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE

数据库将打开进行读取和写入，并在以下情况下创建它尚不存在。这是始终用于sqlite3_open()和sqlite3_open16()。

除了必需的标志外，以下可选标志包括还支持：

SQLITE_OPEN_URI

如果设置了此标志，则文件名可以解释为URI。

SQLITE_OPEN_MEMORY

该数据库将作为内存中数据库打开。数据库由“filename”参数命名，用于缓存共享，如果启用了共享缓存模式，则忽略“文件名”。

SQLITE_OPEN_NOMUTEX

新的数据库连接将使用“多线程”线程模式。这意味着允许单独的线程同时使用SQLite，只要每个线程使用不同的数据库连接。

SQLITE_OPEN_FULLMUTEX

新的数据库连接将使用“序列化”线程模式。这意味着多个线程可以安全地尝试同时使用相同的数据库连接。（互斥锁将阻止任何实际的并发，但在此模式下尝试没有坏处。

SQLITE_OPEN_SHAREDCACHE

数据库已打开共享缓存，已启用，覆盖sqlite3_enable_shared_cache()提供的默认共享缓存设置。不建议使用共享缓存模式，因此不建议使用共享缓存SQLite的许多版本中可能会省略功能。在这种情况下，此选项是no-op。

SQLITE_OPEN_PRIVATECACHE

数据库已打开，共享缓存已禁用，覆盖sqlite3_enable_shared_cache()提供的默认共享缓存设置。

SQLITE_OPEN_EXRESCODE

数据库连接以“扩展结果代码模式”启动。换言之，数据库的行为具有ifsqlite3_extended_result_codes（db，1）在数据库上调用的位置连接创建后立即连接。除了设置扩展结果代码模式，此标志还会导致sqlite3_open_v2()返回扩展结果代码。

SQLITE_OPEN_NOFOLLOW

数据库文件名不允许包含符号链接

如果sqlite3_open_v2()的第3个参数不是上面显示的必需组合可以选择与其他SQLITE_OPEN_*位组合，则行为未定义。SQLite的历史版本已静默地忽略了flags参数中的多余位sqlite3_open_v2()，但是该行为可能无法执行到SQLite的未来版本中，因此应用程序不应依赖在它上面。特别要注意的是，SQLITE_OPEN_EXCLUSIVE标志是无操作的对于sqlite3_open_v2()。SQLITE_OPEN_EXCLUSIVE*不*导致如果数据库已存在，则为Opentofail。TheSQLITE_OPEN_EXCLUSIVEflag仅供VFS接口使用，而不是平价sqlite3_open_v2().

sqlite3_open_v2()的第四个参数是sqlite3_vfs对象的名称，该对象定义操作系统接口新的数据库连接应使用。如果第四个参数是NULL指针，则使用默认的sqlite3_vfs对象。

如果文件名为“：memory：”，则为专用的临时内存中数据库是为连接创建的。此内存中数据库将在以下情况下消失数据库连接已关闭。SQLite的未来版本可能会使用以“：”字符开头的其他特殊文件名。建议当数据库文件名实际以“：”字符，您应该在文件名前面加上路径名，例如“./”以避免歧义。

如果文件名为空字符串，则为私有的临时将创建磁盘数据库。这个私有数据库将是数据库连接关闭后立即自动删除。

URI文件名

如果启用了URI文件名解释，并且filename参数以“file：”开头，然后文件名被解释为URI。URI（英语）如果SQLITE_OPEN_URI标志是在第三个参数中设置为sqlite3_open_v2()，或者如果它有使用带有sqlite3_config()方法的SQLITE_CONFIG_URI选项或通过SQLITE_USE_URI编译时选项全局启用。URI文件名解释已关闭默认情况下，但SQLite的未来版本可能会启用URI文件名默认解释。有关其他信息，请参阅“URI文件名”信息。

URI文件名根据RFC3986进行分析。如果URI包含authority，则它必须是空字符串或字符串“本地主机”。如果颁发机构不是空字符串或“localhost”，则错误将返回给调用方。URI的片段组件，如果present，则被忽略。

SQLite使用URI的路径组件作为磁盘文件的名称其中包含数据库。如果路径以“/”字符开头，然后它被解释为绝对路径。如果路径未开始带有“/”（表示URI中省略了authority部分）然后，该路径被解释为相对路径。在Windows上，绝对路径的第一个组件是驱动器规范（例如“C：”）。

URI的查询组件可能包含解释的参数通过SQLite本身，或通过自定义VFS实现。SQLite及其内置的VFS解释以下查询参数：

vfs：“vfs”参数可用于指定一个VFS对象，该对象提供操作系统接口，该接口应用于访问磁盘上的数据库文件。如果此选项设置为使用默认VFS对象的空字符串。指定未知VFS是一个错误。如果使用sqlite3_open_v2()并且vfs选项为present，则该选项指定的VFS优先于作为第四个参数传递给sqlite3_open_v2()的值。

mode：mode参数可以设置为“ro”、“rw”、“RWC”或“内存”。尝试将其设置为任何其他值是错误。如果指定了“ro”，则数据库将以只读方式打开访问，就好像SQLITE_OPEN_READONLY标志已设置在sqlite3_open_v2()的第三个参数。如果mode选项设置为“rw”，则打开数据库进行读写（但不创建）访问权限，就好像SQLITE_OPEN_READWRITE（但不是SQLITE_OPEN_CREATE）有已设置。值“rwc”等同于同时设置两者SQLITE_OPEN_READWRITE和SQLITE_OPEN_CREATE。如果mode选项是设置为“memory”，则为永不读取的纯内存中数据库或使用从磁盘写入。指定值是错误的限制性低于指定的mode参数在第三个参数中传递给sqlite3_open_v2()的标志。

cache：cache参数可以设置为“shared”或“私人”。将其设置为“共享”等同于将传递给的flags参数中的SQLITE_OPEN_SHAREDCACHE位sqlite3_open_v2()。将cache参数设置为“private”是相当于设置SQLITE_OPEN_PRIVATECACHE位。如果使用sqlite3_open_v2()并且“cache”参数存在于一个URI文件名，其值将覆盖通过设置SQLITE_OPEN_PRIVATECACHE或SQLITE_OPEN_SHAREDCACHE标志。

psow：psow参数指示powersafe覆盖属性是否适用于数据库文件所在的存储介质。

nolock：nolock参数是一个布尔查询参数如果设置，则在回滚日志模式下禁用文件锁定。这对于访问文件系统上的数据库很有用，而该文件系统不支持锁定。警告：如果出现以下两个问题，可能会导致数据库损坏或多个进程写入同一数据库和其中任何一个数据库进程使用nolock=1。

immutable：immutable参数是一个布尔查询指示数据库文件存储在只读媒体。当设置不可变时，SQLite假定数据库文件无法更改，即使通过更高权限，因此数据库以只读方式打开，并且全部锁定并且更改检测被禁用。注意：设置不可变实际上更改的数据库文件的属性可能会导致在不正确的查询结果和/或SQLITE_CORRUPT错误中。另请参见：SQLITE_IOCAP_IMMUTABLE。

在URI的查询组件中指定未知参数不是错误。SQLite的未来版本可能会理解其他查询参数。请参阅“对SQLite具有特殊含义的查询参数”其他信息。

URI 文件名示例

URI 文件名	结果
file:data.db	打开当前目录中的文件“data.db”。
File：/Home/Fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db	打开数据库文件“/home/fred/data.db”。
file://darkstar/home/fred/data.db	错误。“暗星”不是公认的权威。
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db	仅限 Windows：在驱动器上打开 fred 桌面上的文件“data.db” C:.请注意，此示例中的 %20 转义并非严格意义上的必需的 - 空格字符可以按字面意思使用在 URI 文件名中。
file:data.db？mode=ro&cache=private	打开当前目录中的文件“data.db”进行只读访问。无论是否启用共享缓存模式默认情况下，使用专用缓存。
文件：/home/fred/data.db？vfs=unix-dotfile	打开文件“/home/fred/data.db”。使用特殊的 VFS“unix-dotfile” 它使用 dot-files 代替 POSIX 咨询锁定。
file:data.db？mode=readonly	错误。“readonly”不是“mode”参数的有效选项。请改用“ro”：“file:data.db？mode=ro”。

路径中支持URI十六进制转义序列（%HH）和查询URI的组件。十六进制转义序列由百分号-“%”-后跟两个十六进制数字指定八位字节值。在路径或查询组件之前URI文件名被解释，它们使用UTF-8和所有十六进制转义序列替换为包含相应的八位字节。如果此过程生成无效的UTF-8编码，结果是不确定的。
Windows用户注意事项：用于filename参数的编码的sqlite3_open()和sqlite3_open_v2()必须是UTF-8，而不是任何当前已定义代码页。包含国际的文件名字符必须先转换为UTF-8，然后才能将其传递给sqlite3_open()或sqlite3_open_v2()。
Windows运行时用户注意事项：必须设置临时目录在调用sqlite3_open()或sqlite3_open_v2()之前。否则，各种需要使用临时文件的功能可能会失败

关闭数据库连接

int sqlite3_close(sqlite3*);
int sqlite3_close_v2(sqlite3*);
sqlite3_close（）和 sqlite3_close_v2（）例程是析构函数对于 SQLite3 对象。如果出现以下情况，则对 sqlite3_close（）和 sqlite3_close_v2（）的调用返回SQLITE_OK SQLite3 对象已成功销毁，并且所有对象都关联资源已解除分配。
理想情况下，应用程序应完成所有准备好的语句，关闭所有 BLOB 句柄，并完成所有关联sqlite3_backup对象替换为 sqlite3 对象，然后再尝试关闭该对象。如果数据库连接与未完成准备相关联语句、BLOB 处理程序和/或未完成的 sqlite3_backup 对象 sqlite3_close（）将使数据库连接保持打开状态并返回SQLITE_BUSY。如果 sqlite3_close_v2（）是在未完成准备的情况下调用的语句、未关闭的 BLOB 处理程序和/或未完成的sqlite3_backups，无论如何，它都会返回SQLITE_OK，但不会取消分配数据库连接，它将数据库连接标记为不可用 “僵尸”并安排自动解除分配数据库连接完成所有准备好的语句后，所有 BLOB 句柄已关闭，并且所有备份都已完成。sqlite3_close_v2（）接口旨在与垃圾回收的宿主语言一起使用，并且其中调用析构函数的顺序是任意的。
如果在打开事务时销毁了 sqlite3 对象，事务会自动回滚。
sqlite3_close（C）和 sqlite3_close_v2（C）的 C 参数必须为 NULL 指针或获取的 SQLite3 对象指针从 sqlite3_open（）、sqlite3_open16（）或 sqlite3_open_v2（）开始，并且之前未关闭。使用 NULL 指针调用 sqlite3_close（）或 sqlite3_close_v2（）争论是无害的 no-op。
另请参阅对象、常量和函数的列表。

参考文献：

1. C-language Interface Specification for SQLite官方说明文档