Opening A New Database Connection

Opening A New Database Connection

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 */

这些例程按照filename参数指定的方式打开SQLite数据库文件。对于sqlite3_open16()，文件名参数被解释为sqlite3_open()和sqlite3_open_v2()的UTF-8，以及本地字节顺序的UTF-16。数据库连接句柄通常以* ppDb的形式返回，即使发生错误。唯一的例外是，如果SQLite无法分配内存来保存sqlite3对象，则NULL将被写入* ppDb而不是指向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_NOMUTEX，SQLITE_OPEN_FULLMUTEX，SQLITE_OPEN_SHAREDCACHE，SQLITE_OPEN_PRIVATECACHE和/或SQLITE_OPEN_URI标志组合使用：

SQLITE_OPEN_READONLY数据库以只读模式打开。如果数据库尚不存在，则会返回错误.SQLITE_OPEN_READWRIT如果可能，打开数据库进行读取和写入操作，或者仅在操作系统对文件进行写保护时才读取数据库。无论哪种情况，数据库都必须已经存在，否则会返回错误.SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATEThe打开数据库以进行读写操作，并在数据库尚不存在时创建。这是始终用于sqlite3_open()和sqlite3_open16()的行为。

如果sqlite3_open_v2()的第三个参数不是上面显示的组合之一（可选地与其他SQLITE_OPEN_ *位组合），那么行为是未定义的。

如果设置了SQLITE_OPEN_NOMUTEX标志，那么只要在编译时或开始时尚未设置单线程模式，数据库连接就会以多线程线程模式打开。如果设置了SQLITE_OPEN_FULLMUTEX标志，则数据库连接将以串行化线程模式打开，除非先前在编译时或启动时选择了单线程。无论使用sqlite3_enable_shared_cache（）是否启用共享缓存，SQLITE_OPEN_SHAREDCACHE标志都会导致数据库连接有资格使用共享缓存模式。即使启用了SQLITE_OPEN_PRIVATECACHE标志，数据库连接也不会参与共享缓存模式。

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

如果文件名为“：memory：”，则为该连接创建一个专用的临时内存数据库。当数据库连接关闭时，这个内存数据库将会消失。未来版本的SQLite可能会使用以“：”字符开头的其他特殊文件名。建议当数据库文件名实际上以“：”字符开始时，应该在文件名前添加一个路径名，例如“./”以避免含糊不清。

如果文件名是空字符串，则将创建一个专用的临时磁盘数据库。一旦数据库连接关闭，该私有数据库将自动删除。

URI文件名

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

根据RFC 3986分析URI文件名。如果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()的第四个参数传递的值。

• 模式：模式参数可以设置为“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。如果模式选项设置为“内存”，则使用永不从磁盘读取或写入的纯内存数据库。

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

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

• nolock：nolock参数是一个布尔查询参数，如果设置为禁用回滚日志模式下的文件锁定。这对于访问不支持锁定的文件系统上的数据库很有用。小心：如果两个或更多进程写入同一个数据库，并且其中任何一个进程使用nolock = 1，则可能导致数据库损坏。

• immutable：不可变参数是一个布尔型查询参数，表示数据库文件存储在只读介质上。当设置不可变时，SQLite会假定数据库文件不能更改，即使是具有更高特权的进程也是如此，因此数据库以只读方式打开，并且禁用所有锁定和更改检测。警告：在实际上更改的数据库文件上设置不可变属性可能会导致错误的查询结果和/或SQLITE_CORRUPT错误。另请参阅：SQLITE_IOCAP_IMMUTABLE。

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

URI文件名示例

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

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

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