跳到主要内容
跳到主要内容

用于 Grafana 的 ClickHouse 数据源插件

ClickHouse Supported

借助 Grafana，你可以使用仪表盘来探索并共享所有数据。 Grafana 需要安装一个插件才能连接 ClickHouse，该插件可以在其 UI 中轻松完成安装。

1. 收集您的连接信息​

要通过原生 TCP 协议连接到 ClickHouse，需要以下信息：

Parameter(s)Description
HOST and PORT通常在使用 TLS 时端口为 9440，不使用 TLS 时端口为 9000。
DATABASE NAME默认提供名为 default 的数据库，请使用您要连接的数据库名称。
USERNAME and PASSWORD默认用户名为 default。请根据您的使用场景选择合适的用户名。

ClickHouse Cloud 服务的详细信息可以在 ClickHouse Cloud 控制台中查看。 选择要连接的服务并点击 Connect：

ClickHouse Cloud service connect button

选择 Native，示例 clickhouse-client 命令中会展示连接所需的详细信息。

ClickHouse Cloud Native TCP connection details

如果您使用的是自管的 ClickHouse，连接信息由 ClickHouse 管理员进行配置。

2. 创建只读用户​

在将 ClickHouse 连接到 Grafana 等数据可视化工具时，建议创建一个只读用户，以防止数据被非预期修改。

Grafana 不会验证查询是否安全。查询可以包含任意 SQL 语句，包括 DELETE 和 INSERT。

要配置一个只读用户，请执行以下步骤：

  1. 按照 在 ClickHouse 中创建用户和角色 指南创建一个 readonly 用户配置文件。
  2. 确保 readonly 用户拥有足够的权限来修改底层 clickhouse-go client 所需的 max_execution_time 设置。
  3. 如果您使用的是对外公开的 ClickHouse 实例，不建议在 readonly 配置文件中设置 readonly=2。相反，应保持 readonly=1，并将 max_execution_time 的约束类型设置为 changeable_in_readonly，以允许修改该设置。

3. 安装 Grafana 的 ClickHouse 插件​

在 Grafana 能连接到 ClickHouse 之前，需要先安装相应的 Grafana 插件。假设你已经登录 Grafana，请按照以下步骤操作：

  1. 在侧边栏的 Connections 页面中，选择 Add new connection 选项卡。

  2. 搜索 ClickHouse，然后点击由 Grafana Labs 提供的已签名插件：

    在 Connections 页面选择 ClickHouse 插件

  3. 在接下来的页面上，点击 Install 按钮：

    安装 ClickHouse 插件

4. 定义 ClickHouse 数据源​

  1. 安装完成后，单击 Add new data source 按钮。（您也可以在 Connections 页面中的 Data sources 选项卡里添加数据源。）

    Create a ClickHouse data source

  2. 向下滚动找到 ClickHouse 数据源类型，或者在 Add data source 页面顶部的搜索栏中搜索并选择 ClickHouse 数据源。选择后，将会出现如下页面：

Connection configuration page
  1. 输入您的服务器设置和凭证。关键设置包括：
  • Server host address：ClickHouse 服务的主机名。
  • Server port：ClickHouse 服务的端口号。端口会根据服务器配置和所用协议而不同。
  • Protocol：用于连接到 ClickHouse 服务的协议。
  • Secure connection：如果服务器要求安全连接，请启用此选项。
  • Username 和 Password：输入 ClickHouse 用户凭证。如果您尚未配置任何用户，可以尝试将用户名设置为 default。建议配置一个只读用户。

有关更多设置，请参阅 plugin configuration 插件配置文档。

  1. 单击 Save & test 按钮，以验证 Grafana 是否可以连接到您的 ClickHouse 服务。如果连接成功，您会看到一条 Data source is working 消息：

    Select Save & test

5. 后续步骤​

现在数据源已经可以使用了。请在查询构建器中了解更多关于如何构建查询的信息。

有关配置的更多详细说明，请查阅插件配置文档。

如果这些文档中未包含您需要的更多信息，请查看 GitHub 上的插件仓库。

升级插件版本​

从 v4 开始，可以在新版本发布时升级配置和查询。

v3 版本的配置和查询在打开时会自动迁移到 v4。旧的配置和仪表盘会在 v4 中加载，但只有在使用新版本重新保存之后，迁移才会被持久化。如果在打开旧的配置或查询时发现任何问题，请放弃修改并在 GitHub 上报告该问题。

如果配置或查询是由更高版本创建的，则插件无法降级到更早的版本。