打开新的数据库连接

小巧、快速、可靠。
三选一。

SQLite C 接口

int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open_v2(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  int flags,              /* Flags */
  const char *zVfs        /* Name of VFS module to use */
);

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

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

无论打开时是否发生错误，都应通过将其传递给 sqlite3_close() 来释放与数据库连接处理程序关联的资源，当不再需要它时。

sqlite3_open_v2() 接口与 sqlite3_open() 类似，除了它接受两个额外的参数，用于对新的数据库连接进行额外的控制。sqlite3_open_v2() 的 flags 参数必须至少包含以下三个标志组合之一

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

数据库将作为内存数据库打开。数据库以“文件名”参数命名，用于缓存共享（如果启用了共享缓存模式），但“文件名”在其他情况下将被忽略。

SQLITE_OPEN_NOMUTEX

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

SQLITE_OPEN_FULLMUTEX

新的数据库连接将使用“序列化” 线程模式。这意味着多个线程可以安全地尝试同时使用同一个数据库连接。（互斥锁将阻止任何实际的并发，但在这种模式下，尝试并不会造成任何危害。）

SQLITE_OPEN_SHAREDCACHE

数据库以共享缓存启用状态打开，覆盖 sqlite3_enable_shared_cache() 提供的默认共享缓存设置。不鼓励使用共享缓存模式，因此许多 SQLite 版本可能会省略共享缓存功能。在这种情况下，此选项是无效的。

SQLITE_OPEN_PRIVATECACHE

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

SQLITE_OPEN_EXRESCODE

数据库连接在“扩展结果代码模式”下启动。换句话说，数据库的行为与 sqlite3_extended_result_codes(db,1) 在数据库连接创建后立即在数据库连接上调用时的行为相同。除了设置扩展结果代码模式外，此标志还会导致 sqlite3_open_v2() 返回扩展结果代码。

SQLITE_OPEN_NOFOLLOW

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

如果 sqlite3_open_v2() 的第三个参数不是上面显示的必需组合之一，可以选择与其他 SQLITE_OPEN_* 位组合使用，则行为是不确定的。SQLite 的历史版本会默默忽略 flags 参数对 sqlite3_open_v2() 的多余位，但这种行为可能不会延续到 SQLite 的未来版本，因此应用程序不应依赖这种行为。特别是请注意，SQLITE_OPEN_EXCLUSIVE 标志对于 sqlite3_open_v2() 是无效的。SQLITE_OPEN_EXCLUSIVE *不会* 在数据库已经存在的情况下导致打开失败。SQLITE_OPEN_EXCLUSIVE 标志旨在仅供 VFS 接口使用，而不是供 sqlite3_open_v2() 使用。

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

如果文件名是“：memory：”，则会为连接创建一个私有的临时内存数据库。此内存数据库将在数据库连接关闭时消失。SQLite 的未来版本可能会使用以“：”字符开头的其他特殊文件名。建议在数据库文件名实际以“：”字符开头时，在文件名之前添加路径名，例如“./”，以避免歧义。

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

URI 文件名

如果启用了 URI 文件名解释，并且文件名参数以“file：”开头，则文件名将解释为 URI。如果在 sqlite3_open_v2() 的第三个参数中设置了 SQLITE_OPEN_URI 标志，或者使用 SQLITE_CONFIG_URI 选项和 sqlite3_config() 方法或 SQLITE_USE_URI 编译时选项全局启用，则启用 URI 文件名解释。默认情况下 URI 文件名解释处于关闭状态，但 SQLite 的未来版本可能会默认启用 URI 文件名解释。有关更多信息，请参见“URI 文件名”。

URI 文件名根据 RFC 3986 进行解析。如果 URI 包含权限，则它必须为空字符串或字符串“localhost”。如果权限不是空字符串或“localhost”，则向调用者返回错误。如果存在 URI 的片段组件，则将其忽略。

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

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

