Run-Time Loadable Extensions

1.概述

2.加载扩展

3.编译可加载的扩展

4.编程可加载扩展

4.1.示例扩展

5.持久可装载扩展

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

7.实施细节

1. Overview

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

扩展也可以静态链接到应用程序。下面显示的代码模板与静态链接的扩展一样好，因为它可以作为运行时可装载的扩展，除了您应该为入口点函数(“sqlite3_extension_init”)指定不同的名称以避免名称冲突（如果您的应用程序包含两个或更多的扩展。

2. Loading An Extension

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”，则省略前三个字符。所以，例如，如果文件名是“

出于安全原因，默认情况下会关闭扩展加载。为了使用C语言或SQL扩展加载函数，必须先在应用程序中使用sqlite3_db_config(db，SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION，1，NULL)C语言API启用扩展加载。

在命令行shell中，可以使用“.load”dot-command加载扩展。例如：

.load ./YourCode

请注意，命令行shell程序已经为您启用了扩展加载（通过调用sqlite3_enable_load_extension()）接口作为其设置的一部分），因此上述命令无需任何特殊开关，设置或其他复杂操作即可运行。

带有一个参数的“.load”命令调用sqlite3_load_extension()，将zProc参数设置为NULL，从而导致SQLite首先查找名为“sqlite3_extension_init”的入口点，然后查找“x”源自文件名的“sqlite3_X_init”。如果您的扩展名具有不同名称的入口点，则只需提供该名称作为第二个参数即可。例如：

.load ./YourCode nonstandard_entry_point

3. Compiling A Loadable Extension

可加载的扩展名是C代码。为了在大多数类Unix操作系统上编译它们，通常的命令是这样的：

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

Macs是类似unix的，但它们不遵循通常的共享库惯例。要在Mac上编译共享库，请使用如下命令：

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

如果当你尝试加载你的库时，你会得到一个错误消息，指出“mach-o，但是错误的体系结构”，那么你可能需要为gcc添加命令行选项“-arch i386”或“arch x86_64”，这取决于您的应用程序的构建方式。

要使用MSVC在Windows上编译，类似于以下内容的命令通常会起作用：

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

要使用MinGW编译Windows，命令行就像unix一样，只是输出文件后缀更改为“.dll”，省略了-fPIC参数：

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

4. Programming Loadable Extensions

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

#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; } You will do well to customize the name of your entry point to correspond to the name of the shared library you will be generating, rather than using the generic "sqlite3_extension_init" name. Giving your extension a custom entry point name will enable you to statically link two or more extensions into the same program without a linker conflict, if you later decide to use static linking rather than run-time linking. If your shared library ends up being named "YourCode.so" or "YourCode.dll" or "YourCode.dylib" as shown in the compiler examples above, then the correct entry point name would be "sqlite3_yourcode_init". Here is a complete template extension that you can copy/paste to get started:/* 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。示例扩展可以在SQLite源代码树中看到完整和可工作的可载入扩展的很多示例ext / misc子目录。该目录中的每个文件都是一个单独的扩展名。文档由文件头标注释提供。以下是关于ext / misc子目录中一些扩展的简要说明：

carray.c - 实现carray表值函数。

compress.c - 实现应用程序定义的SQL函数compress()和uncompress()，用于对文本或blob内容执行zLib压缩。

json1.c - 实现JSON SQL函数和表值函数。这是一个更大更复杂的扩展。

memvfs.c - 实现存储所有内容的新VFS。

rot13.c - 实现rot13() SQL函数。这是扩展函数的一个非常简单的例子，并且可以用作创建新扩展的模板。

series.c - 实现generate_series虚拟表和表值函数。这是一个虚拟表实现的相对简单的例子，它可以作为编写新虚拟表的模板。

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

5. Persistent Loadable Extensions

可加载扩展的默认行为是，当最初调用sqlite3_load_extension()的数据库连接关闭时，它将从进程内存中卸载。（换句话说，当数据库连接关闭时，会为所有扩展调用sqlite3_vfs对象的xDlUnload方法。）但是，如果初始化过程返回SQLITE_OK_LOAD_PERMANENTLY而不是SQLITE_OK，那么将不会卸载扩展（xDlClose不会被调用）并且扩展名将无限期地保留在进程内存中。对于想要注册新VFS的扩展，SQLITE_OK_LOAD_PERMANENTLY返回值很有用。

6. Statically Linking A Run-Time Loadable Extension

完全相同的源代码可以用于运行时可装入的共享库或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()完成的任何配置，

7. Implementation Details

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

 SQLite is in the Public Domain.