ToolJet 连接 Amazon Redshift 数据源：Marketplace 插件配置与增删改查实战指南

ToolJet 连接 Amazon Redshift 数据源：Marketplace 插件配置与增删改查实战指南

【免费下载链接】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 开源仓库（v2.50.0-LTS 文档）讲解如何通过 Marketplace 插件将 Amazon Redshift 集群接入 ToolJet，使你在应用构建器中直接查询、写入和更新 Redshift 中的数据。读完本文，你将掌握 Redshift 插件的完整配置参数（含 IAM 认证细节）、底层基于 Redshift Data API 的执行原理，以及一套可直接复制运行的增删改查 SQL 示例。

前置条件：安装 Marketplace 插件

在配置 Amazon Redshift 数据源之前，需要先完成 Marketplace 插件的启用与安装。根据 Marketplace 概述文档：

1. 在 ToolJet 实例的.env文件中加入以下环境变量以启用 Marketplace 功能：

ENABLE_MARKETPLACE_FEATURE=true

注意：访问 Marketplace 页面的用户必须具有Administrator权限；本地运行时需先构建 marketplace 插件再启动服务。

2. 点击仪表盘左下角的设置图标，选择Marketplace进入插件市场。
3. 在Marketplace选项卡中找到AWS Redshift插件卡片，点击Install；安装完成后状态会变为Installed。

安装完成后，在仪表盘的Data sources选项卡中滚动到Plugins区域，即可看到已安装的 Redshift 插件并开始配置数据源；配置成功后，即可在查询面板（Query Panel）中新建基于该数据源的查询。

配置 Redshift 数据源

打开 Redshift 数据源的创建页面后，需要填写以下连接参数。

必填参数

可选参数

从插件源码的 manifest.json 可以看出更多实现细节：

• Region 是下拉选择，覆盖了所有主流 AWS 区域，例如us-east-1（US East, N. Virginia）、us-east-2（US East, Ohio）、us-west-2（US West, Oregon）、eu-west-1（Europe, Ireland）、ap-southeast-1（Asia Pacific, Singapore）、ap-northeast-1（Asia Pacific, Tokyo），以及cn-north-1/cn-northwest-1（中国区域）和us-gov-east-1/us-gov-west-1（AWS GovCloud）等，可直接从下拉框选择，避免手输拼写错误。
• Database 的默认值为dev，这是 Redshift 集群初始化时默认创建的示例数据库名；Port 的默认值为5439（Redshift 的标准端口）。
• Secret Key 字段类型为password且标记encrypted: true，即密钥在表单中输入后会被加密存储，不会明文落库。
• 必填校验字段为region、secret_key、access_key、database、workgroup_name，其中 workgroup 名称在连接时同样参与请求构造。

底层原理：IAM 认证与 Redshift Data API

该插件并非通过传统的 JDBC/ODBC 驱动直连集群，而是基于 AWS 官方的Redshift Data API实现。这一点可以从插件核心实现 marketplace/plugins/awsredshift/lib/index.ts 中确认：插件引入了@aws-sdk/client-redshift-data包（依赖版本见 package.json），使用RedshiftDataClient、ExecuteStatementCommand、GetStatementResultCommand和DescribeStatementCommand四个核心类。

连接建立（getConnection）

async getConnection(sourceOptions: SourceOptions): Promise<RedshiftDataClient> { const region = sourceOptions.region; const credentials = { accessKeyId: sourceOptions.access_key, secretAccessKey: sourceOptions.secret_key, }; const client = new RedshiftDataClient({ region, credentials }); return client; }

可见连接的本质是：用你填写的Access Key / Secret Key 构造 AWS 凭据，连同 Region 一起初始化一个RedshiftDataClient。这也解释了为什么认证类型目前只支持 IAM——插件通过 IAM 用户凭证向 Redshift Data API 发起请求，而 Redshift Data API 本身依赖 IAM 权限（例如redshift-data:ExecuteStatement）来完成对集群的受控访问。

连接测试（testConnection）

async testConnection(sourceOptions: SourceOptions): Promise<ConnectionTestResult> { const client = await this.getConnection(sourceOptions); const input = { Sql: 'SELECT 1', Database: sourceOptions.database, WithEvent: true, WorkgroupName: sourceOptions.workgroup_name, }; const command = new ExecuteStatementCommand(input); const result = await client.send(command); return { status: 'ok', data: result }; }

保存数据源时，插件会向 Redshift 发送一条SELECT 1探活语句（WithEvent: true表示启用事件通知模式），成功返回即代表连接可用。

支持的查询