vfs：可以使用“vfs”参数指定 VFS 对象的名称，该对象提供应用于访问磁盘上的数据库文件的操作系统接口。如果此选项设置为空字符串，则使用默认的 VFS 对象。指定未知的 VFS 是错误的。如果使用 sqlite3_open_v2() 并且存在 vfs 选项，则该选项指定的 VFS 将优先于作为 sqlite3_open_v2() 的第四个参数传递的值。
mode：mode 参数可以设置为“ro”、“rw”、“rwc”或“memory”。尝试将其设置为任何其他值都是错误的。如果指定了“ro”，则数据库以只读方式打开，就像在 sqlite3_open_v2() 的第三个参数中设置了 SQLITE_OPEN_READONLY 标志一样。如果 mode 选项设置为“rw”，则数据库以读写（但不是创建）方式打开，就像设置了 SQLITE_OPEN_READWRITE（但不是 SQLITE_OPEN_CREATE）一样。值“rwc”等效于设置 SQLITE_OPEN_READWRITE 和 SQLITE_OPEN_CREATE。如果 mode 选项设置为“memory”，则使用一个永远不会从磁盘读取或写入的纯内存数据库。对于 mode 参数指定的值，如果该值比作为 sqlite3_open_v2() 的第三个参数传递的标志指定的限制更宽松，则为错误。
cache：cache 参数可以设置为“shared”或“private”。将其设置为“shared”等效于在传递给 sqlite3_open_v2() 的 flags 参数中设置 SQLITE_OPEN_SHAREDCACHE 位。将 cache 参数设置为“private”等效于设置 SQLITE_OPEN_PRIVATECACHE 位。如果使用 sqlite3_open_v2() 并且 URI 文件名中存在“cache”参数，则其值将覆盖通过设置 SQLITE_OPEN_PRIVATECACHE 或 SQLITE_OPEN_SHAREDCACHE 标志请求的任何行为。
psow：psow 参数指示存储数据库文件的存储介质是否应用了 powersafe 覆盖属性。
nolock：nolock 参数是一个布尔查询参数，如果设置此参数，则在回滚日志模式下禁用文件锁定。这对于访问不支持锁定的文件系统上的数据库很有用。注意：如果两个或多个进程写入同一个数据库，并且其中任何一个进程使用 nolock=1，则可能会导致数据库损坏。
immutable：immutable 参数是一个布尔查询参数，指示数据库文件存储在只读介质上。当设置了 immutable 时，SQLite 假设数据库文件无法更改，即使是由具有更高权限的进程，因此数据库以只读方式打开，并且禁用所有锁定和更改检测。注意：如果在实际上会发生更改的数据库文件上设置了 immutable 属性，则可能会导致查询结果不正确，或者出现 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://127.0.0.1/home/fred/data.db	打开数据库文件 "/home/fred/data.db"。
file://darkstar/home/fred/data.db	错误。"darkstar" 不是一个认可的授权。
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db	仅限 Windows：打开 C 盘 fred 桌面上的 "data.db" 文件。请注意，此示例中的 %20 转义不是严格必需的 - URI 文件名中可以使用空格字符。
file:data.db?mode=ro&cache=private	以只读方式打开当前目录中的 "data.db" 文件。无论默认情况下是否启用了共享缓存模式，都使用私有缓存。
file:/home/fred/data.db?vfs=unix-dotfile	打开 "/home/fred/data.db" 文件。使用特殊 VFS "unix-dotfile"，它使用点文件代替 posix 咨询锁定。
file:data.db?mode=readonly	错误。"readonly" 不是 "mode" 参数的有效选项。使用 "ro" 代替："file:data.db?mode=ro"。

URI 十六进制转义序列 (%HH) 在 URI 的路径和查询组件中受支持。十六进制转义序列由一个百分号 - "%" - 后跟两个十六进制数字组成，用于指定一个八位字节值。在解释 URI 文件名的路径或查询组件之前，它们将使用 UTF-8 编码，所有十六进制转义序列将被替换为包含对应八位字节的单个字节。如果此过程生成无效的 UTF-8 编码，则结果未定义。

Windows 用户注意事项：sqlite3_open() 和 sqlite3_open_v2() 的文件名参数使用的编码必须是 UTF-8，而不是当前定义的任何代码页。包含国际字符的文件名必须在传递给 sqlite3_open() 或 sqlite3_open_v2() 之前转换为 UTF-8。

Windows Runtime 用户注意事项：必须在调用 sqlite3_open() 或 sqlite3_open_v2() 之前设置临时目录。否则，需要使用临时文件的各种功能可能会失败。

另请参阅：sqlite3_temp_directory

另请参阅对象、常量和函数列表。