ClickHouse

요약

ClickHouse는 오픈 소스 열 지향 데이터베이스 관리 시스템입니다. GitLab은 GitLab Duo, SDLC 트렌드, CI 분석과 같은 고급 분석 기능을 활성화하기 위한 보조 데이터 저장소로 ClickHouse를 사용합니다.

히스토리

GitLab 18.11에서 GitLab Self-Managed에 대해 일반 공개됨.

ClickHouse는 오픈 소스 열 지향 데이터베이스 관리 시스템입니다. 대규모 데이터 세트에서 효율적으로 필터링, 집계 및 쿼리를 수행할 수 있습니다.

GitLab은 GitLab Duo, SDLC 트렌드, CI 분석과 같은 고급 분석 기능을 활성화하기 위한 보조 데이터 저장소로 ClickHouse를 사용합니다. GitLab은 이러한 기능을 지원하는 데이터만 ClickHouse에 저장합니다.

ClickHouse를 GitLab에 연결하려면 ClickHouse Cloud를 사용해야 합니다.

또는 자체 ClickHouse를 가져올 수도 있습니다. 자세한 내용은 GitLab Self-Managed를 위한 ClickHouse 권장 사항을 참조하세요.

ClickHouse로 사용 가능한 분석#

ClickHouse를 구성한 후 다음 분석 기능을 사용할 수 있습니다:

기능	설명
러너 플릿 대시보드	러너 사용량 메트릭과 잡 대기 시간을 표시합니다. 러너 유형과 잡 상태별 잡 수 및 실행된 러너 분을 포함하는 CSV 파일 내보내기를 제공합니다.
기여 분석	시간 경과에 따른 그룹 구성원 기여(푸시 이벤트, 이슈, 머지 리퀘스트)의 분석을 제공합니다. ClickHouse는 대규모 인스턴스의 타임아웃 문제 가능성을 줄입니다.
GitLab Duo 및 SDLC 트렌드	GitLab Duo가 소프트웨어 개발 성능에 미치는 영향을 측정합니다. AI 관련 지표(GitLab Duo 시트 도입, 코드 제안 승인률, GitLab Duo Chat 사용)와 함께 개발 메트릭(배포 빈도, 리드 타임, 변경 실패율, 복구 시간)을 추적합니다.
AI 메트릭용 GraphQL API	AiMetrics, AiUserMetrics, AiUsageData 엔드포인트를 통해 GitLab Duo 및 SDLC 트렌드 데이터에 프로그래밍 방식으로 액세스를 제공합니다. BI 도구 및 사용자 정의 분석을 위한 사전 집계된 메트릭과 원시 이벤트 데이터 내보내기를 제공합니다.

지원되는 ClickHouse 버전#

지원되는 ClickHouse 버전은 GitLab 버전에 따라 다릅니다:

GitLab 17.7 이상은 ClickHouse 23.x를 지원합니다. ClickHouse 24.x 또는 25.x를 사용하려면 해결 방법을 사용하세요.
GitLab 18.1 이상은 ClickHouse 23.x, 24.x, 25.x를 지원합니다.
GitLab 18.8 이상은 ClickHouse 23.x, 24.x, 25.x 및 Replicated 데이터베이스 엔진을 지원합니다.

이전 클러스터는 추가 권한(dictGet)이 필요합니다. 스니펫을 참조하세요.

GitLab 19.0 이상은 ClickHouse 25.x 및 26.x를 지원합니다. ClickHouse 23.x 및 24.x 지원이 제거되었습니다.

ClickHouse Cloud는 항상 최신 안정 GitLab 릴리스와 호환됩니다.

Note

ClickHouse 25.12를 사용하는 경우, ALTER MODIFY COLUMN에 하위 호환되지 않는 변경이 도입되었습니다. 이는 18.8 이전 버전의 GitLab ClickHouse 통합 마이그레이션 프로세스를 중단시킵니다. GitLab을 18.8 이상 버전으로 업그레이드해야 합니다.

ClickHouse 설정#

운영 요구 사항에 따라 배포 유형을 선택하세요:

ClickHouse Cloud (권장): 자동 업그레이드, 백업, 스케일링이 포함된 완전 관리형 서비스.
GitLab Self-Managed용 ClickHouse (BYOC): 인프라와 구성에 대한 완전한 제어.

ClickHouse 인스턴스를 설정한 후:

ClickHouse Cloud 설정#

사전 요구 사항:

ClickHouse Cloud 계정이 있어야 합니다.
GitLab 인스턴스에서 ClickHouse Cloud로의 네트워크 연결을 활성화합니다.
GitLab 인스턴스의 관리자여야 합니다.

ClickHouse Cloud를 설정하려면:

ClickHouse Cloud에 로그인합니다.
New Service를 선택합니다.
서비스 티어를 선택합니다:

Development: 테스트 및 개발 환경용.
- Production: 고가용성 프로덕션 워크로드용.
클라우드 공급자와 리전을 선택합니다. 최적의 성능을 위해 GitLab 인스턴스와 가까운 리전을 선택합니다.
서비스 이름과 설정을 구성합니다.
Create Service를 선택합니다.
프로비저닝이 완료되면 서비스 대시보드에서 연결 세부 정보를 확인합니다:
- 호스트
- 포트 (8443 - GitLab이 사용하는 HTTPS 연결, 또는 clickhouse-client가 사용하는 TLS 포함 네이티브 TCP의 경우 9440)
- 사용자 이름
- 비밀번호

Note

ClickHouse Cloud는 버전 업그레이드와 보안 패치를 자동으로 처리합니다. Enterprise Edition (EE) 고객은 업그레이드 일정을 예약하여 발생 시기를 제어하고 업무 시간 중 예기치 않은 서비스 중단을 방지할 수 있습니다. 자세한 내용은 ClickHouse 업그레이드를 참조하세요.

ClickHouse Cloud 서비스를 생성한 후 GitLab 데이터베이스 및 사용자를 생성합니다.

GitLab Self-Managed용 ClickHouse 설정 (BYOC)#

사전 요구 사항:

ClickHouse 인스턴스가 설치되어 실행 중이어야 합니다. ClickHouse가 설치되어 있지 않은 경우 다음을 참조하세요:
- ClickHouse 공식 설치 가이드.
- GitLab Self-Managed를 위한 ClickHouse 권장 사항.
지원되는 ClickHouse 버전이 있어야 합니다.
GitLab 인스턴스에서 ClickHouse로의 네트워크 연결을 활성화합니다.
ClickHouse와 GitLab 인스턴스 모두의 관리자여야 합니다.

Note

GitLab Self-Managed용 ClickHouse의 경우 버전 업그레이드, 보안 패치, 백업 계획 및 실행에 대한 책임이 있습니다. 자세한 내용은 ClickHouse 업그레이드를 참조하세요.

고가용성 구성#

다중 노드 고가용성(HA) 설정의 경우 GitLab은 ClickHouse의 Replicated 테이블 엔진을 지원합니다.

사전 요구 사항:

여러 노드가 있는 ClickHouse 클러스터. 최소 3개의 노드를 권장합니다.
remote_servers 구성 섹션에서 클러스터를 정의합니다.
ClickHouse 구성에서 다음 매크로를 구성합니다:
- cluster
- shard
- replica

HA를 위한 데이터베이스를 구성할 때는 ON CLUSTER 절과 함께 문을 실행해야 합니다.

자세한 내용은 ClickHouse Replicated 데이터베이스 엔진 문서를 참조하세요.

로드 밸런서 구성#

GitLab 애플리케이션은 HTTP/HTTPS 인터페이스를 통해 ClickHouse 클러스터와 통신합니다. HA 배포의 경우 HTTP 프록시 또는 로드 밸런서를 사용하여 ClickHouse 클러스터 노드 전체에 요청을 분산합니다.

권장 로드 밸런서 옵션:

chproxy - 내장 캐싱 및 라우팅이 있는 ClickHouse 전용 HTTP 프록시.
HAProxy - 범용 TCP/HTTP 로드 밸런서.
NGINX - 로드 밸런싱 기능이 있는 웹 서버.
클라우드 공급자 로드 밸런서 (AWS Application Load Balancer, GCP Load Balancer, Azure Load Balancer).

기본 chproxy 구성 예시:

server:
  http:
    listen_addr: ":8080"

clusters:
  - name: "clickhouse_cluster"
    nodes: [
      "http://ch-node1:8123",
      "http://ch-node2:8123",
      "http://ch-node3:8123"
    ]

users:
  - name: "gitlab"
    password: "your_secure_password"
    to_cluster: "clickhouse_cluster"
    to_user: "gitlab"

로드 밸런서를 사용하는 경우 개별 ClickHouse 노드 대신 로드 밸런서 URL에 연결하도록 GitLab을 구성합니다.

자세한 내용은 chproxy 문서를 참조하세요.

GitLab Self-Managed용 ClickHouse 인스턴스를 구성한 후 GitLab 데이터베이스 및 사용자를 생성합니다.

