Tabularis插件系统深度解析:JSON-RPC 2.0协议如何让插件支持任意编程语言
Tabularis插件系统深度解析:JSON-RPC 2.0协议如何让插件支持任意编程语言
Tabularis 是一个开源桌面 SQL 工作区,内置 MySQL、PostgreSQL、SQLite 三个数据库驱动,并随附 16 个插件(包括 SQL Server、DuckDB、ClickHouse 和 Redis),还内置了 MCP 服务器、SQL 笔记本和可视化 EXPLAIN。它的 Tabularis 插件系统 基于 JSON-RPC 2.0 协议,让插件可以用任意编程语言编写。本文带你彻底搞懂这套插件机制的设计原理与使用方法。
为什么选 JSON-RPC 2.0:4 个关键优势 🧩
Tabularis 的插件不是"加载进主程序的动态库",而是独立的可执行程序,主程序通过标准输入/输出(stdin/stdout)与它交换 JSON-RPC 2.0 消息。这个设计带来四个好处:
| 优势 | 说明 |
|---|---|
| 🌐 语言无关 | 只要能读 stdin、写 stdout,Rust、Python、Go、Java 统统可以写插件 |
| 🛡️ 崩溃隔离 | 插件进程崩了,主应用照常运行 |
| 📦 独立分发 | 插件单独打包、单独更新,主应用无需重新发版 |
| 📖 协议简单 | 每行一条 JSON 消息,调试时可以拿任意工具(甚至 shell 管道)直接对话 |
📚 完整协议参考文档:PLUGIN_GUIDE.md,这是全部 RPC 方法、能力标志和 UI 插槽的权威清单。
插件生命周期:从扫描到连接
插件的完整生命周期只有 5 步:
- 启动扫描:Tabularis 启动时扫描插件目录,查找带
.tabularium清单(旧版为manifest.json)的子目录; - 读取清单:解析清单中的能力(capabilities)与数据类型(data_types);
- 注册驱动:插件出现在"数据库类型"下拉列表中;
- 按需启动:当你用该驱动新建连接时,Tabularis 才真正 spawn 可执行文件,开始发送 JSON-RPC 请求;
- 进程复用:同一会话内的所有操作复用同一个插件进程。
通信协议:每行一条 JSON
- 请求:Tabularis 向插件 stdin 写入一条 JSON-RPC 请求,以换行符
\n分隔; - 响应:插件处理后向 stdout 写回一条 JSON-RPC 响应,同样以
\n结尾; - 日志:插件的 stderr 输出会被 Tabularis 继承记录,不干扰 RPC 通道。
一个真实的请求长这样(来自 PLUGIN_GUIDE.md 第 4 节):
{
"jsonrpc": "2.0",
"method": "get_tables",
"params": {
"params": { "driver": "duckdb", "database": "/path/to/my.duckdb" },
"schema": null
},
"id": 1
}
对应成功响应:
{
"jsonrpc": "2.0",
"result": [ { "name": "users", "schema": "main", "comment": null } ],
"id": 1
}
协议类型定义见 rpc.rs,插件管理器的主流程在 manager.rs。
任意编程语言:一个协议打通所有生态 🐍🦀
协议层面没有任何语言运行时绑定——这是"任意编程语言"承诺的核心。官方在 plugins/ 目录中已经给出了三种语言的真实案例:
- Rust 骨架:PLUGIN_GUIDE.md 第 6 节提供了一个最小可运行骨架:主循环读 stdin 逐行解析 →
dispatch分发方法 → 写回 stdout; - Python 示例:同一文档展示了 Python 版本处理
initialize方法的方式(PLUGIN_GUIDE.md),脚本型插件还能在清单里声明interpreter字段(如python3); - Go / Rust 双实现:官方注册表 registry.json 里的 Redis 驱动同时有 Go 版(
Redis (Go))和 Rust 版(Redis (Rust)),另有基于 ODBC 的 Informix 插件和走 HTTP API 的 Cloudflare D1 插件——同一份协议,不同语言、不同技术栈。
也就是说,你甚至可以用 Node.js 写一个插件去连 Google Sheets(PLUGIN_TUTORIAL.md 的官方教程最终交付物正是一个 Google Sheets 驱动)。
插件安装目录与 .tabularium 清单
各系统的插件安装目录:
| 系统 | 路径 |
|---|---|
| Linux | ~/.local/share/tabularis/plugins/ |
| macOS | ~/Library/Application Support/tabularis/plugins/ |
| Windows | %APPDATA%\tabularis\plugins\ |
每个插件一个子目录,典型结构:
plugins/
└── duckdb/
├── .tabularium # 插件清单
└── duckdb-plugin # 可执行文件(Windows 下自动补 .exe)
清单文件是插件的"身份证",manifest.schema.json 定义了完整结构,必填字段有 5 个:
| 字段 | 作用 |
|---|---|
name |
插件唯一标识(小写短横线 slug),须与目录名一致 |
version |
语义化版本,如 1.0.0 |
executable |
可执行文件相对路径 |
capabilities |
能力开关:schemas、views、routines、file_based、readonly 等,直接决定主界面渲染哪些 UI 元素 |
data_types |
建表界面中可选的 SQL 列类型清单 |
对于普通用户,这些细节都不需要关心:在 设置 → 可用插件 中即可一键安装、更新、卸载插件,无需重启应用;安装时 Tabularis 还会校验注册表的 JWS 签名和下载包的 SHA-256(见 plugins/ 下的完整性校验实现)。
20 分钟上手:插件开发快速路径 ⚡
官方提供了脚手架 packages/create-plugin/,一条命令生成完整项目:
npm create @tabularis/plugin@latest my-driver
cd my-driver
just dev-install
生成的骨架包含 stdin/stdout JSON-RPC 主循环、按 metadata / query / crud / ddl 分组的 handlers,以及 justfile 中的构建安装配方。每个 handler 默认返回"合法但为空"的响应,因此骨架一装进 Tabularis 就能显示在连接选择器里,你可以按"元数据 → 查询 → CRUD → DDL"的优先级逐个补全。
不启动主程序也能自测——直接管道对话即可:
echo '{"jsonrpc":"2.0","method":"get_tables","params":{"params":{"driver":"duckdb","database":"/tmp/test.duckdb"},"schema":null},"id":1}' \
| ./duckdb-plugin
核心 RPC 方法速览 📋
一个驱动至少要实现连接测试、元数据与查询执行三组方法(完整清单见 PLUGIN_GUIDE.md):
| 分组 | 方法 | 说明 |
|---|---|---|
| 连接 | test_connection、ping(可选) |
测试连通性;ping 供周期性健康检查 |
| 元数据 | get_databases、get_schemas、get_tables、get_columns、get_foreign_keys、get_indexes |
数据库浏览器、ER 图的数据来源 |
| 视图/存储过程 | get_views、get_routines、触发器系列 |
可选,由 capabilities 开关控制 |
| 查询 | execute_query(分页)、explain_query |
查询结果网格与可视化 EXPLAIN |
| CRUD | insert_record、update_record、delete_record |
表格内直接增删改 |
| BLOB | save_blob_to_file、fetch_blob_as_data_url |
二进制列导出与预览 |
| DDL 生成 | get_create_table_sql、get_create_index_sql 等 |
生成 SQL 并先展示给用户确认 |
两个设计细节值得注意:
- 优雅降级:不支持的方法只需返回标准错误码
-32601(Method not found),主程序会自动回退到空结果或方言无关的 SQL,主界面依然完整可用; - 标准错误码:
-32700解析错误、-32600非法请求、-32602参数错误、-32603内部错误,与 JSON-RPC 2.0 规范完全一致。
进阶玩法:UI 扩展与 EXPLAIN 解析器 🎨
插件不仅能"驱动数据库",还能"长进"主界面:
- UI 插槽(slots):v0.9.15 起,插件可在清单中声明
ui_extensions,把自定义 React 组件注入工具栏、右键菜单、行编辑器侧栏、设置页等 11 个预定义插槽,组件通过@tabularis/plugin-api包提供的 hooks(usePluginQuery、usePluginModal、usePluginTheme等)与宿主交互,每个插槽都有错误边界隔离——你的组件抛错不会拖垮主应用; - EXPLAIN 解析器:插件可以携带 TypeScript 解析器(IIFE 包),让自己的执行计划格式也能在可视化 EXPLAIN 中渲染(类型定义见 packages/explain/);
- 插件设置字段:清单里的
settings数组可声明任意配置项(字符串、布尔、数字、下拉框),用户保存后通过启动时的initializeRPC 传给插件。
发布插件到官方注册表 🚀
把你的插件分享给全世界只需 4 步:
- 为每个目标平台(linux-x64 / darwin-arm64 / darwin-x64 / win-x64)构建 ZIP,内含
.tabularium与可执行文件; - 发布 Release,并把
.tabularium作为独立资源一并上传; - 提交注册,manifest 不通过 schema 校验会被直接拒绝(HTTP 422),没有"静默回退";
- 在 registry.json 的格式基础上,每个 release 可单独声明
min_tabularis_version——这意味着旧版 Tabularis 用户仍能为自己安装到兼容的旧版本插件。
写在最后
Tabularis 插件系统的精髓在于:用一个 40 年前的协议(JSON over stdio)+ 一份 JSON 清单,换来了真正的语言自由。数据库驱动从此不再是"官方支持哪个就能用哪个"——任何能被程序访问的数据源(SQL、NoSQL、甚至 REST API),都可以用你最熟悉的语言接入这个桌面 SQL 工作区。
想动手试试?从 plugins/PLUGIN_TUTORIAL.md 的 20 分钟教程开始,跟着做完,你就能拥有一个跑在自己机器上的 Google Sheets 数据库驱动。