Openblocks 连接 ClickHouse 数据源:配置步骤与底层插件实现解析

原创2026-10-11 12:18:131,933 阅读
文章标签:低代码后端前端开发工具

Openblocks 连接 ClickHouse 数据源:配置步骤与底层插件实现解析

ClickHouse 是一款面向列式存储的开源数据库管理系统,专为高速在线分析处理(OLAP)与数据仓库场景设计,能够实时处理 PB 级数据。本文基于 Openblocks 官方文档,讲解如何在 Openblocks 中创建 ClickHouse 数据源、填写连接参数、完成连通性测试并保存复用,同时结合仓库中 clickHousePlugin 的源码,深入说明 JDBC 连接串的构造、连接池参数、预编译语句开关与表结构读取等底层实现,帮助你既会操作,也知其原理。

前置准备(Prerequisites)

在开始连接之前,需要完成两项准备:

  1. 获取连接参数:向 ClickHouse 数据库的所有者索取连接所需的主机地址(host)、端口(port)、数据库名(database name)、用户名(user name)与密码(password)。
  2. 配置 IP 白名单:如果你的数据源设置了防火墙规则,需要参考 配置 IP 白名单,将 Openblocks 的 IP 地址加入白名单后再进行连接,否则后续创建数据源与执行查询都会失败。

从源码看,ClickHouse 数据源属于基于 JDBC 的 SQL 类数据源,其连接配置继承自 SqlBasedDatasourceConnectionConfig,包含 database、username、password、host、port、usingSsl、serverTimezone、isReadonly、enableTurnOffPreparedStatement 与 extParams 等字段,这也决定了前端表单与后端校验的字段范围。

创建 ClickHouse 数据源

创建新数据源的操作权限仅限工作区管理员(admins)与开发者(developers)。有两种入口方式,任选其一即可:

方式一:从数据源列表创建

进入 Openblocks 首页的 Data Sources(数据源) 标签页,点击 New data source(新建数据源) 按钮。

方式二:在应用编辑器中创建

在应用编辑器里新建查询(query)时,点击 + New > + New data source,即可直接为当前应用创建数据源。

两种入口最终都会进入数据源创建表单。在前端,ClickHouse 数据源的表单类型注册在 datasourceFormRegistry.tsx:

clickHouse: {
  form: sqlDatasourceForm({ placeholder: "My ClickHouse1", port: "8123" }),
  whitelist: true,
},

其中 sqlDatasourceForm 会渲染通用的 SQL 数据源表单(见 sqlDatasourceForm.tsx),包含数据源名称、主机、端口、数据库、用户名、密码、SSL 开关以及"允许在查询中切换预编译语句"等输入项;whitelist: true 表示该类型需要接入 IP 白名单校验流程。

选择数据源类型

在新建数据源时,选择 Database(数据库) 分类下的 ClickHouse 作为数据源类型。

填写连接配置

选定类型后,为数据源设置名称,并配置以下常规参数:

参数 说明 默认值 / 示例
数据源名称 用于在数据源库中区分不同连接,如 My ClickHouse1 占位提示 My ClickHouse1
Host ClickHouse 服务所在主机地址 必填,且不能包含 : 或 /
Port ClickHouse HTTP 端口 8123(前端表单默认值)
Database 要连接的数据库名称 必填
User name 连接用户名 可选
Password 连接密码 可选
Using SSL 是否启用 SSL 加密连接 默认关闭,开启后 JDBC 连接串 scheme 变为 https://
允许切换预编译语句 允许在查询级别关闭预编译语句,以便动态生成 SQL 默认关闭

其中 Host、Port、Database 为必填的核心项。从 ClickHouseDatasourceConfig 的源码可以看到,默认端口在 defaultPort() 中定义为 8123L,与前端表单的占位端口保持一致。

在保存连接配置时,后端 ClickHouseConnector 会执行参数校验,主要检查项包括:

  • Host 为空 → 报 HOST_EMPTY;
  • Host 中包含 : 或 /(如误填了完整 URL)→ 报 HOST_WITH_COLON;
  • Host 为 localhost 或 127.0.0.1 → 报 INVALID_HOST(Openblocks 服务端与数据库不在同一主机时无法访问本机地址);
  • Database 为空 → 报 DATABASE_NAME_EMPTY。

测试连接与保存

