ToolJet MySQL 数据源接入指南：连接配置、SQL/GUI 查询模式与参数化查询实战-平芜编程栈

ToolJet MySQL 数据源接入指南：连接配置、SQL/GUI 查询模式与参数化查询实战

【免费下载链接】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

本篇技术指南基于 ToolJet 官方文档 docs/docs/data-sources/mysql.md，系统讲解如何在 ToolJet 低代码平台中接入 MySQL 数据库：从工作区级数据源连接（Hostname / Socket 两种协议、SSL 与 SSH 隧道）、到查询面板中的 SQL 模式与 GUI 模式、再到参数化查询防注入与查询超时控制。读完你将能在 ToolJet 应用中安全地读取、写入和批量更新 MySQL 数据，并将结果与前端组件实时联动。

前置条件与适用范围

ToolJet 通过「MySQL 数据源」插件连接 MySQL 数据库进行读写操作，底层实际使用knex（mysql2驱动）完成连接与查询（见 plugins/packages/mysql/lib/index.ts）。在动手连接前，请确认以下网络前提：

若你自托管 ToolJet，请确保数据库的Host/IP 可从你的 VPC 内访问，ToolJet 服务端必须能与 MySQL 端口互通；
若你使用ToolJet Cloud，请将 ToolJet 官方公布的IP 加入数据库白名单。

同时建议为 ToolJet单独创建一个新的 MySQL 数据库用户，而非直接使用root，以便按需控制 ToolJet 对库表的最小访问权限。数据源连接成功后属于工作区级资源，可被同一工作区内的所有应用共享，具体说明见 Data Sources: Overview。

建立 MySQL 连接

点击查询面板中的+ Add new Data source按钮，或通过 ToolJet 仪表盘左侧进入Data Sources页面，即可开始添加 MySQL 数据源。

:::info 网络提示自托管场景下请确认数据库 Host/IP 可从部署 ToolJet 的 VPC 访问；ToolJet Cloud 场景下请将我们的 IP 加入白名单。 :::

连接所需的基础信息

配置表单要求提供以下四项核心信息：

配置项	说明
Username	MySQL 用户名，建议使用为 ToolJet 单独创建的受限账号
Password	用户密码，字段支持 secrets 语法，例如`{{secrets.db_password}}`
Database Name	目标数据库名
Connection Type	连接方式：Hostname（主机名）或 Socket（Unix 套接字）

从插件清单 manifest.json 可以看到，该连接表单还支持「Manual connection（手动配置）」与「Connection string（连接串）」两种形态：手动模式下逐项填写字段；连接串模式下直接粘贴形如mysql://username:password@host:port/database的字符串，插件在运行时会解析并自动填充各项配置。

Hostname 连接方式

选择Hostname作为连接类型（协议枚举值为hostname）时，需要额外提供：

Host/IP：MySQL 主机地址，默认值localhost；
Port：MySQL 端口，默认3306（见 manifest.json）；
SSL：是否开启加密连接；
SSL Certificate（证书类型，三选一）：
- CA Certificate：需填写CA 证书，可选填客户端证书与客户端私钥；
- Self-signed Certificate（自签名证书）：需填写Root 证书、客户端证书（Client cert）与客户端私钥（Client key）；
- None：不校验证书。

插件层面，ssl_enabled开启后，底层会构造ssl对象并依据证书类型注入对应证书内容（ca/key/cert/root_cert），同时以rejectUnauthorized控制是否校验证书链，实现细节见 index.ts 的 buildConnection 与 types.ts。证书与密码均被声明为加密字段（见 manifest.json 的 tj:encrypted 段），入库时会被加密保存。

Socket 连接方式

选择Socket作为连接类型时，只需提供Socket Path（Unix 套接字文件路径）。此时连接配置会走socketPath而非host/port分支（见 index.ts），适合 MySQL 与 ToolJet 部署在同一台机器、通过本地套接字直连的场景。Socket 模式下同样可配置数据库名、用户名与密码。

