SQLite load_extension() 函数使用指南

SQLite load_extension() 是 SQLite 提供的动态扩展库加载函数。通过调用该函数，数据库连接可以在运行时动态加载编译好的 C/C++ 共享库（Linux 上的 .so、macOS 上的 .dylib 或 Windows 上的 .dll），从而为 SQLite 注入自定义标量函数、聚合函数、全文搜索分词器（如 jieba 扩展）或空间地理扩展（如 SpatiaLite）。

这种机制使 SQLite 保持了轻量精简的核心体积，同时赋予其几乎无上限的系统扩展能力。

SQLite `load_extension()` 语法

这里是 SQLite load_extension() 函数的标准语法：

load_extension(file [, entry_point])

参数

file: 必需的。目标编译扩展库的相对路径或绝对物理路径。若未指定扩展名，SQLite 会尝试依据当前操作系统自动补齐（例如 .dylib 或 .so）。
entry_point: 可选的。动态链接库中导出的初始化入口函数名称。如果省略该参数，SQLite 默认使用 sqlite3_extension_init 作为默认入口函数。

返回值与安全机制

成功加载扩展库后，load_extension() 函数返回 NULL。
如果找不到文件、权限不足或入口符号错误，将直接抛出运行时异常并中断查询。
安全门禁：为了防范恶意 SQL 注入执行任意原生代码，SQLite 默认在所有连接中禁用动态扩展加载功能。必须在客户端驱动程序中先调用底层 API sqlite3_enable_load_extension() 显式开启权限，或在 SQLite CLI 交互式终端中通过 .load 执行。

SQLite `load_extension()` 示例

以下示例演示扩展库的加载与调用方式。

基本加载与调用扩展函数

假设我们拥有一个编译好的数学扩展库 math_ext：

-- 1. 加载当前目录下的动态扩展库
SELECT load_extension('./math_ext');

-- 2. 使用扩展库中注册的新数学函数（例如高精度平方根或正弦）
SELECT ext_sqrt(2.0) AS root_two;

输出：

root_two        
----------------
1.4142135623731

显式指定入口初始化函数

当同一个动态链接库中封装了多个不同模块时，可以显式声明初始化符号：

-- 指定自定义入口点 my_custom_init
SELECT load_extension('/usr/local/lib/sqlite/libtext_tools.so', 'my_custom_init');

输出：

load_extension('/usr/local/lib/sqlite/libtext_tools.so', 'my_custom_init')
------------------------------------------------------------------------
NULL

安全受限时的典型报错

如果应用程序尚未在底层连接上开启 sqlite3_enable_load_extension，执行该命令将直接被安全策略拦截：

Error: not authorized to load extensions

结论

load_extension() 是构建高性能轻量级嵌入式扩展的核心技术。
在多租户或接受外部未经清洗 SQL 输入的 Web 环境中，务必保持扩展加载功能处于默认关闭状态，杜绝代码执行风险。
编译扩展时，应确保使用的 SQLite 接口头文件（sqlite3ext.h）与宿主环境运行时版本保持兼容。

SQLite load_extension() 语法

参数