Uniform Resource Identifiers

从版本3.7.7（2011-06-23）开始，sqlite3_open（），sqlite3_open16（）和sqlite3_open_v2（）接口以及ATTACH命令的SQLite数据库文件参数可以指定为普通文件名或作为统一资源标识符或URI。使用URI文件名的优点是可以使用URI上的查询参数来控制新创建的数据库连接的详细信息。例如，可以使用“vfs =”查询参数，以指定备用VFS。或者可以将“mode = ro”作为查询参数以只读方式打开数据库。

为了保持传统应用程序的完全向后兼容性，在缺省情况下，URI文件名功能处于禁用状态。可以使用SQLITE_USE_URI = 1或SQLITE_USE_URI = 0编译时选项启用或禁用URI文件名。URI文件名的编译时设置可以在启动时使用sqlite3_config（SQLITE_CONFIG_URI，1）或sqlite3_config（SQLITE_CONFIG_URI，0）配置调用进行更改。无论编译时或开始时间设置如何，都可以通过将SQLITE_OPEN_URI包含在作为F参数传递给sqlite3_open_v2（N，P，F，V）的一组位中来启用各个数据库连接的URI文件名。

如果在最初打开数据库连接时识别URI文件名，则在ATTACH语句中也会识别URI文件名。同样，如果在第一次打开数据库连接时URI文件名未被识别，它们将不会被ATTACH识别。

由于SQLite总是将任何不以file: 开头的文件名进行解释，而不考虑URI设置，并且由于实际文件以“ file:” 开头是非常罕见的，所以即使URI文件名目前未被使用，对于大多数应用程序来说启用URI处理也是安全的。

根据RFC 3986，1个URI由1个表，1个权限，1个路径，1个查询字符串和1个片段组成。表始终是必需的，权限或路径必有一者，而查询字符串和片段是可选的。

SQLite使用“ file:”URI语法来标识数据库文件。SQLite努力按照与Firefox，Chrome，Safari，Internet Explorer和Opera等流行Web浏览器以及Windows“start”和Mac OS-X “open"等命令行程序完全相同的方式来解释file：URIs。下面是URI解析规则的简要摘要：

• URI规范写法必须是“ file:”。任何其他规范都会导致输入被视为普通文件名。

• 权限可能被省略，也可能空白，或可能是“ localhost”。任何其他权限都会导致错误。例外：如果使用SQLITE_ALLOW_URI_AUTHORITY编译SQLite，则除“localhost”以外的任何权限值都将作为UNC文件名传递到底层操作系统。

• 如果权限存在，那么路径是可选的；如果权限被省略，则路径是必需的。

• 查询字符串是可选的，如果查询字符串存在，则将所有查询参数传递到底层VFS的xOpen方法中。

• 内容片段是可选的，如果存在，则被忽略。

可以在路径，查询字符串或片段中出现零个或多个形式为“ ％HH ”的转义序列（其中H表示任何十六进制数字）。

非格式良好的URI的文件名被解释为普通文件名。

URIs被处理为UTF8文本。在处理之前，文件名参数sqlite3_open16（）从UTF16本地字节顺序转换为UTF8。

3.1. URI 路径

URI的路径组件指定了要打开的SQLite数据库的磁盘文件。如果省略了路径组件，那么数据库将存储在一个临时文件中，当数据库连接关闭时将自动删除该文件。如果权限部分存在，那么路径总是绝对路径名。如果权限部分被省略，且路径以“/”字符（ASCII代码0x2f）开头，则该路径是绝对路径名，否则是相对路径名。在Windows上，如果绝对路径以“ / X：/ ” 开头，其中X是任何单个ASCII字母字符（“a”到“z”或“A”到“Z”），则“ X：“被理解为包含文件的驱动器号，而非顶层目录。

通常可以通过下面显示的步骤将普通文件名转换为等效的URI。唯一的例外是具有驱动器号的相对Windows路径名不能直接转换为URI; 必须首先将其更改为绝对路径名。

• 将所有“ ?”字符转换为“ %3f”。

• 将所有“ #”字符转换为“ %23”。

• （仅在Windows上）将所有“ \”字符转换为“ /”。

• 将两个或多个“ /”字符的所有序列转换为一个“ /”字符。

• （仅在Windows上）如果文件名以驱动器号开头，请添加一个“ /”字符。

• 预先安排“ file:”。

3.2. 请求参数

一个URI文件名可以选择跟一个查询字符串。查询字符串由第一个“ ?”字符后面的文本组成，但不包括以“ #” 开头的可选片段。查询字符串分为键/值对。我们通常将这些键/值对称为“查询参数”。键/值对由单个“ &”字符分隔。键首先出现，并通过单个“ =”字符与值分隔。键和值都可以包含％HH转义序列。

查询参数的文本将附加到VFS的xOpen方法的filename参数中。查询参数中的任何％HH转义序列在被附加到xOpen文件名之前被解析。一个零字节将xOpen文件名参数与第一个查询参数的键，每个键和值以及每个后续键从先前值中分离出来。附加到xOpen文件名的查询参数列表由单个零长度键终止。请注意，查询参数的值可以是空字符串。

3.3. 可识别的查询参数

一些查询参数由SQLite核心解释并用于修改新连接的特性。所有查询参数总是被传递到VFS的xOpen方法中，即使它们先前被SQLite核心读取和解释。

以下查询参数在版本3.15.0（2016-10-14）以前由SQLite识别。新的查询参数可能会在未来进行添加。

cache=shared

cache=private

缓存查询参数可以确定新数据库是使用共享缓存模式打开还是使用私有缓存打开。

immutable=1

固定的查询参数是一个布尔值，用于向SQLite发出信号，表明底层数据库文件保存在只读介质上，并且无法修改，即使是具有提升特权的另一个进程也是如此。SQLite总是以只读方式打开不可变的数据库文件，并跳过所有文件锁定并更改对不可变数据库文件的检测。如果这些查询参数（或xDeviceCharacteristics的SQLITE_IOCAP_IMMUTABLE位）断言，一个数据库文件是不可改变的，那么无论文件怎么变化，SQLite的可能返回的查询结果错误 和/或 SQLITE_CORRUPT错误。

mode=ro

mode=rw

mode=rwc

mode=memory

模式查询参数确定新数据库是否以只读方式打开、读写、在不存在的情况下创建并读写，或者新数据库是不与磁盘交互的纯内存数据库。

modeof=filename

当在unix系统上的sqlite3_open_v2（）期间创建一个新的数据库文件时，SQLite将尝试设置新数据库文件的权限以匹配现有文件“ filename ”。

nolock=1

nolock查询参数是一个布尔值，返回true时，将禁用对VFS的xLock，xUnlock和xCheckReservedLock方法的所有调用。例如，尝试访问不支持文件锁定的文件系统上的文件时，可能会使用nolock查询参数。警告：如果两个或多个数据库尝试与同一个SQLite数据库进行交互，并且其中一个或多个连接启用了“nolock”，则可能导致数据库损坏。只有在应用程序可以保证对数据库的写入被序列化时，才应该使用“nolock”查询参数。

psow=0

psow=1

psow查询参数将覆盖正在打开的数据库文件的powersafe覆盖属性。psow查询参数适用于默认窗口和unix VFSes，但可能不适用于其他专有或非标准VFS。

vfs=NAME

vfs查询参数使用名为NAME的VFS打开数据库连接。如果NAME不是内置到SQLite中的VFS的名称，或者是以前使用sqlite3_vfs_register（）注册的VFS的名称，则无法打开。

• sqlite3_open（）中的URI文件名

• URI文件名示例

 SQLite is in the Public Domain.