进阶连接选项

从 manifest.json 与 types.ts 还可以看到该数据源在当前仓库中支持的几项进阶能力，供配置时参考：

SSH Tunnel：开启后可通过 SSH 跳板访问位于私网的数据库，需提供 SSH Host、SSH Port（默认22）、SSH 用户名，认证方式支持Private key与Password两种。底层通过ssh2建立端口转发流，再经由该 stream 建立 MySQL 连接（见 index.ts 的 createSSHStream）。
Allow dynamic connection parameters：开启后允许在查询运行时由应用动态覆盖默认 Host 与 Database，此时插件会跳过连接缓存并销毁临时连接（见 index.ts 的 run 方法）。
Connection options：可追加自定义连接参数键值对，会透传给 knex/mysql2 连接配置。

保存前建议先测试连接：插件通过执行SELECT @@version;校验连通性（见 index.ts 的 testConnection），测试失败时返回包含 MySQLcode、errno、sqlMessage、sqlState的详细错误对象，便于快速定位凭据、网络或 SSL 问题。

在查询面板中查询 MySQL

数据源添加完成后，回到应用编辑器：点击底部查询管理器的+ Add按钮，选择上一步添加的数据源，即可开始创建读写查询。查询方式分为SQL Mode与GUI Mode两种（默认模式为 SQL，见 operations.json）。

SQL Mode：直接书写 SQL

SQL 模式适用于熟悉 SQL 语法的开发者，操作步骤：

在模式下拉框中选择SQL mode；
在编辑器中输入 SQL 查询；
点击Run按钮执行。

示例：

SELECT * FROM users

SQL 模式在服务端通过knex.raw()执行，插件会剥离空的查询参数、并对空查询直接报错（见 index.ts 的 executeQuery）；每条语句都受STATEMENT_TIMEOUT超时控制。

参数化查询（Parameterized Queries）

ToolJet 支持参数化 SQL 查询：参数以绑定变量的形式传给驱动，可有效预防 SQL 注入，同时支持利用运行值动态构造查询。使用要点：

在 SQL 中用:parameter_name作为参数占位符；
在查询编辑器下方的Parameters（SQL Parameters）区域为每个参数添加键值对；
键名须与查询中使用的参数名一致（不带冒号）；
值可以是静态值，也可以用{{ }}写法绑定组件或变量等动态值。

示例：

Query: SELECT * FROM users WHERE username = :username SQL Parameters: Key: username Value: oliver # 或使用动态值 {{ components.username.value }}

从源码看，SQL 模式收到的参数形如[["username","oliver"]]的键值对数组，插件会先过滤空键再交由knex.raw()执行，全程以绑定参数方式传值而非字符串拼接（见 index.ts 的 handleRawQuery），这正是其防注入能力的实现基础。

查询超时设置

如需调整 SQL 查询的超时时长，可在环境配置文件中加入变量：

PLUGINS_SQL_DB_STATEMENT_TIMEOUT

该变量默认值为120,000 ms（即 120 秒）。插件在单例初始化时读取该变量，仅当其为合法数字时覆盖默认值（见 index.ts 构造函数），随后所有knex.raw()调用都会叠加.timeout()约束。对运行耗时的报表类查询，建议按需调大；对交互类查询可适当调小以避免长连接占用。

GUI Mode：免 SQL 可视化操作

GUI 模式面向不熟悉 SQL 的用户，通过下拉框与表单即可完成增删改查。查询面板操作分两部分：左侧设置（表、列、条件等），右侧会实时预览生成的 SQL。

以文档示例的Bulk update using primary key（按主键批量更新）为例：

在模式下拉框中选择GUI mode；
操作类型选择Bulk update using primary key；
填写Table表名与Primary key column主键列名；
在编辑器中以「对象数组」形式输入待更新的记录；
点击Run执行。

示例：

{{ [ {id: 1, channel: 33}, {id:2, channel:24} ] }}

