Help us learn about your current experience with the documentation. Take the survey.

ClickHouse 集成指南

Tier: 免费版, 高级版, 终极版
Offering: GitLab.com, GitLab 自托管版, GitLab 专属版
Status: 在 GitLab 自托管版和 GitLab 专属版上为 Beta 版

有关 GitLab 自托管版 ClickHouse 支持计划的更多信息，请参阅 this epic。

有关 GitLab 专属版 ClickHouse 支持的更多信息，请参阅 ClickHouse for GitLab Dedicated。

ClickHouse 是一个开源的列式数据库管理系统。它可以高效地对大型数据集进行过滤、聚合和查询。

ClickHouse 是 GitLab 的辅助数据存储。只有特定数据会存储在 ClickHouse 中，用于支持高级分析功能，如 AI 影响分析和 CI 分析。

您可以通过以下方式将 ClickHouse 连接到 GitLab：

推荐。使用 ClickHouse Cloud。
通过自建 ClickHouse。更多信息请参阅 GitLab 自托管版 ClickHouse 推荐配置。

支持的 ClickHouse 版本

首个 GitLab 版本	ClickHouse 版本	备注
17.7.0	23.x (24.x, 25.x)	使用 ClickHouse 24.x 和 25.x 请参阅解决方法部分。
18.1.0	23.x, 24.x, 25.x

支持 ClickHouse Cloud。通常可以确保与最新的主要 GitLab 版本及更高版本兼容。

设置 ClickHouse

要在 GitLab 中设置 ClickHouse：

运行和配置 ClickHouse

当您在托管服务器上运行 ClickHouse 时，各种数据点可能会影响资源消耗，例如每月在您的实例上运行的构建数量、选择的硬件、托管 ClickHouse 的数据中心选择等。无论如何，成本应该不会很高。

要创建必要的用户和数据库对象：

生成一个安全密码并保存它。
登录 ClickHouse SQL 控制台。

执行以下命令。将 PASSWORD_HERE 替换为生成的密码。

CREATE DATABASE gitlab_clickhouse_main_production;
CREATE USER gitlab IDENTIFIED WITH sha256_password BY 'PASSWORD_HERE';
CREATE ROLE gitlab_app;
GRANT SELECT, INSERT, ALTER, CREATE, UPDATE, DROP, TRUNCATE, OPTIMIZE ON gitlab_clickhouse_main_production.* TO gitlab_app;
GRANT SELECT ON information_schema.* TO gitlab_app;
GRANT gitlab_app TO gitlab;

配置 GitLab 与 ClickHouse 的连接

为 GitLab 提供 ClickHouse 凭据：

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['clickhouse_databases']['main']['database'] = 'gitlab_clickhouse_main_production'
gitlab_rails['clickhouse_databases']['main']['url'] = 'https://example.com/path'
gitlab_rails['clickhouse_databases']['main']['username'] = 'gitlab'
gitlab_rails['clickhouse_databases']['main']['password'] = 'PASSWORD_HERE' # 替换为实际密码

保存文件并重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

将 ClickHouse 密码保存为 Kubernetes Secret：

kubectl create secret generic gitlab-clickhouse-password --from-literal="main_password=PASSWORD_HERE"

导出 Helm 值：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  clickhouse:
    enabled: true
    main:
      username: default
      password:
        secret: gitlab-clickhouse-password
        key: main_password
      database: gitlab_clickhouse_main_production
      url: 'http://example.com'

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

要验证您的连接是否设置成功：

登录 Rails 控制台
执行以下命令：
```
ClickHouse::Client.select('SELECT 1', :main)
```
如果成功，命令将返回 [{"1"=>1}]

运行 ClickHouse 迁移

要创建所需的数据库对象，请执行：

sudo gitlab-rake gitlab:clickhouse:migrate

为分析功能启用 ClickHouse

现在您的 GitLab 实例已连接到 ClickHouse，您可以通过为分析功能启用 ClickHouse 来启用使用 ClickHouse 的功能。

故障排除

GitLab 18.0.0 及更早版本的数据库架构迁移

在 GitLab 18.0.0 及更早版本中，为 ClickHouse 24.x 和 25.x 运行数据库架构迁移可能会失败，并显示以下错误消息：

Code: 344. DB::Exception: Projection is fully supported in ReplacingMergeTree with deduplicate_merge_projection_mode = throw. Use 'drop' or 'rebuild' option of deduplicate_merge_projection_mode

如果不运行所有迁移，ClickHouse 集成将无法工作。

要解决此问题并运行迁移：

执行以下命令：

ClickHouse::Client.execute("INSERT INTO schema_migrations (version) VALUES ('20231114142100'), ('20240115162101')", :main)

再次迁移数据库：

sudo gitlab-rake gitlab:clickhouse:migrate

这次数据库迁移应该能成功完成。