ToolJet 3.0.0-LTS PostgreSQL 数据源接入与查询实战指南-育师

ToolJet 3.0.0-LTS PostgreSQL 数据源接入与查询实战指南

【免费下载链接】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 内置了对 PostgreSQL 数据库的连接能力，支持数据的读取与修改，是企业内部工具、仪表盘和业务应用中接入关系型数据最常见的方式之一。本指南基于 ToolJet 3.0.0-LTS 文档与仓库内 PostgreSQL 插件源码，完整讲解两种连接方式、连接参数与 SSL/SSH 等高级配置、SQL 模式与参数化查询、查询超时设置，以及 GUI 模式下的增删改查与批量操作，帮助你从零开始把 PostgreSQL 接入 ToolJet 并在应用构建器中高效使用。

建立连接

要建立 PostgreSQL 数据源连接，有两种入口：

点击查询面板（query panel）上的+ Add new Data source按钮；
从 ToolJet 仪表盘进入数据源总览页面，选择PostgreSQL作为数据源。

ToolJet 提供两种连接类型：

Manual connection（手动连接）
Connection string（连接字符串）

从插件清单 manifest.json 可以看到，连接类型由connection_type字段控制，取值为manual或string，默认manual，且connection_type是唯一必填字段（其余字段按连接类型联动必填）。

手动连接（Manual Connection）

选择Manual connection作为连接类型后，需要提供以下信息：

字段	说明	默认值/要求
Host	数据库主机名或 IP 地址	必填，默认`localhost`
Port	数据库端口	必填，默认`5432`
SSL	是否启用 SSL/TLS 加密连接	默认开启（`true`）
Database Name	要连接的数据库名称	选填
Username	数据库用户名	必填
Password	数据库密码	选填，支持密钥引用，如`{{secrets.db_password}}`
Connection Options	额外的连接参数（键值对）	选填，会透传给底层驱动
SSL Certificate	SSL 证书类型	可选：CA certificate / Self-signed certificate / None

上述字段在 manifest.json 中均有对应定义，其中ssl_enabled默认值为true，port默认值为5432，与 PostgreSQL 服务端的默认行为保持一致。启用 SSL 后还需要选择证书类型：

CA certificate：需要粘贴CA cert（CA 证书内容）；
Self-signed certificate：需要粘贴Client key（客户端私钥）、Client cert（客户端证书）与Root cert（根证书）。

连接字符串（Connection String）

选择Connection string作为连接类型后，只需提供一个字段：

Connection string：完整的 PostgreSQL 连接字符串

ToolJet 使用的连接字符串格式为：

postgres://username:password@hostname:port/database?sslmode=require

示例（来自 manifest 的 help_text）：postgresql://admin:p%40ssword@localhost:5432/my%23db。注意密码、数据库名等特殊字符需要使用 URL 编码（例如@编码为%40、#编码为%23）。sslmode=require等查询参数同样会随字符串传递并被插件解析（见下文源码分析）。

建议：推荐为 ToolJet 单独创建一个新的 PostgreSQL 数据库用户，以精确控制 ToolJet 对数据库的访问级别（最小权限原则）。

自托管网络注意：如果你是自托管 ToolJet，请确保数据库的 Host/IP 能从你的 VPC 内访问；如果使用 ToolJet 云服务，则需要将 ToolJet 的 IP 加入数据库白名单。

查询 PostgreSQL

建立好数据源后，即可在应用编辑器中执行查询：

点击编辑器底部查询管理器（query manager）的+ Add按钮；
选择上一步添加的PostgreSQL数据源；
从下拉框选择查询模式并输入查询内容；
点击Preview按钮预览输出，或点击Run按钮执行查询。

从 operations.json 可以看到，查询模式的默认值是sql，下拉框提供SQL mode与GUI mode两种选择。

SQL 模式

选择 SQL 模式后，在编辑器输入 SQL 语句即可执行。底层实现中，插件通过 Knex 驱动建立连接并执行原生 SQL（参见 index.ts 中run()的sql分支）。

参数化查询

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 }}

从源码看，插件通过isSqlParametersUsed()检测是否传入了非空的查询参数（index.ts），一旦存在参数，就会走handleRawQuery()→executeQuery()路径，通过knexInstance.raw(query, sanitizedQueryParams)将参数绑定到占位符上执行，而不是拼接进 SQL 文本——这正是防注入的关键。

查询超时

可以通过在环境配置文件中添加PLUGINS_SQL_DB_STATEMENT_TIMEOUT变量来设置 SQL 查询的超时时长，默认值为 120,000 ms（即 120 秒）。

在 index.ts 的构造函数中可以看到该逻辑：

this.STATEMENT_TIMEOUT = process.env?.PLUGINS_SQL_DB_STATEMENT_TIMEOUT && !isNaN(Number(process.env?.PLUGINS_SQL_DB_STATEMENT_TIMEOUT)) ? Number(process.env.PLUGINS_SQL_DB_STATEMENT_TIMEOUT) : 120000;

即：环境变量存在且为合法数值时采用该值，否则回退到 120000ms。该超时通过 Knex 连接配置中的statement_timeout传递给 PostgreSQL 服务端（非云版生效），同时testConnection()也使用同一个超时值执行SELECT version();来验证连接。

GUI 模式

选择 GUI 模式后，可通过下拉框选择操作类型。ToolJet 的 PostgreSQL GUI 模式提供以下操作（见 operations.json 与 index.ts 的handleGuiQuery()）：

