统一资源标识符

1. SQLite 中的 URI 文件名

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

2. 向后兼容性

为了保持对传统应用程序的完全向后兼容性，默认情况下禁用 URI 文件名功能。可以使用 SQLITE_USE_URI=1 或 SQLITE_USE_URI=0 编译时选项启用或禁用 URI 文件名。可以使用 sqlite3_config(SQLITE_CONFIG_URI,1) 或 sqlite3_config(SQLITE_CONFIG_URI,0) 配置调用在启动时更改 URI 文件名的编译时设置。无论编译时或启动时的设置如何，都可以通过将 SQLITE_OPEN_URI 位包含在传递给 sqlite3_open_v2(N,P,F,V) 的位集中，为各个数据库连接启用 URI 文件名。

如果在最初打开数据库连接时识别了 URI 文件名，那么在 ATTACH 语句中也会识别 URI 文件名。同样，如果在第一次打开数据库连接时没有识别 URI 文件名，那么 ATTACH 也不会识别它们。

由于 SQLite 始终将任何不以“file" 开头的文件名解释为普通文件名，而不管 URI 设置如何，并且由于实际的文件以“file" 开头的文件名非常罕见，因此对于大多数应用程序来说，即使当前未使用 URI 文件名，启用 URI 处理也是安全的。

3. URI 格式

根据 RFC 3986，URI 由方案、授权、路径、查询字符串和片段组成。方案始终是必需的。授权或路径也始终是必需的。查询字符串和片段是可选的。

SQLite 使用“file" URI 语法来标识数据库文件。SQLite 努力以与流行的 Web 浏览器（例如 Firefox、Chrome、Safari、Internet Explorer 和 Opera）以及命令行程序（例如 Windows "cmd start" 或 "powershell start" 或 macOS “open” 或 Linux “xdg-open” 命令）完全相同的方式解释 file: URI。URI 解析规则的简要摘要如下

URI 的方案必须是“file”。任何其他方案都会导致将输入视为普通文件名。
授权可以省略、为空或为“localhost”。任何其他授权都会导致错误。例外情况：如果 SQLite 使用 SQLITE_ALLOW_URI_AUTHORITY 编译，那么除“localhost”以外的任何授权值都将作为 UNC 文件名传递给底层操作系统。
如果存在授权，则路径是可选的。如果省略授权，则路径是必需的。
查询字符串是可选的。如果存在查询字符串，则所有查询参数都将传递到底层 VFS 的 xOpen 方法中。
片段是可选的。如果存在，则将其忽略。

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

任何不是格式正确的 URI 的文件名都将解释为普通文件名。

URI 作为 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 方法的文件名参数。在追加到 xOpen 文件名之前，将解析查询参数中的任何 %HH 转义序列。单个零字节将 xOpen 文件名参数与第一个查询参数的键、每个键和值以及每个后续键与先前值分隔。追加到 xOpen 文件名的查询参数列表以单个零长度键终止。请注意，查询参数的值可以为空字符串。

3.3. 识别的查询参数

SQLite 核心解释一些查询参数，并用于修改新连接的特征。所有查询参数都始终传递到 VFS 的 xOpen 方法中，即使它们之前已由 SQLite 核心读取和解释。

截至版本 3.15.0（2016-10-14），SQLite 识别以下查询参数。将来可能会添加新的查询参数。

cache=shared cache=private: cache 查询参数确定是否使用共享缓存模式或私有缓存打开新数据库。
immutable=1: immutable 查询参数是一个布尔值，它向 SQLite 信号底层数据库文件存储在只读介质上，并且无法修改，即使是具有提升权限的另一个进程也无法修改。SQLite 始终以只读方式打开不可变的数据库文件，并且它会跳过所有不可变数据库文件上的文件锁定和更改检测。如果此查询参数（或 SQLITE_IOCAP_IMMUTABLE 位在 xDeviceCharacteristics 中）断言数据库文件是不可变的，并且该文件无论如何发生了更改，那么 SQLite 可能会返回不正确的查询结果和/或 SQLITE_CORRUPT 错误。
mode=ro mode=rw mode=rwc mode=memory: mode 查询参数分别确定是否以只读、读写、读写和创建（如果不存在）或数据库是纯内存数据库（从不与磁盘交互）方式打开新数据库。
modeof=filename: 在 Unix 系统上执行 sqlite3_open_v2() 时创建新的数据库文件时，SQLite 将尝试将新数据库文件的权限设置为与现有文件“filename”匹配。
nolock=1: nolock 查询参数是一个布尔值，如果为真，它将禁用对 VFS 的 xLock、xUnlock 和 xCheckReservedLock 方法的所有调用。例如，当尝试访问不支持文件锁定的文件系统上的文件时，可能会使用 nolock 查询参数。注意：如果两个或多个数据库连接尝试与同一个 SQLite 数据库交互，并且一个或多个连接启用了“nolock”，那么可能会导致数据库损坏。只有在应用程序可以保证对数据库的写入已序列化的情况下，才应使用“nolock”查询参数。
psow=0 psow=1: psow 查询参数将覆盖正在打开的数据库文件的 powersafe 覆盖属性。psow 查询参数适用于默认的 Windows 和 Unix VFSes，但对于其他专有或非标准 VFSes 来说可能是一个空操作。
vfs=NAME: vfs 查询参数会导致使用名为 NAME 的 VFS 打开数据库连接。如果 NAME 不是内置于 SQLite 或已使用 sqlite3_vfs_register() 注册的 VFS 的名称，则打开尝试将失败。

4. 另请参阅

此页面最后修改于 2023-01-02 14:22:42 UTC