ClickHouse 설치 확인#

데이터베이스를 구성하기 전에 ClickHouse가 설치되어 액세스 가능한지 확인합니다:

ClickHouse가 실행 중인지 확인합니다:
```
clickhouse-client --query "SELECT version()"
```
ClickHouse가 실행 중이면 버전 번호(예: 24.3.1.12)가 표시됩니다.
자격 증명으로 연결할 수 있는지 확인합니다:
```
clickhouse-client --host your-clickhouse-host --port 9440 --secure --user default --password 'your-password'
```
[!note] TLS를 아직 구성하지 않은 경우 초기 테스트를 위해 --secure 플래그 없이 포트 9000을 사용하세요.

데이터베이스 및 사용자 생성#

필요한 사용자와 데이터베이스 객체를 생성하려면:

안전한 비밀번호를 생성하고 저장합니다.
다음에 로그인합니다:
- ClickHouse Cloud: ClickHouse SQL 콘솔.
- GitLab Self-Managed용 ClickHouse: clickhouse-client.
다음 명령을 실행하고 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, dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app;
   GRANT SELECT ON information_schema.* TO gitlab_app;
   GRANT gitlab_app TO gitlab;

CLUSTER_NAME_HERE를 클러스터 이름으로 교체합니다:

CREATE DATABASE gitlab_clickhouse_main_production ON CLUSTER CLUSTER_NAME_HERE ENGINE = Replicated('/clickhouse/databases/{cluster}/gitlab_clickhouse_main_production', '{shard}', '{replica}');
CREATE USER gitlab IDENTIFIED WITH sha256_password BY 'PASSWORD_HERE' ON CLUSTER CLUSTER_NAME_HERE;
CREATE ROLE gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT SELECT, INSERT, ALTER, CREATE, UPDATE, DROP, TRUNCATE, OPTIMIZE, dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT SELECT ON information_schema.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT gitlab_app TO gitlab ON CLUSTER CLUSTER_NAME_HERE;

GitLab 연결 구성#

GitLab에 ClickHouse 자격 증명을 제공하려면:

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['clickhouse_databases']['main']['database'] = 'gitlab_clickhouse_main_production'
gitlab_rails['clickhouse_databases']['main']['url'] = 'https://your-clickhouse-host:port'
gitlab_rails['clickhouse_databases']['main']['username'] = 'gitlab'
gitlab_rails['clickhouse_databases']['main']['password'] = 'PASSWORD_HERE' # 실제 비밀번호로 교체

URL을 다음으로 교체합니다:

ClickHouse Cloud: https://your-service.clickhouse.cloud:8443
GitLab Self-Managed용 ClickHouse: https://your-clickhouse-host:8443
로드 밸런서가 있는 GitLab Self-Managed HA용 ClickHouse: https://your-load-balancer:8080 (또는 로드 밸런서 URL)

파일을 저장하고 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: gitlab
      password:
        secret: gitlab-clickhouse-password
        key: main_password
      database: gitlab_clickhouse_main_production
      url: 'https://your-clickhouse-host:port'

URL을 다음으로 교체합니다:

ClickHouse Cloud: https://your-service.clickhouse.cloud:8443
GitLab Self-Managed 단일 노드: https://your-clickhouse-host:8443
로드 밸런서가 있는 GitLab Self-Managed HA: https://your-load-balancer:8080 (또는 로드 밸런서 URL)

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Note

프로덕션 배포의 경우 ClickHouse 인스턴스에서 TLS/SSL을 구성하고 https:// URL을 사용하세요. GitLab Self-Managed 설치의 경우 네트워크 보안 문서를 참조하세요.

연결 확인#

연결이 성공적으로 설정되었는지 확인하려면:

Rails 콘솔에 로그인합니다.
다음 명령을 실행합니다:
```
ClickHouse::Client.select('SELECT 1', :main)
```
성공하면 명령이 [{"1"=>1}]을 반환합니다.

연결이 실패하면 다음을 확인합니다:
- ClickHouse 서비스가 실행 중이고 액세스 가능한지.
- GitLab에서 ClickHouse로의 네트워크 연결. 방화벽과 보안 그룹이 연결을 허용하는지 확인합니다.
- 연결 URL이 올바른지 (호스트, 포트, 프로토콜).
- 자격 증명이 올바른지.
- HA 클러스터 배포의 경우: 로드 밸런서가 올바르게 구성되어 요청을 라우팅하는지.

ClickHouse 마이그레이션 실행#

Warning

이 단계는 필수입니다. 건너뛰면 Analytics 대시보드에 데이터가 표시되지 않고 "Failed to fetch data" 오류가 표시됩니다.

필요한 데이터베이스 객체를 생성하려면 다음을 실행합니다:

sudo gitlab-rake gitlab:clickhouse:migrate

마이그레이션은 GitLab-Migrations 차트와 함께 자동으로 실행됩니다.

또는 Toolbox 파드에서 다음 명령을 실행하여 마이그레이션을 실행할 수 있습니다:

gitlab-rake gitlab:clickhouse:migrate

분석을 위한 ClickHouse 활성화#

GitLab 인스턴스가 ClickHouse에 연결된 후 ClickHouse를 사용하는 기능을 활성화할 수 있습니다:

사전 요구 사항:

인스턴스에 대한 관리자 액세스가 있어야 합니다.
ClickHouse 연결이 구성되고 확인되었어야 합니다.
마이그레이션이 성공적으로 완료되었어야 합니다.

분석을 위한 ClickHouse를 활성화하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
Enable ClickHouse for Analytics를 선택합니다.
Save changes를 선택합니다.

분석을 위한 ClickHouse 비활성화#

분석을 위한 ClickHouse를 비활성화하려면:

사전 요구 사항:

인스턴스에 대한 관리자 액세스가 있어야 합니다.

비활성화하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
Enable ClickHouse for Analytics 체크박스를 해제합니다.
Save changes를 선택합니다.

Note

분석을 위한 ClickHouse를 비활성화하면 GitLab이 ClickHouse를 쿼리하지 않지만 ClickHouse 인스턴스에서 데이터를 삭제하지는 않습니다. ClickHouse에 의존하는 분석 기능은 대체 데이터 소스로 대체되거나 사용할 수 없게 됩니다.

ClickHouse 업그레이드#

ClickHouse Cloud#

ClickHouse Cloud는 버전 업그레이드와 보안 패치를 자동으로 처리합니다. 수동 개입이 필요하지 않습니다.

업그레이드 일정 및 유지 관리 창에 대한 정보는 ClickHouse Cloud 업그레이드를 참조하세요.

Note

ClickHouse Cloud는 예정된 업그레이드를 사전에 알려줍니다. 새로운 기능과 변경 사항에 대한 최신 정보를 유지하려면 ClickHouse Cloud 변경 로그를 검토하세요.

GitLab Self-Managed용 ClickHouse (BYOC)#

GitLab Self-Managed용 ClickHouse의 경우 버전 업그레이드 계획 및 실행에 대한 책임이 있습니다.

사전 요구 사항:

ClickHouse 인스턴스에 대한 관리자 액세스가 있어야 합니다.
업그레이드 전에 데이터를 백업합니다. 재해 복구를 참조하세요.

업그레이드 전:

호환성이 손상된 변경 사항에 대한 ClickHouse 릴리스 노트를 검토합니다.
GitLab 버전과의 호환성을 확인합니다.
비프로덕션 환경에서 업그레이드를 테스트합니다.
잠재적인 다운타임을 계획하거나 HA 클러스터의 경우 롤링 업그레이드 전략을 사용합니다.

ClickHouse를 업그레이드하려면:

단일 노드 배포의 경우 ClickHouse 업그레이드 문서를 따릅니다.
HA 클러스터 배포의 경우 다운타임을 최소화하기 위해 롤링 업그레이드를 수행합니다:
1. 한 번에 하나씩 노드를 업그레이드합니다.
2. 노드가 클러스터에 재참여할 때까지 기다립니다.
3. 다음 노드로 진행하기 전에 클러스터 상태를 확인합니다.

Warning

ClickHouse 버전이 GitLab 버전과 호환되는지 항상 확인하세요. 호환되지 않는 버전은 인덱싱이 일시 중지되고 기능이 실패할 수 있습니다. 자세한 내용은 지원되는 ClickHouse 버전을 참조하세요.

자세한 업그레이드 절차는 ClickHouse 업데이트 문서를 참조하세요.

운영#

마이그레이션 상태 확인#

사전 요구 사항:

인스턴스에 대한 관리자 액세스가 있어야 합니다.

ClickHouse 마이그레이션 상태를 확인하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
사용 가능한 경우 Migration status 섹션을 검토합니다.

또는 Rails 콘솔을 사용하여 보류 중인 마이그레이션을 확인합니다:

# Rails 콘솔에 로그인
# 마이그레이션을 확인하기 위해 실행
ClickHouse::MigrationSupport::Migrator.new(:main).pending_migrations

실패한 마이그레이션 재시도#

ClickHouse 마이그레이션이 실패하면:

