Openblocks 连接 ClickHouse 数据源:配置步骤与底层插件实现解析
Openblocks 连接 ClickHouse 数据源:配置步骤与底层插件实现解析
ClickHouse 是一款面向列式存储的开源数据库管理系统,专为高速在线分析处理(OLAP)与数据仓库场景设计,能够实时处理 PB 级数据。本文基于 Openblocks 官方文档,讲解如何在 Openblocks 中创建 ClickHouse 数据源、填写连接参数、完成连通性测试并保存复用,同时结合仓库中 clickHousePlugin 的源码,深入说明 JDBC 连接串的构造、连接池参数、预编译语句开关与表结构读取等底层实现,帮助你既会操作,也知其原理。
前置准备(Prerequisites)
在开始连接之前,需要完成两项准备:
- 获取连接参数:向 ClickHouse 数据库的所有者索取连接所需的主机地址(host)、端口(port)、数据库名(database name)、用户名(user name)与密码(password)。
- 配置 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。
测试连接与保存
配置完成后,可以按需进行验证:
- (可选)Test connection(测试连接):点击测试按钮,检查新建的数据源能否成功连通。底层由 ClickHouseConnector.testConnection() 实现:它会真实地创建一个连接池连接,若创建成功则返回
DatasourceTestResult.testSuccess(),失败则捕获异常并返回testFail(error),并受创建连接超时时间限制。 - 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 负责,其执行流程要点如下:
- SQL 预处理:通过
SqlQueryUtils.removeQueryComments()去除 SQL 注释后校验非空,空 SQL 报SQL_EMPTY。 - 预编译语句开关:数据源配置中的
enableTurnOffPreparedStatement决定查询级别是否允许关闭预编译;只有当数据源开启该开关且查询自身设置了disablePreparedStatement时,才会真正以动态 SQL 方式执行(ClickHouseQueryExecutor.java#L81-L89)。默认使用PreparedStatement绑定参数,可防 SQL 注入;关闭预编译可动态拼接 SQL,但存在注入风险。 - Mustache 参数绑定:SQL 中的
{{ }}Mustache 占位符会被提取并按顺序绑定到预编译语句,支持 null、Integer、Long、Float/Double、Boolean、Map/Collection(序列化为 JSON 字符串)与 String 等类型;遇到不支持的参数类型会抛出PS_BIND_ERROR(ClickHouseQueryExecutor.java#L202-L249)。 - 结果解析:若语句返回结果集,则解析为行数据并附带列名提示(如存在重复列名会给出
DUPLICATE_COLUMN提示);否则返回affectedRows受影响行数。
表结构读取机制
在应用编辑器中,数据源面板会展示 ClickHouse 数据库的表与字段结构,该能力由 ClickHouseStructureParser 提供。它通过查询 information_schema 元数据获取当前数据库(database())下所有表及其列的序号、名称、数据类型与可空性,从而在查询编辑器中自动列出表结构。结构读取整体受 getStructureTimeoutMillis(默认 8000ms)超时保护。
小结
在 Openblocks 中接入 ClickHouse 数据源的操作路径非常清晰:先准备连接参数与 IP 白名单,再通过数据源列表或应用编辑器新建 ClickHouse 类型数据源,填写主机、端口、数据库及可选凭据后测试连接并保存,即可在查询中直接编写 SQL。底层插件实现(clickHousePlugin)通过 ClickHouse JDBC 驱动与 HikariCP 连接池管理连接,支持 SSL、动态可调的池参数、预编译语句切换与元数据结构读取,为 OLAP 分析类应用的构建提供了稳定可靠的数据通道。