Redshift 本身支持一套完整的 SQL 命令。该插件以SQL mode运行，你可以在查询面板的 SQL 编辑器中执行任意 Redshift 支持的 SQL 语句，包括建表、查询、DML 以及 Redshift 特有的分析函数等。

从 operations.json 可以看到，查询表单只暴露一个 SQL 模式，其中sql_query字段使用codehinter编辑器类型，高度设置为 150px，支持在编辑器中嵌入 ToolJet 的变量与表达式（如{{ }}引用表单字段或全局变量），使得查询可以动态化。

实战示例：增删改查

以下示例均以employee表为操作对象，演示在查询面板中如何对 Redshift 集群执行四类常见操作。这些 SQL 可以直接复制到插件查询编辑器中运行。

读取数据（Read）

查询employee表的全部列：

SELECT * FROM employee

写入数据（Write）

向employee表插入一行新数据：

INSERT INTO employee ( first_name, last_name, email, phone_number, hire_date, job_title, salary, department_id ) VALUES ( 'Tom', 'Hudson', 'tom.hudson@example.com', '234843294323', '2024-01-01', 'Test Automation Engineer', 245000.00, 12 );

更新数据（Update）

按employee_id更新指定员工的姓名：

UPDATE employee SET first_name = 'Glenn', last_name = 'Jacobs' WHERE employee_id = 8;

删除数据（Delete）

按employee_id删除一行记录：

DELETE FROM employee WHERE employee_id = 7;

查询执行与结果处理原理

了解插件如何执行与返回结果，有助于你理解为什么不同 SQL 的返回值形态不一样。核心逻辑同样位于 marketplace/plugins/awsredshift/lib/index.ts 的run()方法中：

1. 语句提交与状态轮询

插件先将你的 SQL 通过ExecuteStatementCommand提交到 Redshift Data API，随后利用DescribeStatementCommand轮询语句状态，直到Status变为FINISHED。源码中轮询等待时间上限maxPollingTime为 300、轮询间隔pollingInterval为 50（单位均为毫秒），即约每 50ms 检查一次；若语句状态变为FAILED或处于ABORTED状态，会直接抛出对应错误。

2. 按 SQL 类型分流返回结果

const isSelectQuery = queryOptions.sql_query.trim().toLowerCase().startsWith('select'); const isDeleteQuery = queryOptions.sql_query.trim().toLowerCase().startsWith('delete'); const isUpdateQuery = queryOptions.sql_query.trim().toLowerCase().startsWith('update'); const isInsertQuery = queryOptions.sql_query.trim().toLowerCase().startsWith('insert');

• SELECT 语句：通过GetStatementResultCommand获取查询结果，返回值data为Records（记录数组），可直接绑定到表格、列表等组件；
• INSERT / UPDATE / DELETE 语句：返回DescribeStatementCommand的描述结果（包含影响行数等元信息）；
• 其他语句（如 DDL）：返回{ result: 'Query executed successfully', query: 原始SQL }的确认信息。

3. 错误信息结构化

当查询失败时，插件会对 AWS 返回的错误消息做结构化解析，提取code、context、location、process等字段并封装为QueryError抛出，方便你在前端看到可读性更强的错误明细，而不是一段冗长的原始报错。

安全与最佳实践

• 密钥加密存储：Secret Key 在 manifest.json 中被标记为encrypted: true，配置时应避免在查询 SQL 中硬编码任何凭证信息。
• IAM 权限最小化：由于认证基于 IAM 用户凭证，建议为数据源单独创建权限受限的 IAM 用户，仅授予连接目标数据库与执行语句所需的最小权限（如redshift-data相关动作及redshift-serverless/集群访问策略）。
• 工作区权限管理：Redshift 数据源创建后可复用给工作区内其他构建者使用；若要移除插件，请注意 Marketplace 概述中的警告——移除插件会同时清除应用中所有关联该插件的查询。
• 适用前提：插件基于 Redshift Data API，因此目标集群需满足 Redshift Data API 的可用前提（如集群公开可用或与 ToolJet 网络可达、具备相应 IAM 授权）。若你的环境无法满足，可评估 ToolJet 内置的其他数据库数据源作为替代。

小结

通过 Marketplace 的 AWS Redshift 插件，ToolJet 应用可以借助 Redshift Data API 以 IAM 认证方式安全地访问集群数据，并在 SQL 编辑器中执行从简单查询到复杂分析的全部 SQL 语句。本文既覆盖了从安装、配置到增删改查的完整实操链路，也从源码层面解释了连接建立、状态轮询、结果分流与错误解析的底层机制。相关源码可进一步查阅 marketplace/plugins/awsredshift/lib/index.ts、manifest.json 与 operations.json。

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