오류 세부 정보에 대한 로그를 확인합니다. ClickHouse 관련 오류는 GitLab 애플리케이션 로그에 기록됩니다.
기본 문제를 해결합니다(예: 메모리 부족, 연결 문제).

마이그레이션을 재시도합니다:

# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:clickhouse:migrate

# 자체 컴파일 설치의 경우
bundle exec rake gitlab:clickhouse:migrate RAILS_ENV=production

Note

마이그레이션은 멱등성이 있도록 설계되어 있어 재시도하기에 안전합니다. 마이그레이션이 중간에 실패하면 다시 실행하면 중단된 곳부터 재개하거나 이미 완료된 단계를 건너뜁니다.

ClickHouse Rake 태스크#

GitLab은 ClickHouse 데이터베이스를 관리하기 위한 여러 Rake 태스크를 제공합니다.

사용 가능한 Rake 태스크:

태스크	설명
`sudo gitlab-rake gitlab:clickhouse:migrate`	데이터베이스 스키마를 생성하거나 업데이트하기 위해 모든 보류 중인 ClickHouse 마이그레이션을 실행합니다.
`sudo gitlab-rake gitlab:clickhouse:drop`	모든 ClickHouse 데이터베이스를 삭제합니다. 모든 데이터가 삭제되므로 극도로 주의해서 사용하세요.
`sudo gitlab-rake gitlab:clickhouse:create`	ClickHouse 데이터베이스가 없는 경우 생성합니다.
`sudo gitlab-rake gitlab:clickhouse:setup`	데이터베이스를 생성하고 모든 마이그레이션을 실행합니다. create와 migrate 태스크를 실행하는 것과 동일합니다.
`sudo gitlab-rake gitlab:clickhouse:schema:dump`	백업 또는 버전 제어를 위해 현재 데이터베이스 스키마를 파일로 덤프합니다.
`sudo gitlab-rake gitlab:clickhouse:schema:load`	덤프 파일에서 데이터베이스 스키마를 로드합니다.

Note

자체 컴파일 설치의 경우 sudo gitlab-rake 대신 bundle exec rake를 사용하고 명령 끝에 RAILS_ENV=production을 추가합니다.

일반적인 태스크 예시#

ClickHouse 연결 및 스키마 확인#

ClickHouse 연결이 작동하는지 확인하려면:

# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:clickhouse:info

# 자체 컴파일 설치의 경우
bundle exec rake gitlab:clickhouse:info RAILS_ENV=production

이 태스크는 ClickHouse 연결 및 구성에 대한 디버깅 정보를 출력합니다.

모든 마이그레이션 재실행#

보류 중인 모든 마이그레이션을 실행하려면:

# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:clickhouse:migrate

# 자체 컴파일 설치의 경우
bundle exec rake gitlab:clickhouse:migrate RAILS_ENV=production

데이터베이스 초기화#

Warning

이 작업은 ClickHouse 데이터베이스의 모든 데이터를 삭제합니다. 개발 환경이나 문제 해결 시에만 사용하세요.

데이터베이스를 삭제하고 재생성하려면:

# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:clickhouse:drop
sudo gitlab-rake gitlab:clickhouse:setup

# 자체 컴파일 설치의 경우
bundle exec rake gitlab:clickhouse:drop RAILS_ENV=production
bundle exec rake gitlab:clickhouse:setup RAILS_ENV=production

환경 변수#

Rake 태스크 동작을 제어하기 위해 환경 변수를 사용할 수 있습니다:

환경 변수	데이터 유형	설명
`VERBOSE`	Boolean	마이그레이션 중 자세한 출력을 보려면 `true`로 설정합니다. 예: `VERBOSE=true sudo gitlab-rake gitlab:clickhouse:migrate`

성능 조정#

Note

사용자 수에 따른 리소스 크기 조정 및 배포 권장 사항은 시스템 요구 사항을 참조하세요.

ClickHouse 아키텍처 및 성능 조정에 대한 정보는 ClickHouse 아키텍처 문서를 참조하세요.

재해 복구#

백업 및 복원#

GitLab 애플리케이션을 업그레이드하기 전에 전체 백업을 수행해야 합니다. ClickHouse 데이터는 GitLab 백업 도구에 포함되지 않습니다.

백업 및 복원 전략은 배포 선택에 따라 다릅니다.

ClickHouse Cloud#

ClickHouse Cloud는 자동으로:

백업 및 복원을 관리합니다.
매일 백업을 생성하고 보존합니다.

추가 구성이 필요하지 않습니다.

자세한 내용은 ClickHouse Cloud 백업을 참조하세요.

GitLab Self-Managed용 ClickHouse#

자체 ClickHouse 인스턴스를 관리하는 경우 데이터 안전을 위해 정기적으로 백업을 수행해야 합니다:

시스템 테이블(metrics 또는 logs 등 제외)의 초기 전체 백업을 오브젝트 스토리지 버킷(예: AWS S3)으로 가져옵니다.
이 초기 전체 백업 후 증분 백업을 수행합니다.

이 방식은 모든 전체 백업에 대한 데이터를 복제하지만 데이터를 복원하는 가장 쉬운 방법입니다.

또는 clickhouse-backup을 사용합니다. 이는 예약 및 원격 스토리지 관리와 같은 추가 기능이 있는 서드파티 도구입니다.

모니터링#

GitLab 통합의 안정성을 보장하기 위해 ClickHouse 클러스터의 상태와 성능을 모니터링해야 합니다.

ClickHouse Cloud#

ClickHouse Cloud는 보안 API 엔드포인트를 통해 메트릭을 노출하는 기본 Prometheus 통합을 제공합니다.

API 자격 증명을 생성한 후 ClickHouse Cloud에서 메트릭을 스크레이핑하도록 수집기를 구성할 수 있습니다. 예를 들어 Prometheus 배포.

GitLab Self-Managed용 ClickHouse#

ClickHouse는 Prometheus 형식의 메트릭을 노출할 수 있습니다. 이를 활성화하려면:

config.xml의 prometheus 섹션을 구성하여 전용 포트(기본값 9363)에서 메트릭을 노출합니다:

<prometheus>
    <endpoint>/metrics</endpoint>
    <port>9363</port>
    <metrics>true</metrics>
    <events>true</events>
    <asynchronous_metrics>true</asynchronous_metrics>
</prometheus>

http://<clickhouse-host>:9363/metrics에서 스크레이핑하도록 Prometheus 또는 호환 서버를 구성합니다.

모니터링할 메트릭#

GitLab 기능에 영향을 줄 수 있는 문제를 감지하기 위해 다음 메트릭에 대한 알림을 설정해야 합니다:

메트릭 이름	설명	알림 임계값 (권장)
`ClickHouse_Metrics_Query`	현재 실행 중인 쿼리 수. 갑작스러운 급증은 성능 병목을 나타낼 수 있습니다.	기준 편차 (예: > 100)
`ClickHouseProfileEvents_FailedSelectQuery`	실패한 선택 쿼리 수	기준 편차 (예: > 50)
`ClickHouseProfileEvents_FailedInsertQuery`	실패한 삽입 쿼리 수	기준 편차 (예: > 10)
`ClickHouse_AsyncMetrics_ReadonlyReplica`	복제본이 읽기 전용 모드로 전환되었는지 나타냅니다(종종 ZooKeeper 연결 손실로 인해).	> 0 (즉각 조치 필요)
`ClickHouse_ProfileEvents_NetworkErrors`	네트워크 오류 (연결 재설정/타임아웃). 빈번한 오류는 GitLab 백그라운드 잡 실패를 유발할 수 있습니다.	Rate > 0

활성 상태 확인#

ClickHouse가 로드 밸런서 뒤에 있는 경우 HTTP /ping 엔드포인트를 사용하여 활성 상태를 확인할 수 있습니다. 예상 응답은 HTTP 코드 200과 함께 Ok입니다.

보안 및 감사#

데이터 보안을 보장하고 감사 가능성을 확보하려면 다음 보안 관행을 사용합니다.

네트워크 보안#

TLS 암호화: ClickHouse 서버가 연결을 검증하기 위해 TLS 암호화를 사용하도록 구성합니다.

GitLab에서 연결 URL을 구성할 때 https:// 프로토콜(예: https://clickhouse.example.com:8443)을 사용해야 합니다.
IP 허용 목록: ClickHouse 포트(기본값 8443 또는 9440)에 대한 액세스를 GitLab 애플리케이션 노드 및 기타 인가된 네트워크로만 제한합니다.

감사 로깅#

GitLab 애플리케이션은 개별 ClickHouse 쿼리에 대한 별도의 감사 로그를 유지하지 않습니다. 데이터 액세스(누가 언제 무엇을 쿼리했는지)에 관한 특정 요구 사항을 충족하려면 ClickHouse 측에서 로깅을 활성화할 수 있습니다.

ClickHouse Cloud#

ClickHouse Cloud에서는 쿼리 로깅이 기본적으로 활성화되어 있습니다. system.query_log 테이블을 쿼리하여 이 로그에 액세스할 수 있습니다.

