libSQL 源码详解：sqlite3-jni，在 Java 中一比一映射 SQLite3 C API
发布时间：2026/9/13 12:19:43 作者：尧图编辑部 阅读量：1,286
libSQL 源码详解sqlite3-jni在 Java 中一比一映射 SQLite3 C API【免费下载链接】libsqllibSQL is a fork of SQLite that is both Open Source, and Open Contributions.项目地址: https://gitcode.com/GitHub_Trending/li/libsqlsqlite3-jni 是 libSQL 仓库内libsql-sqlite3源码树自带的一套 Java Native InterfaceJNI绑定目标是把 sqlite3 的 C API 以「尽可能一比一」的方式原样暴露给 Java 开发者让 SQLite 官方 C 文档几乎可以当作 JNI 版的文档直接阅读。本文将基于 ext/jni/README.md 并结合仓库内真实源码完整讲解该绑定的设计目标、Hello World、构建流程、与 C API 的映射规则以及 Collation 与 UDF 等回调型 API 在 Java 中的重映射方式帮助你在自己的 Java 项目中直接复用这套 C 风格 API。前置说明本 README 明确给出 FOREWARNING——该子项目仍处于快速开发阶段API 可能随时变化随 3.43 版本发布的 JNI 绑定属于 tech preview技术预览在正式定稿之前不要依赖其 API 细节定稿后将提供强向后兼容保证。阅读本文时请留意这一前提。一、项目定位与设计目标该目录存放的是 sqlite3 API 的 Java Native Interface 绑定。核心设计目标README 原话如下C API 的一比一近似映射在跨语言语义允许的范围内将 C API 以 1-to-1(-ish) 的方式映射到 Java紧邻目标是尽可能让 C 文档 直接适用于 JNI 绑定该外部链接仅作为背景说明不构成仓库证据。支持 Java 82014 年发布及更高版本。环境无关凡是 Java 与 SQLite3 都能运行的地方绑定都应能工作。除 JDK 外零第三方依赖包括不引入特定 IDE 与工具链的构建级依赖欢迎为任意环境补充构建文件前提是它们互不干扰、不成为 SQLite 维护者的负担。同时 README 明确列出Non-goals非目标不提供高层 OO 包装 API——客户端可以基于这套 C 风格 API 自行封装。虚拟表Virtual Table大概率不支持因为将其塞进 Java 需要海量胶水代码。不支持混合模式客户端既通过 Java 侧 API、又通过自有 native 代码访问 SQLite因为这会是本绑定与混合模式客户端之间潜在误交互的雷区。从源码结构看绑定代码位于 ext/jni/src/org/sqlite/jni 下分为capiC 风格 API 的直接映射、wrapper1一个轻量 Java 风格包装层、fts5FTS5 定制扩展与tester等子包C 侧胶水代码在 ext/jni/src/c/sqlite3-jni.c 与机器生成的 ext/jni/src/c/sqlite3-jni.h 中。二、Hello World打开一个内存数据库README 给出的最小可运行示例完整如下import org.sqlite.jni.*; import static org.sqlite.jni.capi.CApi.*; ... final sqlite3 db sqlite3_open(:memory:); try { final int rc sqlite3_errcode(db); if( 0 ! rc ){ if( null ! db ){ System.out.print(Error opening db: sqlite3_errmsg(db)); }else{ System.out.print(Error opening db: rcrc); } ... handle error ... } // ... else use the db ... }finally{ // ALWAYS close databases using sqlite3_close() or sqlite3_close_v2() // when done with them. All of their active statement handles must // first have been passed to sqlite3_finalize(). sqlite3_close_v2(db); }几个值得注意的实现细节均可在仓库源码中得到印证sqlite3是一个「指针包装器」而非连接对象。查看 sqlite3.java它继承自NativePointerHoldersqlite3并实现AutoCloseable其 Javadoc 明确说明「这些包装器并不拥有其关联的指针只是通过 JNI 在 Java 与 C 之间以类型安全的方式传递它」。它的close()方法内部直接调用CApi.sqlite3_close_v2(this)。CApi是全部绑定的唯一入口。查看 CApi.java 第 86-90 行CApi是final类其静态初始化块执行System.loadLibrary(sqlite3-jni)——这就是为什么运行时必须保证libsqlite3-jni.so或其他平台对应的 DLL能被 JVM 通过-Djava.library.path...找到。结果码语义与 C 完全一致sqlite3_open、sqlite3_errcode、sqlite3_errmsg等函数的返回码与 C API 一一对应SQLITE_OK为 0等等这些常量全部以long形式声明在机器生成的sqlite3-jni.h中例如SQLITE_OK 0L、SQLITE_ERROR 1L、SQLITE_BUSY 5L、SQLITE_ROW 100L、SQLITE_DONE 101L。三、构建与测试README 指出标准构建假定类 Linux 环境需要GNU Make支持 Java 8 或更高版本的 JDK现代 C 编译器gcc 和 clang 均可最简单的构建流程$ export JAVA_HOME/path/to/jdk/root $ make $ make test $ make cleanmake jar可生成 jar 发行包但jar 不包含二进制 DLL 文件——每个目标平台都需要单独编译各自的 DLL。仓库中的 GNUmakefile 为我们揭示了远比 README 更丰富的构建细节JDK 探测JAVA_HOME ? $(HOME)/jdk/currentJDK_HOME ? $(JAVA_HOME)若$(JDK_HOME)不存在会直接报错set JDK_HOME to the top-most dir of your JDK installation.。jar/java/javac/javadoc 全部取自$(JDK_HOME)/bin/。JNI 头文件路径编译 C 侧时除$(JDK_HOME)/include外还通过$(patsubst ...)自动把$(JDK_HOME)/include/*下的平台子目录如linux加入头文件搜索路径-I。可调编译开关opt.threadsafe默认 1、opt.fatal-oom默认 1、opt.debug默认 1开启-DSQLITE_DEBUG -g关闭时用-Os、opt.metrics默认 1对应-DSQLITE_JNI_ENABLE_METRICS。基础宏包括-DSQLITE_THREADSAFE...、-DSQLITE_TEMP_STORE2、-DSQLITE_USE_URI1、-DSQLITE_OMIT_LOAD_EXTENSION、-DSQLITE_OMIT_DEPRECATED、-DSQLITE_OMIT_SHARED_CACHE。可选扩展宏opt.extras1时追加-DSQLITE_ENABLE_RTREE、-DSQLITE_ENABLE_PREUPDATE_HOOK、-DSQLITE_ENABLE_COLUMN_METADATA、-DSQLITE_ENABLE_EXPLAIN_COMMENTS、-DSQLITE_ENABLE_NORMALIZE、-DSQLITE_ENABLE_SQLLOG、-DSQLITE_ENABLE_STMTVTAB及 dbpage/dbstat/bytecode vtab 等enable.fts51时追加-DSQLITE_ENABLE_FTS5并把 fts5 相关 Java 文件纳入编译GNUmakefile 注释特别提醒该开关会影响已签入的sqlite3-jni.h内容剥离 fts5 的改动不应被签入。JNI 头文件的生成机制sqlite3-jni.h是机器生成的由javac -h针对含 JNI 声明的 Java 文件CApi.java、SQLTester.java以及启用 fts5 时的Fts5ExtensionApi.java、fts5_api.java、fts5_tokenizer.java生成各org_sqlite_jni_*.h再拼接为最终头文件。测试目标make test实际执行test-one与test-mt——test-one运行org.sqlite.jni.capi.Tester1和org.sqlite.jni.wrapper1.Tester2test-mt以-t 7 -r 50 -shuffle参数做 7 线程 × 50 轮的随机顺序多线程测试。另有test-sqllog带-sqllog选项与tester驱动src/tests/*.test脚本。JVM 参数统一带-ea启用断言与-Djava.library.path$(dir.bld.c)。多线程模式矩阵测试make multitest会依次用threadsafe0/1/2×oom0/1共 6 种组合编译并跑完整测试集。jar 与发行包make jar生成sqlite3-jni.jar主类为org.sqlite.jni.capi.Tester1并提示运行需要-Djava.library.pathDIR/CONTAINING/libsqlite3-jni.somake dist生成发行 zipsqlite-jni-版本.zip且会警告必须使用 JDK8javac 1.8构建以保证兼容性。javadocmake doc生成 javadoc默认-exclude org.sqlite.jni.fts52023-09-13 起暂不把 fts5 部分纳入公开文档。四、C API 的一比一映射规则4.1 映射哲学README 的核心原则本绑定力求在跨语言语义允许的范围内提供与 C API 文档一致的一比一体验。凡是跨语言语义不允许一比一的地方或一比一映射在 Java 中会显得异常笨拙的地方才会审慎地调整接口所有偏离 C 语义的场合都会明确记录。任何语义偏差无论是增加还是删减都被要求清楚写进文档。Java 侧重载overloads出于易用性绑定会提供接受/返回替代数据形式或提供默认参数值的重载但它们全部是对应 C API 的「薄代理」不引入任何新语义。从 CApi.java 的源码注释可以看到例如sqlite3_result_set(sqlite3_context, int)等价于sqlite3_result_int且sqlite3_result_set()有大量按类型区分的重载。Java 专属能力_java后缀少量新增 API 的名字里都带_javaREADME 给出的示例包括sqlite3_result_java_object()sqlite3_column_java_object()sqlite3_value_java_object()三者合起来实现「把任意 Java 对象从用户自定义 SQL 函数一路传递回调用方」。在 sqlite3-jni.h 中还能看到同类扩展例如sqlite3_bind_java_objectSignature: (JILjava/lang/Object;)I、sqlite3_bind_nio_buffer把java.nio.ByteBuffer直接绑定为 BLOB、sqlite3_jni_supports_nio()、sqlite3_java_uncache_thread()等。Java 的 Modified UTF-8 陷阱CApi.java的类注释专门提醒——SQLite 内部使用标准 UTF-8而 Java 原生使用 UTF-16JNI 的字符串转换用的是「Modified UTF-8MUTF-8」。因此 Java 字符串到标准 UTF-8 的转换必须走String.getBytes(StandardCharsets.UTF_8)接受 C 风格无长度字符串的函数需要自行把 Java 字符串转成以\0结尾的字节数组CApi内用nulTerminateUtf8()私有方法统一处理而带长度参数的函数只要传对长度即可。这点在跨语言边界上极易踩坑值得所有使用者警惕。4.2 Golden Rule垃圾回收无法释放 SQLite 资源这是本绑定最重要的使用纪律README 原文强调所有数据库与预处理语句句柄都必须由客户端代码显式清理有未释放语句句柄的数据库无法关闭。sqlite3_close()在无法关闭时会失败sqlite3_close_v2()则识别这种情况把数据库标记为 zombie僵尸待库检测到所有挂起语句都关闭后再执行终结。Java 垃圾回收不能关闭数据库也不能终结预处理语句——这些必须显式调用 API。合适的类实现了 Java 的AutoCloseable接口因此可以配合 try-with-resources 使用如上面的sqlite3类所示其close()即sqlite3_close_v2。另外在 CApi.java 中还有一条与资源/线程相关的规则每个使用过 SQLite3 JNI API 的线程在结束前都应调用sqlite3_java_uncache_thread()来清理缓存的每线程信息主线程不强制但额外线程不调用会泄漏 C 堆上的缓存条目进而可能持有大量 Java 侧全局引用。4.3 Golden Rule #2回调中严禁抛异常除非……除明确文档化的例外本 API 的所有例程都保留 C 风格语义不允许抛出或传播异常错误信息必须通过结果码或null返回。允许抛出的唯一例外是客户端误用例如在会导致NullPointerException的地方传null。API 会标记不应为 null 的参数但一般不主动防御此类误用部分 C 风格 API 明确把null当作 no-op部分 JNI API 在收到null时会刻意返回错误码而非段错误。客户端定义的回调绝对不允许抛异常除非被非常明确地文档化为 throw-safe。原因在于README 原文所有此类回调都充当 C 函数回调接口的代理而其中一些接口没有错误上报机制——有能力把错误传播回库的回调会把异常转换成对应的 C 级错误信息没有传播能力的回调为了维持 C 风格语义必然要抑制异常可能只在调试通道输出。在源码中可以找到对应佐证AggregateFunction.xStep()的 Javadoc 写的是「如果此函数抛出异常异常不会被传播可能向调试通道发出警告」AggregateFunction.xFinal()与ScalarFunction.xFunc()则是「异常会被转换为sqlite3_result_error()」——前者没有错误传播通道后者有处理策略截然不同。五、笨拙结构的重映射Collation 与 UDF有些 C 构造一比一搬进 Java 会非常别扭因为它们把 C 的世界观强塞进 Java 迥异的模型里。README 用「我们先试过一比一真的很别扭」的口吻详解了以下几类重映射。5.1 自定义排序规则Custom CollationsC API 原形README 原文// C: int sqlite3_create_collation(sqlite3 * db, const char * name, int eTextRep, void *pUserData, int (*xCompare)(void*,int,void const *,int,void const *)); int sqlite3_create_collation_v2(sqlite3 * db, const char * name, int eTextRep, void *pUserData, int (*xCompare)(void*,int,void const *,int,void const *), void (*xDestroy)(void*));C 中pUserData是可选客户端状态通过「外部传参」的方式传给xCompare()/xDestroy()。如果照搬到 Java就会出现 README 所说的两处别扭(A) 回调与状态是两个截然不同的对象(B) 状态要单独提供这与 Java 的习语格格不入。因此绑定改为如下 Java 接口README 原文int sqlite3_create_collation(sqlite3 db, String name, int eTextRep, SomeCallbackType collation);其中Collation类提供必须实现的抽象call()方法与可覆写的 no-opxDestroy()方法使用起来非常「Java」int rc sqlite3_create_collation(db, mycollation, SQLITE_UTF8, new SomeCallbackType(){ // Required comparison function: Override public int call(byte[] lhs, byte[] rhs){ ... } // Optional finalizer function: Override public void xDestroy(){ ... } // Optional local state: private String localState1 This is local state. There are many like it, but this one is mine.; private MyStateType localState2 new MyStateType(); ... });仓库中的 CollationCallback.java 印证了这一设计它继承CallbackProxy与XDestroyCallback核心方法是int call(NotNull byte[] lhs, NotNull byte[] rhs)要求按memcmp()语义返回比较结果与void xDestroy()排序规则被销毁时调用可覆写以做自定义清理。README 还特别说明了几点如果需要完全可以把状态通过闭包绑定在调用作用域内而不是塞进 Collation 对象上述改造不丢失、不遮蔽 C API 的任何能力资深用户无需妥协由于新接口同时提供了 v1 与 v2 的能力sqlite3_create_collation_v2()变得多余——覆写xDestroy()即等价于 v2 语义。5.2 用户自定义 SQL 函数UDFsqlite3_create_function()一族 API 重度依赖函数指针来提供客户端回调因此 JNI 绑定必须改接口。Java 侧只有一个核心函数注册入口README 原文int sqlite3_create_function(sqlite3 db, String funcName, int nArgs, int encoding, SQLFunction func);README 中的开放设计问题encoding参数在 Java 中是否还有意义目前未定若无意义将被移除。SQLFunction本身不直接使用而是通过其三个子类实例化README 原文ScalarFunction用单个回调实现简单标量函数AggregateFunction用两个回调实现聚合函数WindowFunction用四个回调实现窗口函数。在仓库源码中可以看到这三者的精确形状SQLFunction.java 是一个空标记接口marker interface注释说明 JNI 层只依赖基类SQLFunction及 UDF 回调接口的方法名与签名客户端甚至可以自建符合公共接口的类。ScalarFunction.java抽象方法xFunc(sqlite3_context cx, sqlite3_value[] args)对应 C 的xFunc抛异常会被转换为sqlite3_result_error()与可覆写的空xDestroy()。AggregateFunction.java抽象方法xStep(sqlite3_context cx, sqlite3_value[] args)与xFinal(sqlite3_context cx)并内嵌PerContextStateT辅助类——它用MapLong, ValueHolderT把sqlite3_context.getAggregateContext()映射到一块客户端自定义类型的「累加器状态」解决同一 SQL 语句中多次调用 UDF如SELECT MYFUNC(A), MYFUNC(B)...时状态归属的难题配套的getAggregateState()首次调用时以初值创建映射与takeAggregateState()在xFinal中取出并清除映射必须配对使用。WindowFunction.java继承AggregateFunctionT额外要求实现xInverse(sqlite3_context cx, sqlite3_value[] args)与xValue(sqlite3_context cx)对应 C APIsqlite3_create_window_function()的回调从而凑齐 README 所说的「四个回调」。README 建议在 Tester1.java 中搜索SQLFunction查看实际用法。该文件本身是一个约 2200 行的反射驱动测试集支持单线程、多线程-t、-r、-shuffle模式并用ManualTest、SingleThreadOnly、RequiresJniNio等注解标记测试的执行约束。5.3 诸如此类And so on...README 最后指出其他接受回调的 API 也采用与上面类似的接口改造例如sqlite3_trace_v2()与sqlite3_update_hook()。尽管签名变了JNI 层仍会尽一切努力提供与 C API 文档一致的语义。从源码目录 capi 中可以数出这些回调接口的完整清单AuthorizerCallback授权器、AutoExtensionCallback自动扩展、BusyHandlerCallback忙处理器、CollationNeededCallback、CommitHookCallback提交钩子、ConfigLogCallback、ConfigSqlLogCallback、PreupdateHookCallbackpreupdate 钩子对应-DSQLITE_ENABLE_PREUPDATE_HOOK、ProgressHandlerCallback进度处理器、RollbackHookCallback回滚钩子、TraceV2Callbacksqlite3_trace_v2、UpdateHookCallback更新钩子、PrepareMultiCallback、XDestroyCallback等另有OutputPointer模拟 C 的指针输出参数例如sqlite3_open的sqlite3**第二参数、ValueHolder可修改的值容器与NativePointerHolder原生指针的 Java 包装基类。六、如何继续深入阅读原文档ext/jni/README.md注意其开头的免责声明——API 仍在快速演进。看 C 侧胶水实现sqlite3-jni.c 与机器生成的 sqlite3-jni.h后者含全部结果码、SQLITE_*常量与JNIEXPORT函数签名。看 Java 侧 API 全集CApi.javafinal类静态块System.loadLibrary(sqlite3-jni)。看句柄包装与资源管理sqlite3.java、sqlite3_stmt.java、sqlite3_value.java、sqlite3_context.java、sqlite3_blob.java、sqlite3_backup.java均继承NativePointerHolder并支持AutoCloseable。看测试用例Tester1.javaC 风格 API 测试、Tester2.javawrapper1 包装层测试、TesterFts5.javaFTS5 测试以及脚本驱动测试 src/tests。看构建细节GNUmakefile 与发行构建文件 jar-dist.make。整个绑定是 libSQLSQLite 的开源 fork源码树的一部分SQLite 核心位于 libsql-sqlite3/src上层 Rust 生态libsql、libsql-server、libsql-ffi等可参见仓库根 README.md。【免费下载链接】libsqllibSQL is a fork of SQLite that is both Open Source, and Open Contributions.项目地址: https://gitcode.com/GitHub_Trending/li/libsql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 