操作	值	说明
List rows	`list_rows`	按条件查询行，支持过滤、排序、聚合、分组、limit/offset
Create row	`create_row`	插入单行
Update rows	`update_rows`	按条件更新行，可控制是否允许多行更新
Delete rows	`delete_rows`	按条件删除行，可配合 limit 与多行删除开关
Upsert row	`upsert_rows`	存在即更新、不存在即插入（依赖主键冲突检测）
Bulk insert	`bulk_insert`	批量插入多条记录
Bulk update using primary key	`bulk_update_pkey`	按主键批量更新多条记录
Bulk upsert using primary key	`bulk_upsert_pkey`	按主键批量 upsert

文档中重点演示的Bulk update using primary key操作步骤如下：选择该操作，提供Table名称与Primary key column主键列名，然后在编辑器中输入records（对象数组）。每个对象必须包含主键列的值，用于定位要更新的行。

[ { "customer_id": 1, "country": "India" }, { "customer_id": 2, "country": "USA" } ]

批量操作的底层实现

源码对批量操作做了细致的工程化处理（index.ts）：

自动分批：computeBatchSize()会采样记录、统计列数，用PARAM_THRESHOLD（60,000 个参数上限）除以列数计算每批记录数，避免单条 SQL 参数超限；splitIntoBatches()负责切分。
事务保障：executeBulkQueriesInTransaction()将所有批次放入同一个数据库事务中执行，任一批次失败即整体回滚。
返回受影响行：批量更新/upsert 通过RETURNING *返回受影响的记录。
安全开关：update_rows、delete_rows、upsert_rows等写操作支持allow_multiple_updates（是否允许多行修改）与zero_records_as_success（0 行命中是否视为成功）两个开关。例如delete_rows在既无过滤条件又无 limit 时会直接报错，防止误删全表；单行删除/更新若匹配多行且未开启多行开关，也会抛出错误并回滚。

仓库内的测试用例 postgresql.test.js 验证了buildBulkUpdateQuery()的查询生成逻辑，例如对customers表按主键id批量更新两条记录会生成：

UPDATE customers SET name = 'sam', email = 'sam@example.com' WHERE id = 1; UPDATE customers SET name = 'jon', email = 'jon@example.com' WHERE id = 2;

连接原理与高级行为

理解插件源码有助于排查连接与性能问题。核心逻辑集中在 plugins/packages/postgresql/lib/index.ts：

连接池：通过 Knex 创建连接，池配置为pool: { min: 0, max: 10, acquireTimeoutMillis: 10000 }，即最多 10 个连接、获取连接 10 秒超时、总获取超时 60 秒。
连接缓存：getConnection()会基于数据源配置生成哈希（generateSourceOptionsHash）作为缓存键，命中缓存则复用连接；若数据源配置已更新（通过dataSourceUpdatedAt判断），则重建连接。开启动态连接参数后不会走缓存，每次查询都会新建连接并在用完后销毁，避免动态 host/database 污染连接池。
动态连接参数：开启allow_dynamic_connection_parameters后，查询时可传入host与database覆盖默认值——手动连接模式直接覆盖 host/database 字段；连接字符串模式则通过new URL(...)改写 hostname 与 pathname 后重新生成字符串。
SSH 隧道：启用后插件用ssh2库在本地127.0.0.1上开一个随机端口，通过ssh.forwardOut把流量转发到目标数据库，随后用本地端口建立 Knex 连接；查询结束或连接测试完成后会关闭隧道与客户端（server.close()+sshClient.end()）。
SSL 配置：getSslConfig()依据ssl_enabled与ssl_certificate类型构造 Node 驱动所需的rejectUnauthorized、ca、key、cert选项；选择 CA 证书时传ca_cert，选择自签名证书时传client_key与client_cert。
连接选项：手动填写的 Connection Options 会以键值对形式展开，并合并到 Knex 配置中（空值会被过滤），可用来传递驱动级别的额外参数。
错误处理：查询失败时，插件会提取 PostgreSQL 驱动的code、detail、hint、routine等诊断信息并包装为QueryError返回；连接测试还会对无效连接字符串、SSH 失败、Knex 超时等场景给出针对性提示。

常见问题与实用提示

连接失败排查：先确认 Host/Port 可达（自托管场景检查 VPC 安全组、云场景检查白名单）；再确认用户名密码与目标数据库权限；若启用了 SSL 而服务端未开启或证书不匹配，可临时关闭 SSL 验证连通性。
参数化查询的键名：参数键必须去掉冒号（:username对应的键是username），否则绑定不上。
长查询超时：超过 120 秒的查询请调整PLUGINS_SQL_DB_STATEMENT_TIMEOUT环境变量（单位毫秒）。
GUI 批量更新：records 数组中的每个对象都必须包含主键列值；批量更新/删除等写操作请留意多行开关，避免误操作。
结果变换：可以对查询结果应用 JavaScript 或 Python 变换，参考变换教程。
表格组件批量更新实战：如何在表格组件中实现多行批量更新，可参考如何通过主键批量更新表格中的多行。

小结

ToolJet 的 PostgreSQL 数据源同时提供了面向初学者的可视化配置（手动连接 + GUI 操作）与面向高级场景的灵活能力（连接字符串、SSL/SSH、动态连接参数、参数化 SQL）。底层插件基于 Knex 驱动实现连接池复用、语句超时控制、批量事务与防注入的参数绑定，保证了查询的安全与可靠。你可以结合插件源码、连接字段定义与查询操作定义进一步深入理解每一项配置对实际行为的影响。

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