GitLab Self-Managed용 ClickHouse#

자체 관리 인스턴스의 경우 서버 구성에서 query_log 구성 파라미터가 활성화되어 있는지 확인합니다:

config.xml 또는 users.xml에 query_log 섹션이 있는지 확인합니다:

<query_log>
    <database>system</database>
    <table>query_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <ttl>event_date + INTERVAL 30 DAY</ttl>  <!-- 30일만 유지 -->
</query_log>

활성화되면 실행된 모든 쿼리가 system.query_log 테이블에 기록되어 감사 추적이 가능합니다.

시스템 요구 사항#

권장 시스템 요구 사항은 사용자 수에 따라 다릅니다.

배포 결정 매트릭스 빠른 참조#

사용자	기본 권장 사항	비교 가능한 AWS ARM 인스턴스	비교 가능한 GCP ARM 인스턴스	비교 가능한 Azure ARM 인스턴스	배포 유형
1K	ClickHouse Cloud Basic	-	-	-	관리형
2K	ClickHouse Cloud Basic	m8g.xlarge	c4a-standard-4	Standard_D4ps_v6	관리형 또는 단일 노드
3K	ClickHouse Cloud Scale	m8g.2xlarge	c4a-standard-8	Standard_D8ps_v6	관리형 또는 단일 노드
5K	ClickHouse Cloud Scale	m8g.4xlarge	c4a-standard-16	Standard_D16ps_v6	관리형 또는 단일 노드
10K	ClickHouse Cloud Scale	m8g.4xlarge	c4a-standard-16	Standard_D16ps_v6	관리형 또는 단일 노드/HA
25K	GitLab Self-Managed용 ClickHouse 또는 ClickHouse Cloud Scale	m8g.8xlarge 또는 3×m8g.4xlarge	c4a-standard-32 또는 3×c4a-standard-16	Standard_D32ps_v6 또는 3×Standard_D16ps_v6	관리형 또는 단일 노드/HA
50K	GitLab Self-Managed용 ClickHouse HA 또는 ClickHouse Cloud Scale	3×m8g.4xlarge	3×c4a-standard-16	3×Standard_D16ps_v6	관리형 또는 HA 클러스터

1K 사용자#

권장 사항: ClickHouse Cloud Basic - 운영 복잡성 없이 좋은 비용 효율성을 제공합니다.

2K 사용자#

권장 사항: ClickHouse Cloud Basic - 운영 복잡성 없이 최고의 가치를 제공합니다.

GitLab Self-Managed 배포를 위한 대안 권장 사항:

AWS: m8g.xlarge (4 vCPU, 16 GB)
GCP: c4a-standard-4 또는 n4-standard-4 (4 vCPU, 16 GB)
Azure: Standard_D4ps_v6 (4 vCPU, 16 GB)
스토리지: 낮음-중간 성능 티어의 20 GB

3K 사용자#

권장 사항: ClickHouse Cloud Scale

GitLab Self-Managed 배포를 위한 대안 권장 사항:

AWS: m8g.2xlarge (8 vCPU, 32 GB)
GCP: c4a-standard-8 또는 n4-standard-8 (8 vCPU, 32 GB)
Azure: Standard_D8ps_v6 (8 vCPU, 32 GB)
스토리지: 중간 성능 티어의 100 GB

Note

이 규모에서는 HA 배포가 비용 효율적이지 않습니다.

5K 사용자#

권장 사항: ClickHouse Cloud Scale

GitLab Self-Managed 배포를 위한 대안 권장 사항:

AWS: m8g.4xlarge (16 vCPU, 64 GB)
GCP: c4a-standard-16 또는 n4-standard-16 (16 vCPU, 64 GB)
Azure: Standard_D16ps_v6 (16 vCPU, 64 GB)
스토리지: 높은 성능 티어의 100 GB
배포: 단일 노드 권장

10K 사용자#

권장 사항: ClickHouse Cloud Scale

GitLab Self-Managed 배포를 위한 대안 권장 사항:

AWS: m8g.4xlarge (16 vCPU, 64 GB)
GCP: c4a-standard-16 또는 n4-standard-16 (16 vCPU, 64 GB)
Azure: Standard_D16ps_v6 (16 vCPU, 64 GB)
스토리지: 높은 성능 티어의 200 GB
HA 옵션: 중요 워크로드의 경우 3노드 클러스터 가능

25K 사용자#

권장 사항: ClickHouse Cloud Scale 또는 GitLab Self-Managed용 ClickHouse. 이 규모에서는 두 옵션 모두 경제적으로 실행 가능합니다.

GitLab Self-Managed 배포를 위한 권장 사항:

단일 노드:
- AWS: m8g.8xlarge (32 vCPU, 128 GB)
- GCP: c4a-standard-32 또는 n4-standard-32 (32 vCPU, 128 GB)
- Azure: Standard_D32ps_v6 (32 vCPU, 128 GB)
HA 배포:
- AWS: 3 × m8g.4xlarge (16 vCPU, 64 GB 각)
- GCP: 3 × c4a-standard-16 또는 3 × n4-standard-16 (16 vCPU, 64 GB 각)
- Azure: 3 × Standard_D16ps_v6 (16 vCPU, 64 GB 각)
스토리지: 높은 성능 티어의 노드당 400 GB.

50K 사용자#

권장 사항: GitLab Self-Managed용 ClickHouse HA 또는 ClickHouse Cloud Scale. 이 규모에서는 자체 관리 옵션이 약간 더 비용 효율적입니다.

GitLab Self-Managed 배포를 위한 권장 사항:

단일 노드:
- AWS: m8g.8xlarge (32 vCPU, 128 GB)
- GCP: c4a-standard-32 또는 n4-standard-32 (32 vCPU, 128 GB)
- Azure: Standard_D32ps_v6 (32 vCPU, 128 GB)
HA 배포 (권장):
- AWS: 3 × m8g.4xlarge (16 vCPU, 64 GB 각)
- GCP: 3 × c4a-standard-16 또는 3 × n4-standard-16 (16 vCPU, 64 GB 각)
- Azure: 3 × Standard_D16ps_v6 (16 vCPU, 64 GB 각)
스토리지: 높은 성능 티어의 노드당 1000 GB.

GitLab Self-Managed 배포용 HA 고려 사항#

HA 설정은 10k 사용자 이상에서만 비용 효율적입니다.

최소: 쿼럼을 위한 세 개의 ClickHouse 노드.
ClickHouse Keeper: 코디네이션을 위한 세 개의 노드 (공동 배치 또는 별도).
로드 밸런서: 쿼리 분산을 위해 권장.
네트워크: 노드 간 저지연 연결이 중요합니다.

용어집#

클러스터: 데이터를 저장하고 처리하기 위해 함께 작동하는 노드(서버) 모음.
MergeTree: MergeTree는 높은 데이터 수집률과 대규모 데이터 볼륨을 위해 설계된 ClickHouse의 테이블 엔진입니다. 열 지향 스토리지, 사용자 정의 파티셔닝, 스파스 기본 인덱스, 백그라운드 데이터 병합 지원 등의 기능을 제공하는 ClickHouse의 핵심 스토리지 엔진입니다.
파츠(Parts): 테이블 데이터의 일부를 저장하는 디스크의 물리적 파일. 파츠는 파티션 키를 사용하여 생성된 테이블 데이터의 논리적 분할인 파티션과 다릅니다.
복제본(Replica): ClickHouse 데이터베이스에 저장된 데이터의 복사본. 중복성 및 신뢰성을 위해 동일한 데이터의 복제본을 여러 개 가질 수 있습니다. 복제본은 ReplicatedMergeTree 테이블 엔진과 함께 사용되어 ClickHouse가 다른 서버 간에 여러 데이터 사본을 동기화된 상태로 유지할 수 있도록 합니다.
샤드(Shard): 데이터의 하위 집합. ClickHouse는 항상 데이터에 대해 최소 하나의 샤드를 갖습니다. 여러 서버에 데이터를 분할하지 않으면 데이터는 하나의 샤드에 저장됩니다. 단일 서버의 용량을 초과하는 경우 여러 서버에 데이터를 샤딩하여 부하를 분산할 수 있습니다.
TTL (Time To Live): TTL(Time To Live)은 특정 기간 후에 열/행을 자동으로 이동, 삭제 또는 롤업하는 ClickHouse 기능입니다. 더 이상 자주 액세스할 필요가 없는 데이터를 삭제, 이동 또는 보관할 수 있으므로 스토리지를 더 효율적으로 관리할 수 있습니다.

문제 해결#

GitLab 18.0.0 이하에서 데이터베이스 스키마 마이그레이션#

Warning

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 통합이 작동하지 않습니다.

이 문제를 해결하고 마이그레이션을 실행하려면:

Rails 콘솔에 로그인합니다.

다음 명령을 실행합니다:

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

데이터베이스를 다시 마이그레이션합니다:
```
sudo gitlab-rake gitlab:clickhouse:migrate
```