该示例意为：将id为 1 的记录channel更新为 33、id为 2 的记录channel更新为 24。插件会根据主键逐行拼接出多条UPDATE ... WHERE pk = value;语句后一次性提交（服务端的查询构造器由 createQueryBuilder('mysql') 提供）。

从 operations.json 可见，当前 MySQL 插件在 GUI 模式下实际支持8 种操作：

操作	说明
List rows	查询行，支持筛选、排序、聚合、分组与 limit/offset 分页
Create row	插入单行，按列名与值成对填写
Update rows	更新行，需至少一个筛选条件，可控制是否允许多行更新
Delete rows	删除行，要求至少提供筛选条件或 limit，防止误删全表
Upsert row	按主键插入或更新（支持复合主键）
Bulk insert	批量插入对象数组
Bulk update using primary key	按主键批量更新（本示例所用操作）
Bulk upsert using primary key	按主键批量插入或更新

GUI 模式在提交写操作时有一系列防误操作保护（对应源码 handleGuiQuery 与 executeWriteQuery）：

更新/删除操作必须至少有一个筛选条件（删除还可通过 limit 兜底），否则直接报错；
默认不允许一次匹配并修改多行，可通过Allow this query to modify/delete multiple rows开关显式放开；
默认将「匹配 0 行」视为失败，可通过zero records as success开关调整；
批量写入会被拆分为单个事务顺序执行，任一语句失败即整体回滚，保证数据一致性；
超大批量写入会按「MySQL 单查询 65,535 个参数上限」自动计算批次大小（安全阈值为 64,000，见 index.ts），避免超出协议限制。

仓库中的单元测试 plugins/packages/mysql/tests/mysql.test.js 验证了按主键批量更新语句的生成逻辑：给定两条含id的记录，buildBulkUpdateQuery会产出两条以分号分隔的UPDATE customers SET ... WHERE id = ...;语句，可作为理解该 GUI 操作底层行为的最小样例。

:::tip 结果转换每次查询返回的结果还可以通过 ToolJet 的transformations（数据转换）能力在渲染前做二次加工，例如字段重命名、类型转换或结构重组，可参考 transformations 教程。 :::

与前端组件联动

MySQL 查询创建完成后，其返回结果（对象数组）会以查询名暴露给整个应用，可直接绑定到表格、下拉框、图表等组件的数据属性上。典型用法包括：

表格展示：将数据源查询结果直接赋给 Table 组件，实现内部工具的数据看板；
表单驱动的条件查询：结合参数化查询，把输入框、下拉框值（如{{ components.username.value }}）作为查询参数，实现按用户输入过滤的实时检索；
事件链触发：在按钮点击事件中触发「先删除后新增」「先更新再重新加载列表」等多步骤查询编排。

查询结果字段名、行数等信息以QueryResult结构返回（SQL 模式取结果的第一个结果集，见 handleRawQuery），便于前端按数组或对象访问。

常见问题排查要点

连接超时/握手失败：优先检查 Host/IP、Port、数据库名与白名单；自托管时确认 VPC 路由与安全组放行 3306；
SSL 相关报错：若 MySQL 服务端强制 SSL，请在数据源中开启 SSL 并正确选择证书类型（CA Certificate / Self-signed Certificate），自签名场景需将 Root 证书、客户端证书与私钥一并填入；
写操作拒绝执行：GUI 模式的更新/删除要求至少一个筛选条件，且默认禁止匹配多行——确认是否显式开启了对应开关；
查询结果为空被报错：默认「0 行受影响」会被视为失败，可开启zero_records_as_success；
大批量写入失败：单查询参数超限时插件会自动分批，若仍失败可尝试拆小记录数组并检查字段类型。

以上排查依据均来自 index.ts 与 operations.json 的实际实现。如需进一步了解数据源权限与跨应用共享，可阅读 Data Sources 概览；查询编辑器整体用法见 Query Panel 文档。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考