ToolJet 接入 MariaDB 数据源：连接配置、CRUD 查询与源码级实现解析-编程实验室

ToolJet 接入 MariaDB 数据源：连接配置、CRUD 查询与源码级实现解析

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

MariaDB 是 MySQL 生态中最流行的兼容分支，ToolJet 内置了对自建与云端 MariaDB 服务器的完整支持，可用来读写数据、驱动内部工具与数据看板。本文将基于 ToolJet 3.0.0-LTS 文档体系，完整讲解 MariaDB 数据源的连接参数、SSL/SSH 安全选项、SQL 与图形化查询方式，并结合仓库中 MariaDB 插件源码（plugins/packages/mariadb/lib/index.ts）剖析其连接池、事务保护与批量写入的底层实现，帮助你既会用、又知其所以然。

连接 MariaDB 数据源

在 ToolJet 中建立 MariaDB 全局数据源（global datasource）有两种入口：

在查询面板（query panel）点击+ Add new global datasource按钮；

从 ToolJet 仪表盘进入 Global Datasources（即文档 />

源码视角：连接是如何建立的

要理解上述参数的真实作用，可以追踪插件源码中的连接建立链路。MariaDB 插件基于mariadb驱动（^3.2.3，见 plugins/packages/mariadb/package.json），核心实现集中在 plugins/packages/mariadb/lib/index.ts。

连接池配置（buildConnectionPool()）关键点包括：

使用mariadb.createPool()创建连接池，connectionLimit取自表单，缺省为10；
namedPlaceholders: true开启命名占位符，支持:name形式参数绑定；
multipleStatements: true允许多语句执行；
connectTimeout: 60000（60 秒连接超时）；
连接会按数据源配置哈希缓存复用：getCachedConnection/cacheConnectionWithConfiguration配合dataSourceId + optionsHash作为缓存键，数据源更新后自动失效重建。

SSH 隧道实现（createSSHStream()）使用ssh2客户端建立forwardOut端口转发，将本地流量转发到 MariaDB 的 host:port；连接配置的stream回调将 SSH 通道作为 socket 传给驱动。SSH 连接设置了readyTimeout: 20000与keepaliveInterval: 10000，并支持密码与私钥两种认证。若数据库在私有网络，这是推荐的接入方式。

连接测试（testConnection()）会执行SELECT 1 as val验证连通性，失败时返回QueryError并携带驱动报错信息。GUI 模式的表/列选择器则通过查询information_schema.TABLES与information_schema.COLUMNS动态获取元数据（invokeMethod中的listTables/listColumns）。

在 ToolJet 中查询 MariaDB

连接成功后，按以下步骤编写查询：

点击+ Add按钮打开可用数据源列表；
在全局数据源区域选择MariaDB；
在编辑器中输入 SQL 查询；
点击Preview预览查询返回的数据，或点击Run执行查询。

:::tip 查询结果可以通过 Transformation（数据转换）进一步处理。详细用法请参阅 transformations.md。 :::

CRUD 查询完整示例

假设存在一个名为customers的 MariaDB 数据库，我们先在其中创建一张users表，包含以下列：

id（integer，自增）
name（varchar）
age（integer）
email（varchar）

CREATE TABLE user( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50), age INT, email VARCHAR(100) );

上述命令会在customers数据库中创建users表。接下来逐一演示针对该表的增删改查命令。

创建（Insert）

插入单个用户：

INSERT INTO user (name, age, email) VALUES ('John Doe', 25, 'john@example.com');

批量插入多个用户：

INSERT INTO user (name, age, email) VALUES ('John Doe', 25, 'john@example.com'), ('Jane Smith', 30, 'jane@example.com'), ('Bob Johnson', 35, 'bob@example.com');

读取（Select）

查询所有用户：

SELECT * FROM user;

只查询指定列：

SELECT name, age, email FROM user;

为查询添加条件与过滤：

SELECT name, age, email FROM user WHERE age > 25;

更新（Update）

更新指定用户的年龄：

UPDATE user SET age = 26 WHERE id = 1;

删除（Delete）

删除指定用户：

DELETE FROM user WHERE id = 1;

实际使用中请根据具体需求调整取值与条件。以上命令覆盖了建表、插入、查询、更新与删除的完整流程。

SQL 模式与 GUI 模式的底层行为

执行查询时，插件会根据queryOptions.mode分发到两种处理路径（index.ts）：

SQL 模式（sql）：直接执行编辑器中的 SQL。query_params会过滤空键后以命名占位符方式绑定参数，从底层防止 SQL 注入；返回结果会经过toJson()序列化，其中bigint类型会被转换为数字字符串，避免精度丢失。

GUI 模式（gui）：不手写 SQL，而是通过可视化操作生成查询。插件基于createQueryBuilder('mariadb')构建语句——在 plugins/packages/common/lib/queryBuilder.ts 中，MariaDBDialect继承自MySQLDialect，使用反引号`引用标识符、LIMIT/OFFSET分页，并支持eq/neq/gt/gte/lt/lte/like/in/not_in/between等操作符与sum/count/avg/min/max聚合函数。GUI 模式支持以下操作：

操作	说明
`list_rows`	查询列表，支持 where 过滤、排序、聚合与分组、limit/offset 分页
`create_row`	新增单行，返回`insertId`
`update_rows`	更新行，基于过滤条件匹配
`upsert_rows`	按主键更新或插入
`delete_rows`	删除行，支持 limit 限制
`bulk_insert`	批量插入多条记录
`bulk_update_pkey`/`bulk_upsert_pkey`	按主键批量更新 / 批量 upsert

其中批量操作会按“每语句 65,000 个绑定参数上限”自动计算批次大小（computeBatchSize结合PARAM_THRESHOLD = 65_000），将大批量记录拆分为多个批次并在同一事务中执行，保证原子性。

写操作的安全保护

源码在 GUI 模式中内置了多重防误操作机制（index.ts）：

update_rows必须至少提供一个过滤条件（where_filters），否则直接报错 "Update rows requires at least one filter condition."；
delete_rows必须提供过滤条件或 limit，防止误删全表；
当“允许更新/删除多行”（allow_multiple_updates）关闭时，若语句匹配超过一行，事务会回滚并报错；
当“零记录视为成功”（zero_records_as_success）关闭时，若影响行数为 0，同样回滚报错；
所有写操作均在beginTransaction/commit/rollback包裹的事务中执行，确保数据一致性。

这些保护同样适用于 SQL 模式之外的图形化操作，是生产环境安全使用数据库的关键设计。

故障排查建议

如果 MariaDB 数据源连接遇到问题，可以按顺序尝试以下步骤：

确认 MariaDB 服务器正在运行，并且 ToolJet 服务器可以访问到它；
核对凭据的拼写与大小写（用户名、密码、库名均区分大小写）；
尝试重启 ToolJet 服务器。

如果问题依旧，可以在 GUI 模式的连接表单中先使用Test Connection（源码中执行SELECT 1验证），观察返回的错误信息；若为网络问题，检查 ToolJet 与数据库之间的防火墙、端口（默认 3306）可达性；若启用了 SSL/SSH，还需逐一确认证书内容、SSH 认证方式与目标地址是否正确。