이번에는 데이터베이스 마이그레이션이 성공적으로 완료됩니다.

데이터베이스 딕셔너리 읽기 지원#

GitLab 18.8부터 GitLab은 데이터 비정규화를 위해 ClickHouse 딕셔너리를 사용하기 시작했습니다. 18.8 이전의 GRANT 문은 gitlab 사용자에게 딕셔너리를 쿼리할 권한을 부여하지 않았으므로 수동 수정 단계가 필요합니다:

다음에 로그인합니다:
- ClickHouse Cloud: ClickHouse SQL 콘솔.
- GitLab Self-Managed용 ClickHouse: clickhouse-client.
다음 명령을 실행합니다:

   GRANT dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app;

CLUSTER_NAME_HERE를 클러스터 이름으로 교체합니다:

GRANT dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;

권한이 없으면 ClickHouse 마이그레이션(CreateNamespaceTraversalPathsDict)이 다음 오류와 함께 실패합니다:

DB::Exception: gitlab: Not enough privileges.

권한을 부여한 후 마이그레이션을 안전하게 재시도할 수 있습니다(분산 마이그레이션 잠금이 해제될 때까지 1-2시간 기다리는 것이 좋습니다).

ClickHouse CI 잡 데이터 구체화 뷰 데이터 불일치#

GitLab 18.5 이하에서 Sidekiq 작업자가 네트워크 타임아웃 후 재시도할 때 ClickHouse 테이블(ci_finished_pipelines 및 ci_finished_builds 등)에 중복 데이터가 삽입될 수 있었습니다. 이 문제로 인해 구체화 뷰가 러너 플릿 대시보드를 포함한 분석 대시보드에서 잘못된 집계 메트릭을 표시했습니다.

이 문제는 GitLab 18.9에서 수정되었으며 18.6, 18.7, 18.8로 백포팅되었습니다. 이 문제를 해결하려면 GitLab 18.6 이상으로 업그레이드하세요.

기존 중복 데이터가 있는 경우 영향받은 구체화 뷰를 재구성하는 수정이 이슈 586319의 GitLab 18.10에서 계획되어 있습니다. 지원을 받으려면 GitLab 지원팀에 문의하세요.

ClickHouse

GitLab v19.1

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-06-19

요약

히스토리

GitLab 18.11에서 GitLab Self-Managed에 대해 일반 공개됨.

ClickHouse는 오픈 소스 열 지향 데이터베이스 관리 시스템입니다. 대규모 데이터 세트에서 효율적으로 필터링, 집계 및 쿼리를 수행할 수 있습니다.

ClickHouse를 GitLab에 연결하려면 ClickHouse Cloud를 사용해야 합니다.

또는 자체 ClickHouse를 가져올 수도 있습니다. 자세한 내용은 GitLab Self-Managed를 위한 ClickHouse 권장 사항을 참조하세요.

ClickHouse로 사용 가능한 분석#

ClickHouse를 구성한 후 다음 분석 기능을 사용할 수 있습니다:

기능	설명
러너 플릿 대시보드	러너 사용량 메트릭과 잡 대기 시간을 표시합니다. 러너 유형과 잡 상태별 잡 수 및 실행된 러너 분을 포함하는 CSV 파일 내보내기를 제공합니다.
기여 분석	시간 경과에 따른 그룹 구성원 기여(푸시 이벤트, 이슈, 머지 리퀘스트)의 분석을 제공합니다. ClickHouse는 대규모 인스턴스의 타임아웃 문제 가능성을 줄입니다.
GitLab Duo 및 SDLC 트렌드	GitLab Duo가 소프트웨어 개발 성능에 미치는 영향을 측정합니다. AI 관련 지표(GitLab Duo 시트 도입, 코드 제안 승인률, GitLab Duo Chat 사용)와 함께 개발 메트릭(배포 빈도, 리드 타임, 변경 실패율, 복구 시간)을 추적합니다.
AI 메트릭용 GraphQL API	AiMetrics, AiUserMetrics, AiUsageData 엔드포인트를 통해 GitLab Duo 및 SDLC 트렌드 데이터에 프로그래밍 방식으로 액세스를 제공합니다. BI 도구 및 사용자 정의 분석을 위한 사전 집계된 메트릭과 원시 이벤트 데이터 내보내기를 제공합니다.

지원되는 ClickHouse 버전#

지원되는 ClickHouse 버전은 GitLab 버전에 따라 다릅니다:

GitLab 17.7 이상은 ClickHouse 23.x를 지원합니다. ClickHouse 24.x 또는 25.x를 사용하려면 해결 방법을 사용하세요.
GitLab 18.1 이상은 ClickHouse 23.x, 24.x, 25.x를 지원합니다.
GitLab 18.8 이상은 ClickHouse 23.x, 24.x, 25.x 및 Replicated 데이터베이스 엔진을 지원합니다.

이전 클러스터는 추가 권한(dictGet)이 필요합니다. 스니펫을 참조하세요.

GitLab 19.0 이상은 ClickHouse 25.x 및 26.x를 지원합니다. ClickHouse 23.x 및 24.x 지원이 제거되었습니다.

ClickHouse Cloud는 항상 최신 안정 GitLab 릴리스와 호환됩니다.

Note

ClickHouse 설정#

운영 요구 사항에 따라 배포 유형을 선택하세요:

ClickHouse Cloud (권장): 자동 업그레이드, 백업, 스케일링이 포함된 완전 관리형 서비스.
GitLab Self-Managed용 ClickHouse (BYOC): 인프라와 구성에 대한 완전한 제어.

ClickHouse 인스턴스를 설정한 후:

ClickHouse Cloud 설정#

사전 요구 사항:

ClickHouse Cloud 계정이 있어야 합니다.
GitLab 인스턴스에서 ClickHouse Cloud로의 네트워크 연결을 활성화합니다.
GitLab 인스턴스의 관리자여야 합니다.

ClickHouse Cloud를 설정하려면:

ClickHouse Cloud에 로그인합니다.
New Service를 선택합니다.
서비스 티어를 선택합니다:

Development: 테스트 및 개발 환경용.
- Production: 고가용성 프로덕션 워크로드용.
클라우드 공급자와 리전을 선택합니다. 최적의 성능을 위해 GitLab 인스턴스와 가까운 리전을 선택합니다.
서비스 이름과 설정을 구성합니다.
Create Service를 선택합니다.
프로비저닝이 완료되면 서비스 대시보드에서 연결 세부 정보를 확인합니다:
- 호스트
- 포트 (8443 - GitLab이 사용하는 HTTPS 연결, 또는 clickhouse-client가 사용하는 TLS 포함 네이티브 TCP의 경우 9440)
- 사용자 이름
- 비밀번호

Note

ClickHouse Cloud 서비스를 생성한 후 GitLab 데이터베이스 및 사용자를 생성합니다.

GitLab Self-Managed용 ClickHouse 설정 (BYOC)#

사전 요구 사항:

ClickHouse 인스턴스가 설치되어 실행 중이어야 합니다. ClickHouse가 설치되어 있지 않은 경우 다음을 참조하세요:
- ClickHouse 공식 설치 가이드.
- GitLab Self-Managed를 위한 ClickHouse 권장 사항.
지원되는 ClickHouse 버전이 있어야 합니다.
GitLab 인스턴스에서 ClickHouse로의 네트워크 연결을 활성화합니다.
ClickHouse와 GitLab 인스턴스 모두의 관리자여야 합니다.

Note

고가용성 구성#

다중 노드 고가용성(HA) 설정의 경우 GitLab은 ClickHouse의 Replicated 테이블 엔진을 지원합니다.

사전 요구 사항:

여러 노드가 있는 ClickHouse 클러스터. 최소 3개의 노드를 권장합니다.
remote_servers 구성 섹션에서 클러스터를 정의합니다.
ClickHouse 구성에서 다음 매크로를 구성합니다:
- cluster
- shard
- replica

HA를 위한 데이터베이스를 구성할 때는 ON CLUSTER 절과 함께 문을 실행해야 합니다.

자세한 내용은 ClickHouse Replicated 데이터베이스 엔진 문서를 참조하세요.

로드 밸런서 구성#

권장 로드 밸런서 옵션:

chproxy - 내장 캐싱 및 라우팅이 있는 ClickHouse 전용 HTTP 프록시.
HAProxy - 범용 TCP/HTTP 로드 밸런서.
NGINX - 로드 밸런싱 기능이 있는 웹 서버.
클라우드 공급자 로드 밸런서 (AWS Application Load Balancer, GCP Load Balancer, Azure Load Balancer).

기본 chproxy 구성 예시:

server:
  http:
    listen_addr: ":8080"

clusters:
  - name: "clickhouse_cluster"
    nodes: [
      "http://ch-node1:8123",
      "http://ch-node2:8123",
      "http://ch-node3:8123"
    ]

users:
  - name: "gitlab"
    password: "your_secure_password"
    to_cluster: "clickhouse_cluster"
    to_user: "gitlab"