配置完成后,可以按需进行验证:

  1. (可选)Test connection(测试连接):点击测试按钮,检查新建的数据源能否成功连通。底层由 ClickHouseConnector.testConnection() 实现:它会真实地创建一个连接池连接,若创建成功则返回 DatasourceTestResult.testSuccess(),失败则捕获异常并返回 testFail(error),并受创建连接超时时间限制。
  2. Save(保存):点击保存后,该数据源会存入你的数据源库(data source library),之后可在任意应用的查询编辑器中复用。

连接串构造与连接池实现原理

创建连接的核心逻辑位于 ClickHouseConnector.createHikariDataSource(),其 JDBC 连接串构造规则为:

jdbc:clickhouse:<scheme><host>:<port>/<database>

其中 scheme 由 SSL 开关决定:usingSsl = true 时使用 https://,否则使用 http://。例如启用 SSL 且 host 为 ch.example.com、端口 8123、数据库 default 时,连接串为:

jdbc:clickhouse:https://ch.example.com:8123/default

连接池使用 HikariCP(版本见 pom.xml,依赖为 com.clickhouse:clickhouse-jdbc:0.3.2-patch11 的 uber jar,驱动类为 com.clickhouse.jdbc.ClickHouseDriver),并配置了以下关键池参数:

HikariCP 参数 值 说明
connectionTimeout 250ms 等待连接池给出连接的超时时间
validationTimeout 3s 连接校验超时
initializationFailTimeout 4s 初始化失败判定超时
idleTimeout 默认 6 分钟 空闲连接回收时间,可通过 connectionPoolIdleTimeoutMinutes 动态配置
maxLifetime 2 小时 连接最大生命周期
keepaliveTime 3 分钟 保活探测间隔
leakDetectionThreshold 30s 连接泄漏检测阈值
maximumPoolSize 默认 50 最大连接数,可通过 connectionPoolMaxPoolSize 动态配置
minimumIdle 1 最小空闲连接数

连接创建整体包裹在 createConnectionTimeout(默认 5000ms)超时控制内,超时会抛出 DATASOURCE_TIMEOUT_ERROR。上述 connectionPoolMaxPoolSize、connectionPoolIdleTimeoutMinutes 等可通过 ConfigCenter 动态调整。

查询执行与预编译语句开关

数据源保存后即可在应用中编写 SQL 查询。查询层由 ClickHouseQueryExecutor 负责,其执行流程要点如下:

  1. SQL 预处理:通过 SqlQueryUtils.removeQueryComments() 去除 SQL 注释后校验非空,空 SQL 报 SQL_EMPTY。
  2. 预编译语句开关:数据源配置中的 enableTurnOffPreparedStatement 决定查询级别是否允许关闭预编译;只有当数据源开启该开关且查询自身设置了 disablePreparedStatement 时,才会真正以动态 SQL 方式执行(ClickHouseQueryExecutor.java#L81-L89)。默认使用 PreparedStatement 绑定参数,可防 SQL 注入;关闭预编译可动态拼接 SQL,但存在注入风险。
  3. Mustache 参数绑定:SQL 中的 {{ }} Mustache 占位符会被提取并按顺序绑定到预编译语句,支持 null、Integer、Long、Float/Double、Boolean、Map/Collection(序列化为 JSON 字符串)与 String 等类型;遇到不支持的参数类型会抛出 PS_BIND_ERROR(ClickHouseQueryExecutor.java#L202-L249)。
  4. 结果解析:若语句返回结果集,则解析为行数据并附带列名提示(如存在重复列名会给出 DUPLICATE_COLUMN 提示);否则返回 affectedRows 受影响行数。

表结构读取机制

在应用编辑器中,数据源面板会展示 ClickHouse 数据库的表与字段结构,该能力由 ClickHouseStructureParser 提供。它通过查询 information_schema 元数据获取当前数据库(database())下所有表及其列的序号、名称、数据类型与可空性,从而在查询编辑器中自动列出表结构。结构读取整体受 getStructureTimeoutMillis(默认 8000ms)超时保护。

小结

在 Openblocks 中接入 ClickHouse 数据源的操作路径非常清晰:先准备连接参数与 IP 白名单,再通过数据源列表或应用编辑器新建 ClickHouse 类型数据源,填写主机、端口、数据库及可选凭据后测试连接并保存,即可在查询中直接编写 SQL。底层插件实现(clickHousePlugin)通过 ClickHouse JDBC 驱动与 HikariCP 连接池管理连接,支持 SSL、动态可调的池参数、预编译语句切换与元数据结构读取,为 OLAP 分析类应用的构建提供了稳定可靠的数据通道。

登录后查看全文
openblocks