打开一个新的数据库连接

Small. Fast. Reliable.
Choose any three.

SQLite C接口

打开一个新的数据库连接

int sqlite3_open（
  const char *文件名，/ *数据库文件名（UTF-8）* /
  sqlite3 ** ppDb / * OUT：SQLite数据库句柄* /
）;
int sqlite3_open16（
  const void *文件名，/ *数据库文件名（UTF-16）* /
  sqlite3 ** ppDb / * OUT：SQLite数据库句柄* /
）;
int sqlite3_open_v2（
  const char *文件名，/ *数据库文件名（UTF-8）* /
  sqlite3 ** ppDb，/ * OUT：SQLite数据库句柄* /
  int标志，/ *标志* /
  const char * zVfs / *要使用的VFS模块的名称* /
）;

这些例程打开由filename参数指定的SQLite数据库文件。文件名参数对于sqlite3_open（）和sqlite3_open_v2（）解释为UTF-8，对于sqlite3_open16（）则以本机字节顺序解释为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_READONLY: 数据库以只读模式打开。如果数据库尚不存在，则返回错误。
SQLITE_OPEN_READWRITE: 如果可能，将打开数据库以进行读取或写入，或者仅在文件受操作系统写保护的情况下才读取数据库。无论哪种情况，数据库都必须已经存在，否则将返回错误。
SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE: 将打开数据库以供读取和写入，如果数据库尚不存在，则会创建该数据库。这是始终用于sqlite3_open（）和sqlite3_open16（）的行为。

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

SQLITE_OPEN_URI

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

SQLITE_OPEN_MEMORY

该数据库将作为内存数据库打开。如果启用了共享缓存模式，则为共享缓存而用“文件名”自变量命名数据库，但否则将忽略“文件名”。

SQLITE_OPEN_NOMUTEX

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

SQLITE_OPEN_FULLMUTEX

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

SQLITE_OPEN_SHAREDCACHE

将打开启用共享缓存的数据库，从而覆盖sqlite3_enable_shared_cache（）提供的默认共享缓存设置。

SQLITE_OPEN_PRIVATECACHE

打开数据库时禁用了共享缓存，将覆盖sqlite3_enable_shared_cache（）提供的默认共享缓存设置。

SQLITE_OPEN_NOFOLLOW

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

如果sqlite3_open_v2（）的第三个参数不是上面显示的必需组合之一，可以选择与其他SQLITE_OPEN_ *位组合，则该行为是不确定的。

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

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

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

URI文件名

如果启用了URI文件名解释，并且filename参数以“ file：”开头，则文件名将被解释为URI。如果在sqlite3_open_v2（）的第三个参数中设置了SQLITE_OPEN_URI标志，或者已使用带有sqlite3_config（）方法的SQLITE_CONFIG_URI选项或通过SQLITE_USE_URI编译时选项在全局范围内启用了SQLITE_OPEN_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：模式参数可以设置为“ ro”，“ rw”，“ rwc”或“ memory”。尝试将其设置为任何其他值是一个错误。如果指定“ ro”，则打开数据库以进行只读访问，就像在sqlite3_open_v2（）的第三个参数中设置了SQLITE_OPEN_READONLY标志一样。如果将模式选项设置为“ rw”，则将打开数据库以进行读写（但不创建）访问，就好像已设置了SQLITE_OPEN_READWRITE（但未设置SQLITE_OPEN_CREATE）一样。值“ rwc”等效于设置SQLITE_OPEN_READWRITE和SQLITE_OPEN_CREATE。如果将模式选项设置为“内存”，则为纯内存数据库从不读取或写入磁盘。为mode参数指定的值限制比第三个参数传递给sqlite3_open_v2（）的标志所指定的限制要小，这是错误的。
cache：cache参数可以设置为“ shared”或“ private”。将其设置为“共享”等效于将传递给sqlite3_open_v2（）的flags参数中的SQLITE_OPEN_SHAREDCACHE位置1。将缓存参数设置为“专用”等效于将SQLITE_OPEN_PRIVATECACHE位置1。如果使用sqlite3_open_v2（）且URI文件名中包含“ cache”参数，则其值将覆盖通过设置SQLITE_OPEN_PRIVATECACHE或SQLITE_OPEN_SHAREDCACHE标志所请求的任何行为。
psow：psow参数指示 powersafe overwrite属性是否适用于数据库文件所在的存储介质。
nolock：nolock参数是一个布尔查询参数，如果设置该参数将禁用回滚日志模式下的文件锁定。这对于访问不支持锁定的文件系统上的数据库很有用。警告：如果两个或多个进程写入同一数据库，并且其中任何一个进程使用nolock = 1，则可能导致数据库损坏。
immutable：immutable参数是一个布尔查询参数，它指示数据库文件存储在只读介质上。设置不可变后，SQLite假定即使具有更高特权的进程也无法更改数据库文件，因此该数据库以只读方式打开，并且所有锁定和更改检测均被禁用。警告：在实际上发生更改的数据库文件上设置不可变属性可能会导致错误的查询结果和/或SQLITE_CORRUPT错误。另请参阅：SQLITE_IOCAP_IMMUTABLE。

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

URI文件名示例

URI文件名	结果
文件：data.db	在当前目录中打开文件“ data.db”。
文件：/home/fred/data.db 文件：///home/fred/data.db 文件：//localhost/home/fred/data.db	打开数据库文件“ /home/fred/data.db”。
文件：//darkstar/home/fred/data.db	一个错误。“暗黑之星”不是公认的权威。
文件：/// C：/Documents%20and%20Settings/fred/Desktop/data.db	仅限Windows：在驱动器C：的fred桌面上打开文件“ data.db”。请注意，在此示例中转义％20并非绝对必要-可以在URI文件名中原样使用空格字符。
文件：data.db？mode = ro＆cache = private	在当前目录中打开文件“ data.db”以进行只读访问。无论默认情况下是否启用共享缓存模式，都应使用专用缓存。
文件：/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的路径和查询组件支持URI十六进制转义序列（％HH）。十六进制转义序列由一个百分号-“％”-后面紧跟两个指定十六进制值的十六进制数字。在解释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（）之前设置临时目录。否则，要求使用临时文件的各种功能可能会失败。

另请参见：sqlite3_temp_directory

另请参见对象，常量和函数的列表。