로드 밸런서를 사용하는 경우 개별 ClickHouse 노드 대신 로드 밸런서 URL에 연결하도록 GitLab을 구성합니다.

자세한 내용은 chproxy 문서를 참조하세요.

GitLab Self-Managed용 ClickHouse 인스턴스를 구성한 후 GitLab 데이터베이스 및 사용자를 생성합니다.

ClickHouse 설치 확인#

데이터베이스를 구성하기 전에 ClickHouse가 설치되어 액세스 가능한지 확인합니다:

ClickHouse가 실행 중인지 확인합니다:
```
clickhouse-client --query "SELECT version()"
```
ClickHouse가 실행 중이면 버전 번호(예: 24.3.1.12)가 표시됩니다.
자격 증명으로 연결할 수 있는지 확인합니다:
```
clickhouse-client --host your-clickhouse-host --port 9440 --secure --user default --password 'your-password'
```
[!note] TLS를 아직 구성하지 않은 경우 초기 테스트를 위해 --secure 플래그 없이 포트 9000을 사용하세요.

데이터베이스 및 사용자 생성#

필요한 사용자와 데이터베이스 객체를 생성하려면:

안전한 비밀번호를 생성하고 저장합니다.
다음에 로그인합니다:
- ClickHouse Cloud: ClickHouse SQL 콘솔.
- GitLab Self-Managed용 ClickHouse: clickhouse-client.
다음 명령을 실행하고 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, dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app;
   GRANT SELECT ON information_schema.* TO gitlab_app;
   GRANT gitlab_app TO gitlab;

CLUSTER_NAME_HERE를 클러스터 이름으로 교체합니다:

CREATE DATABASE gitlab_clickhouse_main_production ON CLUSTER CLUSTER_NAME_HERE ENGINE = Replicated('/clickhouse/databases/{cluster}/gitlab_clickhouse_main_production', '{shard}', '{replica}');
CREATE USER gitlab IDENTIFIED WITH sha256_password BY 'PASSWORD_HERE' ON CLUSTER CLUSTER_NAME_HERE;
CREATE ROLE gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT SELECT, INSERT, ALTER, CREATE, UPDATE, DROP, TRUNCATE, OPTIMIZE, dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT SELECT ON information_schema.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT gitlab_app TO gitlab ON CLUSTER CLUSTER_NAME_HERE;

GitLab 연결 구성#

GitLab에 ClickHouse 자격 증명을 제공하려면:

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['clickhouse_databases']['main']['database'] = 'gitlab_clickhouse_main_production'
gitlab_rails['clickhouse_databases']['main']['url'] = 'https://your-clickhouse-host:port'
gitlab_rails['clickhouse_databases']['main']['username'] = 'gitlab'
gitlab_rails['clickhouse_databases']['main']['password'] = 'PASSWORD_HERE' # 실제 비밀번호로 교체

URL을 다음으로 교체합니다:

ClickHouse Cloud: https://your-service.clickhouse.cloud:8443
GitLab Self-Managed용 ClickHouse: https://your-clickhouse-host:8443
로드 밸런서가 있는 GitLab Self-Managed HA용 ClickHouse: https://your-load-balancer:8080 (또는 로드 밸런서 URL)

파일을 저장하고 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: gitlab
      password:
        secret: gitlab-clickhouse-password
        key: main_password
      database: gitlab_clickhouse_main_production
      url: 'https://your-clickhouse-host:port'

URL을 다음으로 교체합니다:

ClickHouse Cloud: https://your-service.clickhouse.cloud:8443
GitLab Self-Managed 단일 노드: https://your-clickhouse-host:8443
로드 밸런서가 있는 GitLab Self-Managed HA: https://your-load-balancer:8080 (또는 로드 밸런서 URL)

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Note

연결 확인#

연결이 성공적으로 설정되었는지 확인하려면:

Rails 콘솔에 로그인합니다.
다음 명령을 실행합니다:
```
ClickHouse::Client.select('SELECT 1', :main)
```
성공하면 명령이 [{"1"=>1}]을 반환합니다.

연결이 실패하면 다음을 확인합니다:
- ClickHouse 서비스가 실행 중이고 액세스 가능한지.
- GitLab에서 ClickHouse로의 네트워크 연결. 방화벽과 보안 그룹이 연결을 허용하는지 확인합니다.
- 연결 URL이 올바른지 (호스트, 포트, 프로토콜).
- 자격 증명이 올바른지.
- HA 클러스터 배포의 경우: 로드 밸런서가 올바르게 구성되어 요청을 라우팅하는지.

ClickHouse 마이그레이션 실행#

Warning

이 단계는 필수입니다. 건너뛰면 Analytics 대시보드에 데이터가 표시되지 않고 "Failed to fetch data" 오류가 표시됩니다.

필요한 데이터베이스 객체를 생성하려면 다음을 실행합니다:

sudo gitlab-rake gitlab:clickhouse:migrate

마이그레이션은 GitLab-Migrations 차트와 함께 자동으로 실행됩니다.

또는 Toolbox 파드에서 다음 명령을 실행하여 마이그레이션을 실행할 수 있습니다:

gitlab-rake gitlab:clickhouse:migrate

분석을 위한 ClickHouse 활성화#

GitLab 인스턴스가 ClickHouse에 연결된 후 ClickHouse를 사용하는 기능을 활성화할 수 있습니다:

사전 요구 사항:

인스턴스에 대한 관리자 액세스가 있어야 합니다.
ClickHouse 연결이 구성되고 확인되었어야 합니다.
마이그레이션이 성공적으로 완료되었어야 합니다.

분석을 위한 ClickHouse를 활성화하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
Enable ClickHouse for Analytics를 선택합니다.
Save changes를 선택합니다.

분석을 위한 ClickHouse 비활성화#

분석을 위한 ClickHouse를 비활성화하려면:

사전 요구 사항:

인스턴스에 대한 관리자 액세스가 있어야 합니다.

비활성화하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
Enable ClickHouse for Analytics 체크박스를 해제합니다.
Save changes를 선택합니다.

Note

ClickHouse 업그레이드#

ClickHouse Cloud#

ClickHouse Cloud는 버전 업그레이드와 보안 패치를 자동으로 처리합니다. 수동 개입이 필요하지 않습니다.

업그레이드 일정 및 유지 관리 창에 대한 정보는 ClickHouse Cloud 업그레이드를 참조하세요.

Note

GitLab Self-Managed용 ClickHouse (BYOC)#

GitLab Self-Managed용 ClickHouse의 경우 버전 업그레이드 계획 및 실행에 대한 책임이 있습니다.

사전 요구 사항:

ClickHouse 인스턴스에 대한 관리자 액세스가 있어야 합니다.
업그레이드 전에 데이터를 백업합니다. 재해 복구를 참조하세요.

업그레이드 전:

호환성이 손상된 변경 사항에 대한 ClickHouse 릴리스 노트를 검토합니다.
GitLab 버전과의 호환성을 확인합니다.
비프로덕션 환경에서 업그레이드를 테스트합니다.
잠재적인 다운타임을 계획하거나 HA 클러스터의 경우 롤링 업그레이드 전략을 사용합니다.

ClickHouse를 업그레이드하려면:

단일 노드 배포의 경우 ClickHouse 업그레이드 문서를 따릅니다.
HA 클러스터 배포의 경우 다운타임을 최소화하기 위해 롤링 업그레이드를 수행합니다:
1. 한 번에 하나씩 노드를 업그레이드합니다.
2. 노드가 클러스터에 재참여할 때까지 기다립니다.
3. 다음 노드로 진행하기 전에 클러스터 상태를 확인합니다.

Warning

자세한 업그레이드 절차는 ClickHouse 업데이트 문서를 참조하세요.

운영#

마이그레이션 상태 확인#

사전 요구 사항:

인스턴스에 대한 관리자 액세스가 있어야 합니다.

ClickHouse 마이그레이션 상태를 확인하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
사용 가능한 경우 Migration status 섹션을 검토합니다.

또는 Rails 콘솔을 사용하여 보류 중인 마이그레이션을 확인합니다:

# Rails 콘솔에 로그인
# 마이그레이션을 확인하기 위해 실행
ClickHouse::MigrationSupport::Migrator.new(:main).pending_migrations

실패한 마이그레이션 재시도#

ClickHouse 마이그레이션이 실패하면:

오류 세부 정보에 대한 로그를 확인합니다. ClickHouse 관련 오류는 GitLab 애플리케이션 로그에 기록됩니다.
기본 문제를 해결합니다(예: 메모리 부족, 연결 문제).

마이그레이션을 재시도합니다:

# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:clickhouse:migrate

# 자체 컴파일 설치의 경우
bundle exec rake gitlab:clickhouse:migrate RAILS_ENV=production

Note

ClickHouse Rake 태스크#

GitLab은 ClickHouse 데이터베이스를 관리하기 위한 여러 Rake 태스크를 제공합니다.

사용 가능한 Rake 태스크:

