SQLite运行时可加载扩展(三十五）

返回：SQLite—系列文章目录

上一篇:SQLite轻量级会话扩展（三十四）

1. 概述

SQLite 能够在运行时加载扩展（包括新的应用程序定义的 SQL 函数、整理序列、虚拟表和 VFS）。此功能允许开发扩展代码和与应用程序分开测试，然后加载根据需要。

扩展也可以与应用程序静态链接。下面显示的代码模板将像静态一样工作链接扩展，因为它作为运行时可加载扩展，除了您应该提供入口点函数（“sqlite3_extension_init”）如果应用程序包含以下内容，则使用其他名称以避免名称冲突两个或多个扩展。

2. 加载扩展

SQLite 扩展是共享库或 DLL。要加载它，您需要需要向 SQLite 提供包含共享库或 DLL 以及用于初始化扩展的入口点。在 C 代码中，此信息是使用 sqlite3_load_extension() API 提供的。请参阅有关此内容的文档例程以获取更多信息。

请注意，不同的操作系统使用不同的文件名其共享库的后缀。Windows 使用“.dll”，Mac 使用 “.dylib”，除 Mac 外的大多数 Unix 都使用“.so”。如果你想使你的代码可移植，你可以从共享中省略后缀将自动添加库文件名和相应的后缀通过 sqlite3_load_extension() 接口。

还有一个可用于加载扩展的 SQL 函数：load_extension(X，Y)。它的工作方式与 sqlite3_load_extension() C 接口类似。

加载扩展的两种方法都允许您指定扩展的入口点的名称。您可以将此参数留空 - 传入 sqlite3_load_extension() C 语言接口的 NULL 指针或省略 load_extension() SQL 接口的第二个参数 - 扩展加载器逻辑将尝试找出入口点靠它自己。它将首先尝试通用扩展名 “sqlite3_extension_init”。如果这不起作用，它会构造一个使用模板“sqlite3_X_init”的入口点，其中 X 被替换与文件名中每个 ASCII 字符的小写等效值在最后一个“/”之后和第一个“.”之前省略前三个字符（如果它们恰好是“lib”）。因此，例如，如果文件名为“/usr/lib/libmathfunc-4.8.so”，则为入口点名称将是“sqlite3_mathfunc_init”。或者，如果文件名是 “./SpellFixExt.dll”，则将调用入口点 “sqlite3_spellfixext_init”。

出于安全原因，扩展加载默认处于关闭状态。为了使用 C 语言或 SQL 扩展加载函数，必须首先使用

 sqlite3_db_config(db，SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION，1，NULL)

启用扩展加载应用程序中的 C 语言 API。

在命令行 shell 中，可以使用 “.load” 点命令。例如：

.load ./YourCode

请注意，命令行 shell 程序已启用扩展加载（通过调用 sqlite3_enable_load_extension（）接口作为其设置的一部分），因此上面的命令无需任何特殊开关、设置或其他复杂情况。

带有一个参数的“.load”命令调用 sqlite3_load_extension（）将 zProc 参数设置为 NULL，导致 SQLite 首先查找名为“sqlite3_extension_init”，然后名为“sqlite3_X_init”的入口点其中“X”派生自文件名。如果扩展有条目点与不同的名称，只需提供该名称作为第二个论点。例如：

.load ./YourCode nonstandard_entry_point

3. 编译可加载扩展

可加载的扩展是 C 代码。要编译它们，请执行以下操作最像 UNIX 的操作系统，通常的命令是这样的：

gcc -g -fPIC -shared YourCode.c -o YourCode.so

Mac 是类似 unix 的，但它们不遵循通常的共享库约定。要在 Mac 上编译共享库，请使用类似这：

gcc -g -fPIC -dynamiclib YourCode.c -o YourCode.dylib

如果在尝试加载库时收到错误消息这说“Mach-O，但架构错误”，那么您可能需要添加命令行选项“-arch i386”或“arch x86_64”到 gcc，具体取决于关于如何构建应用程序。

若要使用 MSVC 在 Windows 上编译，请使用类似于以下内容的命令通常可以：

cl YourCode.c -link -dll -out:YourCode.dll

要使用 MinGW 为 Windows 编译，命令行就像它一样适用于 UNIX，但输出文件后缀更改为“.dll”，并且省略了 -fPIC 参数：

gcc -g -shared YourCode.c -o YourCode.dll

4. 对可加载扩展进行编程

模板可加载扩展包含以下三个元素：

使用源顶部的“#include < sqlite3ext.h>” 代码文件，而不是“#include < sqlite3.h>”。
将宏“SQLITE_EXTENSION_INIT1”单独放在一行上紧接在“#include < sqlite3ext.h>”行之后。
添加一个扩展加载入口点例程，如下所示内容如下：
```
#ifdef _WIN32
__declspec(dllexport)
#endif
int sqlite3_extension_init( /* <== Change this name, maybe */
  sqlite3 *db, 
  char **pzErrMsg, 
  const sqlite3_api_routines *pApi
){
  int rc = SQLITE_OK;
  SQLITE_EXTENSION_INIT2(pApi);
  /* insert code to initialize your extension here */
  return rc;
}
```
您可以很好地将入口点的名称自定义为对应于您将要生成的共享库的名称，而不是使用通用的“sqlite3_extension_init”名称。给您的扩展自定义入口点名称将使您能够静态地在没有链接器的情况下将两个或多个扩展链接到同一程序中冲突（如果您以后决定使用静态链接而不是运行时）连接。如果您的共享库最终被命名为“YourCode.so”或编译器示例中显示的“YourCode.dll”或“YourCode.dylib” ，那么正确的入口点名称将是 “sqlite3_yourcode_init”。

这是一个完整的模板扩展，您可以复制/粘贴要开始使用，请执行以下操作：

/* Add your header comment here */
#include <sqlite3ext.h> /* Do not use <sqlite3.h>! */
SQLITE_EXTENSION_INIT1

/* Insert your extension code here */

#ifdef _WIN32
__declspec(dllexport)
#endif
/* TODO: Change the entry point name so that "extension" is replaced by
** text derived from the shared library filename as follows:  Copy every
** ASCII alphabetic character from the filename after the last "/" through
** the next following ".", converting each character to lowercase, and
** discarding the first three characters if they are "lib".
*/
int sqlite3_extension_init(
  sqlite3 *db, 
  char **pzErrMsg, 
  const sqlite3_api_routines *pApi
){
  int rc = SQLITE_OK;
  SQLITE_EXTENSION_INIT2(pApi);
  /* Insert here calls to
  **     sqlite3_create_function_v2(),
  **     sqlite3_create_collation_v2(),
  **     sqlite3_create_module_v2(), and/or
  **     sqlite3_vfs_register()
  ** to register the new features that your extension adds.
  */
  return rc;
}

4.1. 示例扩展

完整且可加载扩展的许多示例可以是在 ext/misc 子目录的 SQLite 源代码树中看到。该目录中的每个文件都是一个单独的扩展名。文档由文件上的标题注释提供。以下是对 ext/misc 子目录：

卡雷.c — carray 表值函数的实现。
压缩.c — 实现应用程序定义的 SQL 函数 compress()和 uncompress()对文本或 blob 内容进行 zLib 压缩。
json1.c — JSON SQL 函数和表值函数的实现。这是一个更大、更复杂的扩展。
memvfs.c — 实现将所有内容存储在内存中的新 VFS。
rot13.c — rot13（） SQL 函数的实现。这是一个非常简单的扩展函数示例并可用作创建新扩展的模板。
系列.c — 实现generate_series虚拟表和表值函数。这是一个相对简单的示例虚拟表实现，可以作为编写模板新的虚拟表。

其他更复杂的扩展可以在子文件夹中找到在 ext/ 下，除 ext/misc/ 外。

5. 持久可加载扩展

可加载扩展的默认行为是卸载它当最初调用 sqlite3_load_extension（）的数据库连接关闭时，从进程内存中。（换言之，xDlClose 方法的 sqlite3_vfs 对象在数据库时为所有扩展调用连接关闭。但是，如果初始化过程返回 SQLITE_OK_LOAD_PERMANENTLY 而不是 SQLITE_OK，则扩展将未卸载（不会调用 xDlClose），并且扩展将保留无限期地在进程内存中。SQLITE_OK_LOAD_PERMANENTLY回归 value 对于想要注册新 VFS 的扩展非常有用。

澄清一下：初始化函数返回的扩展 SQLITE_OK_LOAD_PERMANENTLY在数据库之后继续存在于内存中连接关闭。但是，扩展不会自动进行注册到后续数据库连接。这使它成为可能加载实现新 VFS 的扩展。持久加载和注册实现新 SQL 的扩展函数、整理序列和/或虚拟表，使得那些添加的功能可用于所有后续数据库连接，然后，初始化例程还应该在将注册这些服务的子函数上调用 sqlite3_auto_extension（）。

vfsstat.c 扩展显示一个可加载扩展的示例，该扩展永久注册两者新的 VFS 和新的虚拟表。该扩展中的 sqlite3_vfsstat_init（）初始化例程仅调用一次，当首先加载扩展。它注册了新的“vfslog”VFS 一次，它返回SQLITE_OK_LOAD_PERMANENTLY，以便使用的代码要实现“vfslog”，VFS 将保留在内存中。初始化例程还在指向“vstatRegister()”的指针上调用 sqlite3_auto_extension（函数，以便所有后续数据库连接都将调用 “vstatRegister()”函数，因此注册 “vfsstat”虚拟表。

6. 静态链接运行时可加载扩展

完全相同的源代码可用于运行时可加载共享库或 DLL，并作为与应用。这提供了灵活性，并允许你重复使用相同的内容以不同的方式编写代码。

要静态链接扩展，只需添加 -DSQLITE_CORE 编译时选项。SQLITE_CORE宏会导致SQLITE_EXTENSION_INIT1 并将宏SQLITE_EXTENSION_INIT2为无操作。然后修改你的应用程序直接调用入口点，传入 NULL 指针作为第三个“pApi”参数。

使用入口点名称尤为重要基于扩展名文件名，而不是通用 “sqlite3_extension_init”入口点名称，如果将静态链接两个或多个扩展。如果使用通用名称，则有将是同一符号的多个定义，并且链接将失败。

如果要在应用程序中打开多个数据库连接，而不是调用每个数据库的扩展入口点连接另外，您可能需要考虑使用 sqlite3_auto_extension（）接口来注册您的扩展和使它们在每个数据库连接时自动启动已打开。您只需注册每个扩展一次，就可以在 main() 例程的开头附近执行此操作。使用 sqlite3_auto_extension（）接口注册扩展使您的扩展就像它们内置在核心 SQLite 中一样 - 它们每当打开新的数据库连接时，自动存在无需初始化。只要确保完成任何您需要先使用 sqlite3_config（）完成的配置注册扩展，因为 sqlite3_auto_extension（）接口隐式调用 sqlite3_initialize（）。

7. 实施细节

SQLite 使用 sqlite3_vfs 对象的 xDlOpen()、xDlError()、xDlSym()和 xDlClose()方法。这些方法是使用 unix 上的 dlopen()库（这解释了为什么 SQLite 通常需要链接到 Unix 系统上的“-ldl”库）并在 Windows 上使用 LoadLibrary()API。在自定义 VFS 中不寻常的系统，这些方法都可以省略，在这种情况下运行时扩展加载机制将不起作用（尽管您仍然可以静态链接扩展代码，假设入口指针是唯一命名的）。 SQLite可以用SQLITE_OMIT_LOAD_EXTENSION进行编译，以省略扩展加载代码从构建。