Skip to main content
LibreDB Studio 是一款开源 (MIT 许可) 、自托管的 SQL IDE, 可直接在浏览器中运行。它通过 HTTP 接口连接 ClickHouse,无需 JDBC 或原生 驱动程序,并提供 SQL 编辑器、数据库浏览器、EXPLAIN 执行计划,以及基于 system 表构建的监控仪表板。

开始之前

  • 使用 Docker 运行 LibreDB Studio (docker run -p 3000:3000 ghcr.io/libredb/libredb-studio:latest) , 或使用 Node.js 24 及以上版本运行 (npx @libredb/studio) ,然后打开 http://localhost:3000。首次 运行时,管理员密码会打印到日志中。
  • 确保运行 LibreDB Studio 的机器能够访问 ClickHouse 的 HTTP 或 HTTPS 端口。
  • 创建一个 ClickHouse 用户,并授予其访问待查询数据库的权限。此外,数据库浏览器 还需要 system.dictionaries 和 system.data_skipping_indices 的 SELECT 权限,以及 每个包含字典的数据库的 dictGet 权限。如需使用仪表盘,请授予 监控 ClickHouse 中 所列 system 表的 SELECT 权限。
例如,对于查询 uk 数据库的用户 reader:

工作原理

  1. 浏览器将语句发送到 LibreDB Studio 服务器。
  2. 服务器将该语句作为 HTTP POST / 的请求正文发送给 ClickHouse,并以 URL 参数的形式传递 default_format=JSONCompact 和所选数据库,凭证则通过 HTTP 基本身份验证传递。
  3. 服务器返回结果行、ClickHouse 声明的列类型,以及 ClickHouse 报告的耗时。 每条语句都是一次独立的无状态请求,不绑定任何会话。

连接到自托管 ClickHouse

1

收集连接详情

您需要准备主机、HTTP 端口 (默认为 8123;若使用 HTTPS,则为服务器的 HTTPS 端口,通常为 8443) 、用户名和密码,数据库名称可选。如果连接未指定数据库,则使用 default。
2

创建连接

  1. 在侧边栏中选择 + (新连接) 。
  2. 选择 ClickHouse 作为数据库类型,端口会自动填充为 8123。
  3. 输入连接名称、主机、端口、用户名和密码,并可选填 数据库名称。
  4. 如需使用 HTTPS,请展开 SSL / TLS,选择 disable 以外的任一 SSL 模式,并将 端口 改为 服务器的 HTTPS 端口 (通常为 8443) 。除 disable 外,所有模式都会依据 LibreDB Studio 服务器信任的 CA 来验证服务器 证书,也就是 verify-system 所描述的行为。 该方式适用于 ClickHouse Cloud,以及证书由公共受信任 CA 签发的服务器。如果使用自签名证书或私有 CA 证书,请参阅 故障排查。
  5. 选择 测试连接,然后选择 Establish Connection。
您也可以通过 Paste URL 直接粘贴 URL,而无需逐项填写,例如 clickhouse://localhost:8123/default 或 https://reader:secret@ch.example.com:8443/analytics。 使用 https:// URL 时会自动启用 TLS。
3

运行查询

打开连接,在编辑器中编写语句并运行。数据库浏览器会列出每个 数据库中的表、视图、物化视图、字典和用户定义函数,并展示 列、主键列、数据跳过索引以及对象定义。本示例使用英国房产价格数据集。 请先按照该指南将数据加载到 uk.uk_price_paid,再将连接的数据库设置为 uk, 然后运行:

监控 ClickHouse

监控仪表板以该连接所配置的用户身份读取以下数据源: 如果用户缺少上述某张表的授权,或者 query_log 已关闭,对应面板将保持 空白,而不会导致整个仪表盘无法加载。system.query_log 采用异步方式变为已刷盘状态,因此 刚执行完的语句可能需要几秒钟才会出现。 LibreDB Studio 还可以对表执行 OPTIMIZE TABLE ... FINAL,显示某个表或数据库的 system.parts 摘要, 并通过 KILL QUERY ... SYNC 终止正在运行的查询。执行这些操作需要 具备相应的授权。

故障排查

请求由 LibreDB Studio 的服务器发出,而非你的浏览器,因此运行 LibreDB Studio 的机器或容器必须能够访问该主机。 当 LibreDB Studio 在 Docker 中运行、而 ClickHouse 运行在同一台机器上时,localhost 指向的是容器本身,而不是宿主机。请确认你输入的是 HTTP 端口,而不是原生协议端口 9000。
LibreDB Studio 的服务器基于 Node.js 运行,Node.js 会使用其自带的公共 CA 列表来校验服务器证书。它会忽略在 SSL / TLS 下粘贴的 CA 证书,而仅将 CA 添加到操作系统的证书存储中也不足以解决问题。启动 LibreDB Studio 服务器时,请将 NODE_EXTRA_CA_CERTS 环境变量设置为某个 PEM 文件的路径,该文件中包含你的 CA 证书;如果服务器证书为自签名证书,则包含服务器自身的证书。使用 Docker 时,请将 该文件挂载到容器中,并传入相应参数,例如 -e NODE_EXTRA_CA_CERTS=/certs/ca.pem。
数据库浏览器会读取 system.dictionaries 来对每个数据库中的对象进行分类,并读取 system.data_skipping_indices 来获取表的详细信息。如果没有 system.dictionaries 的 SELECT 权限, 对象列表将无法加载;如果没有 system.data_skipping_indices 的 SELECT 权限,则无法打开表的详细信息。 在用户获得字典所在数据库的 dictGet 权限之前,该字典会显示在表列表中。 请按照开始之前中的说明授予上述权限,然后刷新浏览器。
该 ClickHouse 用户无法读取监控 ClickHouse 中列出的一个或多个 system 表。请为所需的表授予 SELECT 权限,然后重新连接。
慢查询视图读取的是 system.query_log,而在查询日志关闭时,该表不会记录任何内容。 请为该用户启用 log_queries 设置 (例如在其设置配置文件中启用) ,然后运行几条 查询。日志已刷盘后即会出现新条目,这可能需要几秒钟。 如果视图仍然为空,则可能是整个服务器 (而非仅该用户) 禁用了查询日志。请按照 system.query_log 中的说明,检查服务器配置中是否包含 query_log 部分。

后续步骤