태스크	설명
`sudo gitlab-rake gitlab:clickhouse:migrate`	데이터베이스 스키마를 생성하거나 업데이트하기 위해 모든 보류 중인 ClickHouse 마이그레이션을 실행합니다.
`sudo gitlab-rake gitlab:clickhouse:drop`	모든 ClickHouse 데이터베이스를 삭제합니다. 모든 데이터가 삭제되므로 극도로 주의해서 사용하세요.
`sudo gitlab-rake gitlab:clickhouse:create`	ClickHouse 데이터베이스가 없는 경우 생성합니다.
`sudo gitlab-rake gitlab:clickhouse:setup`	데이터베이스를 생성하고 모든 마이그레이션을 실행합니다. create와 migrate 태스크를 실행하는 것과 동일합니다.
`sudo gitlab-rake gitlab:clickhouse:schema:dump`	백업 또는 버전 제어를 위해 현재 데이터베이스 스키마를 파일로 덤프합니다.
`sudo gitlab-rake gitlab:clickhouse:schema:load`	덤프 파일에서 데이터베이스 스키마를 로드합니다.

Note

자체 컴파일 설치의 경우 sudo gitlab-rake 대신 bundle exec rake를 사용하고 명령 끝에 RAILS_ENV=production을 추가합니다.

일반적인 태스크 예시#

ClickHouse 연결 및 스키마 확인#

ClickHouse 연결이 작동하는지 확인하려면:

# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:clickhouse:info

# 자체 컴파일 설치의 경우
bundle exec rake gitlab:clickhouse:info RAILS_ENV=production

이 태스크는 ClickHouse 연결 및 구성에 대한 디버깅 정보를 출력합니다.

모든 마이그레이션 재실행#

보류 중인 모든 마이그레이션을 실행하려면:

# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:clickhouse:migrate

# 자체 컴파일 설치의 경우
bundle exec rake gitlab:clickhouse:migrate RAILS_ENV=production

데이터베이스 초기화#

Warning

이 작업은 ClickHouse 데이터베이스의 모든 데이터를 삭제합니다. 개발 환경이나 문제 해결 시에만 사용하세요.

데이터베이스를 삭제하고 재생성하려면:

# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:clickhouse:drop
sudo gitlab-rake gitlab:clickhouse:setup

# 자체 컴파일 설치의 경우
bundle exec rake gitlab:clickhouse:drop RAILS_ENV=production
bundle exec rake gitlab:clickhouse:setup RAILS_ENV=production

환경 변수#

Rake 태스크 동작을 제어하기 위해 환경 변수를 사용할 수 있습니다:

환경 변수	데이터 유형	설명
`VERBOSE`	Boolean	마이그레이션 중 자세한 출력을 보려면 `true`로 설정합니다. 예: `VERBOSE=true sudo gitlab-rake gitlab:clickhouse:migrate`

성능 조정#

Note

사용자 수에 따른 리소스 크기 조정 및 배포 권장 사항은 시스템 요구 사항을 참조하세요.

ClickHouse 아키텍처 및 성능 조정에 대한 정보는 ClickHouse 아키텍처 문서를 참조하세요.

재해 복구#

백업 및 복원#

GitLab 애플리케이션을 업그레이드하기 전에 전체 백업을 수행해야 합니다. ClickHouse 데이터는 GitLab 백업 도구에 포함되지 않습니다.

백업 및 복원 전략은 배포 선택에 따라 다릅니다.

ClickHouse Cloud#

ClickHouse Cloud는 자동으로:

백업 및 복원을 관리합니다.
매일 백업을 생성하고 보존합니다.

추가 구성이 필요하지 않습니다.

자세한 내용은 ClickHouse Cloud 백업을 참조하세요.

GitLab Self-Managed용 ClickHouse#

자체 ClickHouse 인스턴스를 관리하는 경우 데이터 안전을 위해 정기적으로 백업을 수행해야 합니다:

시스템 테이블(metrics 또는 logs 등 제외)의 초기 전체 백업을 오브젝트 스토리지 버킷(예: AWS S3)으로 가져옵니다.
이 초기 전체 백업 후 증분 백업을 수행합니다.

이 방식은 모든 전체 백업에 대한 데이터를 복제하지만 데이터를 복원하는 가장 쉬운 방법입니다.

또는 clickhouse-backup을 사용합니다. 이는 예약 및 원격 스토리지 관리와 같은 추가 기능이 있는 서드파티 도구입니다.

모니터링#

GitLab 통합의 안정성을 보장하기 위해 ClickHouse 클러스터의 상태와 성능을 모니터링해야 합니다.

ClickHouse Cloud#

ClickHouse Cloud는 보안 API 엔드포인트를 통해 메트릭을 노출하는 기본 Prometheus 통합을 제공합니다.

API 자격 증명을 생성한 후 ClickHouse Cloud에서 메트릭을 스크레이핑하도록 수집기를 구성할 수 있습니다. 예를 들어 Prometheus 배포.

GitLab Self-Managed용 ClickHouse#

ClickHouse는 Prometheus 형식의 메트릭을 노출할 수 있습니다. 이를 활성화하려면:

config.xml의 prometheus 섹션을 구성하여 전용 포트(기본값 9363)에서 메트릭을 노출합니다:

<prometheus>
    <endpoint>/metrics</endpoint>
    <port>9363</port>
    <metrics>true</metrics>
    <events>true</events>
    <asynchronous_metrics>true</asynchronous_metrics>
</prometheus>

http://<clickhouse-host>:9363/metrics에서 스크레이핑하도록 Prometheus 또는 호환 서버를 구성합니다.

모니터링할 메트릭#

GitLab 기능에 영향을 줄 수 있는 문제를 감지하기 위해 다음 메트릭에 대한 알림을 설정해야 합니다:

메트릭 이름	설명	알림 임계값 (권장)
`ClickHouse_Metrics_Query`	현재 실행 중인 쿼리 수. 갑작스러운 급증은 성능 병목을 나타낼 수 있습니다.	기준 편차 (예: > 100)
`ClickHouseProfileEvents_FailedSelectQuery`	실패한 선택 쿼리 수	기준 편차 (예: > 50)
`ClickHouseProfileEvents_FailedInsertQuery`	실패한 삽입 쿼리 수	기준 편차 (예: > 10)
`ClickHouse_AsyncMetrics_ReadonlyReplica`	복제본이 읽기 전용 모드로 전환되었는지 나타냅니다(종종 ZooKeeper 연결 손실로 인해).	> 0 (즉각 조치 필요)
`ClickHouse_ProfileEvents_NetworkErrors`	네트워크 오류 (연결 재설정/타임아웃). 빈번한 오류는 GitLab 백그라운드 잡 실패를 유발할 수 있습니다.	Rate > 0

활성 상태 확인#

ClickHouse가 로드 밸런서 뒤에 있는 경우 HTTP /ping 엔드포인트를 사용하여 활성 상태를 확인할 수 있습니다. 예상 응답은 HTTP 코드 200과 함께 Ok입니다.

보안 및 감사#

데이터 보안을 보장하고 감사 가능성을 확보하려면 다음 보안 관행을 사용합니다.

네트워크 보안#

TLS 암호화: ClickHouse 서버가 연결을 검증하기 위해 TLS 암호화를 사용하도록 구성합니다.

GitLab에서 연결 URL을 구성할 때 https:// 프로토콜(예: https://clickhouse.example.com:8443)을 사용해야 합니다.
IP 허용 목록: ClickHouse 포트(기본값 8443 또는 9440)에 대한 액세스를 GitLab 애플리케이션 노드 및 기타 인가된 네트워크로만 제한합니다.

감사 로깅#

ClickHouse Cloud#

ClickHouse Cloud에서는 쿼리 로깅이 기본적으로 활성화되어 있습니다. system.query_log 테이블을 쿼리하여 이 로그에 액세스할 수 있습니다.

GitLab Self-Managed용 ClickHouse#

자체 관리 인스턴스의 경우 서버 구성에서 query_log 구성 파라미터가 활성화되어 있는지 확인합니다:

config.xml 또는 users.xml에 query_log 섹션이 있는지 확인합니다:

<query_log>
    <database>system</database>
    <table>query_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <ttl>event_date + INTERVAL 30 DAY</ttl>  <!-- 30일만 유지 -->
</query_log>

활성화되면 실행된 모든 쿼리가 system.query_log 테이블에 기록되어 감사 추적이 가능합니다.

시스템 요구 사항#

권장 시스템 요구 사항은 사용자 수에 따라 다릅니다.

배포 결정 매트릭스 빠른 참조#

사용자	기본 권장 사항	비교 가능한 AWS ARM 인스턴스	비교 가능한 GCP ARM 인스턴스	비교 가능한 Azure ARM 인스턴스	배포 유형
1K	ClickHouse Cloud Basic	-	-	-	관리형
2K	ClickHouse Cloud Basic	m8g.xlarge	c4a-standard-4	Standard_D4ps_v6	관리형 또는 단일 노드
3K	ClickHouse Cloud Scale	m8g.2xlarge	c4a-standard-8	Standard_D8ps_v6	관리형 또는 단일 노드
5K	ClickHouse Cloud Scale	m8g.4xlarge	c4a-standard-16	Standard_D16ps_v6	관리형 또는 단일 노드
10K	ClickHouse Cloud Scale	m8g.4xlarge	c4a-standard-16	Standard_D16ps_v6	관리형 또는 단일 노드/HA
25K	GitLab Self-Managed용 ClickHouse 또는 ClickHouse Cloud Scale	m8g.8xlarge 또는 3×m8g.4xlarge	c4a-standard-32 또는 3×c4a-standard-16	Standard_D32ps_v6 또는 3×Standard_D16ps_v6	관리형 또는 단일 노드/HA
50K	GitLab Self-Managed용 ClickHouse HA 또는 ClickHouse Cloud Scale	3×m8g.4xlarge	3×c4a-standard-16	3×Standard_D16ps_v6	관리형 또는 HA 클러스터

1K 사용자#

권장 사항: ClickHouse Cloud Basic - 운영 복잡성 없이 좋은 비용 효율성을 제공합니다.

2K 사용자#

권장 사항: ClickHouse Cloud Basic - 운영 복잡성 없이 최고의 가치를 제공합니다.

GitLab Self-Managed 배포를 위한 대안 권장 사항:

AWS: m8g.xlarge (4 vCPU, 16 GB)
GCP: c4a-standard-4 또는 n4-standard-4 (4 vCPU, 16 GB)
Azure: Standard_D4ps_v6 (4 vCPU, 16 GB)
스토리지: 낮음-중간 성능 티어의 20 GB

3K 사용자#

권장 사항: ClickHouse Cloud Scale

GitLab Self-Managed 배포를 위한 대안 권장 사항:

AWS: m8g.2xlarge (8 vCPU, 32 GB)
GCP: c4a-standard-8 또는 n4-standard-8 (8 vCPU, 32 GB)
Azure: Standard_D8ps_v6 (8 vCPU, 32 GB)
스토리지: 중간 성능 티어의 100 GB

Note

이 규모에서는 HA 배포가 비용 효율적이지 않습니다.

5K 사용자#

권장 사항: ClickHouse Cloud Scale

GitLab Self-Managed 배포를 위한 대안 권장 사항:

AWS: m8g.4xlarge (16 vCPU, 64 GB)
GCP: c4a-standard-16 또는 n4-standard-16 (16 vCPU, 64 GB)
Azure: Standard_D16ps_v6 (16 vCPU, 64 GB)
스토리지: 높은 성능 티어의 100 GB
배포: 단일 노드 권장

10K 사용자#

권장 사항: ClickHouse Cloud Scale

GitLab Self-Managed 배포를 위한 대안 권장 사항:

AWS: m8g.4xlarge (16 vCPU, 64 GB)
GCP: c4a-standard-16 또는 n4-standard-16 (16 vCPU, 64 GB)
Azure: Standard_D16ps_v6 (16 vCPU, 64 GB)
스토리지: 높은 성능 티어의 200 GB
HA 옵션: 중요 워크로드의 경우 3노드 클러스터 가능

25K 사용자#

권장 사항: ClickHouse Cloud Scale 또는 GitLab Self-Managed용 ClickHouse. 이 규모에서는 두 옵션 모두 경제적으로 실행 가능합니다.

GitLab Self-Managed 배포를 위한 권장 사항:

단일 노드:
- AWS: m8g.8xlarge (32 vCPU, 128 GB)
- GCP: c4a-standard-32 또는 n4-standard-32 (32 vCPU, 128 GB)
- Azure: Standard_D32ps_v6 (32 vCPU, 128 GB)
HA 배포:
- AWS: 3 × m8g.4xlarge (16 vCPU, 64 GB 각)
- GCP: 3 × c4a-standard-16 또는 3 × n4-standard-16 (16 vCPU, 64 GB 각)
- Azure: 3 × Standard_D16ps_v6 (16 vCPU, 64 GB 각)
스토리지: 높은 성능 티어의 노드당 400 GB.

50K 사용자#

권장 사항: GitLab Self-Managed용 ClickHouse HA 또는 ClickHouse Cloud Scale. 이 규모에서는 자체 관리 옵션이 약간 더 비용 효율적입니다.

GitLab Self-Managed 배포를 위한 권장 사항:

단일 노드:
- AWS: m8g.8xlarge (32 vCPU, 128 GB)
- GCP: c4a-standard-32 또는 n4-standard-32 (32 vCPU, 128 GB)
- Azure: Standard_D32ps_v6 (32 vCPU, 128 GB)
HA 배포 (권장):
- AWS: 3 × m8g.4xlarge (16 vCPU, 64 GB 각)
- GCP: 3 × c4a-standard-16 또는 3 × n4-standard-16 (16 vCPU, 64 GB 각)
- Azure: 3 × Standard_D16ps_v6 (16 vCPU, 64 GB 각)
스토리지: 높은 성능 티어의 노드당 1000 GB.

GitLab Self-Managed 배포용 HA 고려 사항#

HA 설정은 10k 사용자 이상에서만 비용 효율적입니다.

최소: 쿼럼을 위한 세 개의 ClickHouse 노드.
ClickHouse Keeper: 코디네이션을 위한 세 개의 노드 (공동 배치 또는 별도).
로드 밸런서: 쿼리 분산을 위해 권장.
네트워크: 노드 간 저지연 연결이 중요합니다.

용어집#

클러스터: 데이터를 저장하고 처리하기 위해 함께 작동하는 노드(서버) 모음.
MergeTree: MergeTree는 높은 데이터 수집률과 대규모 데이터 볼륨을 위해 설계된 ClickHouse의 테이블 엔진입니다. 열 지향 스토리지, 사용자 정의 파티셔닝, 스파스 기본 인덱스, 백그라운드 데이터 병합 지원 등의 기능을 제공하는 ClickHouse의 핵심 스토리지 엔진입니다.
파츠(Parts): 테이블 데이터의 일부를 저장하는 디스크의 물리적 파일. 파츠는 파티션 키를 사용하여 생성된 테이블 데이터의 논리적 분할인 파티션과 다릅니다.
복제본(Replica): ClickHouse 데이터베이스에 저장된 데이터의 복사본. 중복성 및 신뢰성을 위해 동일한 데이터의 복제본을 여러 개 가질 수 있습니다. 복제본은 ReplicatedMergeTree 테이블 엔진과 함께 사용되어 ClickHouse가 다른 서버 간에 여러 데이터 사본을 동기화된 상태로 유지할 수 있도록 합니다.
샤드(Shard): 데이터의 하위 집합. ClickHouse는 항상 데이터에 대해 최소 하나의 샤드를 갖습니다. 여러 서버에 데이터를 분할하지 않으면 데이터는 하나의 샤드에 저장됩니다. 단일 서버의 용량을 초과하는 경우 여러 서버에 데이터를 샤딩하여 부하를 분산할 수 있습니다.
TTL (Time To Live): TTL(Time To Live)은 특정 기간 후에 열/행을 자동으로 이동, 삭제 또는 롤업하는 ClickHouse 기능입니다. 더 이상 자주 액세스할 필요가 없는 데이터를 삭제, 이동 또는 보관할 수 있으므로 스토리지를 더 효율적으로 관리할 수 있습니다.

문제 해결#

GitLab 18.0.0 이하에서 데이터베이스 스키마 마이그레이션#

Warning

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 통합이 작동하지 않습니다.

이 문제를 해결하고 마이그레이션을 실행하려면:

Rails 콘솔에 로그인합니다.

다음 명령을 실행합니다:

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

데이터베이스를 다시 마이그레이션합니다:
```
sudo gitlab-rake gitlab:clickhouse:migrate
```

이번에는 데이터베이스 마이그레이션이 성공적으로 완료됩니다.

데이터베이스 딕셔너리 읽기 지원#

다음에 로그인합니다:
- ClickHouse Cloud: ClickHouse SQL 콘솔.
- GitLab Self-Managed용 ClickHouse: clickhouse-client.
다음 명령을 실행합니다:

   GRANT dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app;

CLUSTER_NAME_HERE를 클러스터 이름으로 교체합니다:

GRANT dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;

권한이 없으면 ClickHouse 마이그레이션(CreateNamespaceTraversalPathsDict)이 다음 오류와 함께 실패합니다:

DB::Exception: gitlab: Not enough privileges.

권한을 부여한 후 마이그레이션을 안전하게 재시도할 수 있습니다(분산 마이그레이션 잠금이 해제될 때까지 1-2시간 기다리는 것이 좋습니다).

ClickHouse CI 잡 데이터 구체화 뷰 데이터 불일치#

이 문제는 GitLab 18.9에서 수정되었으며 18.6, 18.7, 18.8로 백포팅되었습니다. 이 문제를 해결하려면 GitLab 18.6 이상으로 업그레이드하세요.