GitLab은 일반 유지 관리를 위한 Rake 작업을 제공합니다.

GitLab 및 시스템 정보 수집#

이 명령은 GitLab 설치 환경과 그것이 실행되는 시스템에 대한 정보를 수집합니다. 도움을 요청하거나 이슈를 보고할 때 유용할 수 있습니다. 멀티 노드 환경에서는 PostgreSQL 소켓 오류를 방지하기 위해 GitLab Rails를 실행하는 노드에서 이 명령을 실행합니다.

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:env:info
  

• 자체 컴파일 설치:

  bundle exec rake gitlab:env:info RAILS_ENV=production
  

출력 예시:

System information
System:         Ubuntu 20.04
Proxy:          no
Current User:   git
Using RVM:      no
Ruby Version:   2.7.6p219
Gem Version:    3.1.6
Bundler Version:2.3.15
Rake Version:   13.0.6
Redis Version:  6.2.7
Sidekiq Version:6.4.2
Go Version:     unknown

GitLab information
Version:        15.5.5-ee
Revision:       5f5109f142d
Directory:      /opt/gitlab/embedded/service/gitlab-rails
DB Adapter:     PostgreSQL
DB Version:     13.8
URL:            https://app.gitaly.gcp.gitlabsandbox.net
HTTP Clone URL: https://app.gitaly.gcp.gitlabsandbox.net/some-group/some-project.git
SSH Clone URL:  git@app.gitaly.gcp.gitlabsandbox.net:some-group/some-project.git
Elasticsearch:  no
Geo:            no
Using LDAP:     no
Using Omniauth: yes
Omniauth Providers:

GitLab Shell
Version:        14.12.0
Repository storage paths:
- default:      /var/opt/gitlab/git-data/repositories
- gitaly:       /var/opt/gitlab/git-data/repositories
GitLab Shell path:              /opt/gitlab/embedded/service/gitlab-shell

Gitaly
- default Address:      unix:/var/opt/gitlab/gitaly/gitaly.socket
- default Version:      15.5.5
- default Git Version:  2.37.1.gl1
- gitaly Address:       tcp://10.128.20.6:2305
- gitaly Version:       15.5.5
- gitaly Git Version:   2.37.1.gl1

GitLab 라이선스 정보 표시#

이 명령은 GitLab 라이선스 정보와 사용 중인 좌석 수를 표시합니다. GitLab Enterprise 설치에서만 사용할 수 있습니다. GitLab Community Edition에는 라이선스를 설치할 수 없습니다.

Support에 티켓을 등록할 때나 라이선스 파라미터를 프로그래밍 방식으로 확인할 때 유용할 수 있습니다.

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:license:info
  

• 자체 컴파일 설치:

  bundle exec rake gitlab:license:info RAILS_ENV=production
  

출력 예시:

Today's Date: 2020-02-29
Current User Count: 30
Max Historical Count: 30
Max Users in License: 40
License valid from: 2019-11-29 to 2020-11-28
Email associated with license: user@example.com

GitLab 구성 확인#

gitlab:check Rake 작업은 다음 Rake 작업을 실행합니다:

• gitlab:gitlab_shell:check
• gitlab:gitaly:check
• gitlab:sidekiq:check
• gitlab:incoming_email:check
• gitlab:ldap:check
• gitlab:app:check
• gitlab:geo:check(Geo를 실행하는 경우에만)

각 구성 요소가 설치 가이드에 따라 설정되었는지 확인하고 발견된 문제에 대한 해결 방법을 제안합니다. 이 명령은 애플리케이션 서버에서 실행해야 하며 Gitaly와 같은 구성 요소 서버에서는 올바르게 동작하지 않습니다.

다음에 대한 문제 해결 가이드도 참고할 수 있습니다:

• GitLab.
• Linux 패키지 설치.

추가로 현재 시크릿으로 데이터베이스 값을 복호화할 수 있는지 확인해야 합니다.

gitlab:check를 실행하려면 다음을 실행합니다:

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:check
  

• 자체 컴파일 설치:

  bundle exec rake gitlab:check RAILS_ENV=production
  

• Kubernetes 설치:

  kubectl exec -it <toolbox-pod-name> -- sudo gitlab-rake gitlab:check
  

  [!note] Helm 기반 GitLab 설치의 특수한 아키텍처 때문에 출력에 gitlab-shell, Sidekiq, systemd 관련 파일에 대한 연결 확인의 거짓 음성(false negative)이 포함될 수 있습니다. 보고된 이러한 실패는 예상된 것이며 실제 문제를 나타내지 않습니다. 진단 결과를 검토할 때 무시합니다.

출력에서 프로젝트 이름을 제외하려면 gitlab:check에 SANITIZE=true를 사용합니다.

출력 예시:

Checking Environment ...

Git configured for git user? ... yes
Has python2? ... yes
python2 is supported version? ... yes

Checking Environment ... Finished

Checking GitLab Shell ...

GitLab Shell version? ... OK (1.2.0)
Repo base directory exists? ... yes
Repo base directory is a symlink? ... no
Repo base owned by git:git? ... yes
Repo base access is drwxrws---? ... yes
post-receive hook up-to-date? ... yes
post-receive hooks in repos are links: ... yes

Checking GitLab Shell ... Finished

Checking Sidekiq ...

Running? ... yes

Checking Sidekiq ... Finished

Checking GitLab App...

Database config exists? ... yes
Database is SQLite ... no
All migrations up? ... yes
GitLab config exists? ... yes
GitLab config up to date? ... no
Cable config exists? ... yes
Resque config exists? ... yes
Log directory writable? ... yes
Tmp directory writable? ... yes
Init script exists? ... yes
Init script up-to-date? ... yes
Redis version >= 2.0.0? ... yes

Checking GitLab ... Finished

authorized_keys 파일 재빌드#

경우에 따라 authorized_keys 파일을 재빌드해야 합니다. 예를 들어 업그레이드 후 SSH를 통해 푸시할 때 Permission denied (publickey)가 표시되고 gitlab-shell.log 파일에서 404 Key Not Found 오류가 발견되는 경우입니다. authorized_keys를 재빌드하려면 다음을 실행합니다:

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:shell:setup
  

• 자체 컴파일 설치:

  cd /home/git/gitlab
  sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production
  

출력 예시:

This will rebuild an authorized_keys file.
You will lose any data stored in authorized_keys file.
Do you want to continue (yes/no)? yes

Redis 캐시 지우기#

어떤 이유로 대시보드에 잘못된 정보가 표시되면 Redis의 캐시를 지울 수 있습니다. 이렇게 하려면 다음을 실행합니다:

• Linux 패키지 설치:

  sudo gitlab-rake cache:clear
  

• 자체 컴파일 설치:

  cd /home/git/gitlab
  sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production
  

에셋 사전 컴파일#

버전 업그레이드 중에 CSS가 잘못 적용되거나 일부 아이콘이 누락되는 경우가 있습니다. 그런 경우에는 에셋을 다시 사전 컴파일합니다.

이 Rake 작업은 자체 컴파일 설치에만 적용됩니다. Linux 패키지를 실행할 때 이 문제를 해결하는 방법은 자세히 알아보기를 참고합니다. Linux 패키지에 대한 안내는 GitLab의 Kubernetes 및 Docker 배포에도 적용할 수 있습니다. 다만 일반적으로 컨테이너 기반 설치에서는 에셋 누락 문제가 발생하지 않습니다.

• 자체 컴파일 설치:

  cd /home/git/gitlab
  sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production
  

Linux 패키지 설치에서는 최적화되지 않은 에셋(JavaScript, CSS)이 업스트림 GitLab의 릴리스 시점에 고정됩니다. Linux 패키지 설치에는 이러한 에셋의 최적화된 버전이 포함됩니다. 패키지를 설치한 후 프로덕션 머신에서 JavaScript / CSS 코드를 수정하지 않는다면 프로덕션 머신에서 rake gitlab:assets:compile을 다시 실행할 이유는 없습니다. 에셋이 손상되었다고 의심되면 Linux 패키지를 다시 설치해야 합니다.

원격 사이트에 대한 TCP 연결 확인#

프록시 문제를 해결하기 위해 GitLab 설치 환경이 다른 머신의 TCP 서비스(예를 들어 PostgreSQL 또는 웹 서버)에 연결할 수 있는지 확인해야 하는 경우가 있습니다. 이를 돕는 Rake 작업이 포함되어 있습니다.

• Linux 패키지 설치:

  sudo gitlab-rake gitlab:tcp_check[example.com,80]
  

• 자체 컴파일 설치:

  cd /home/git/gitlab
  sudo -u git -H bundle exec rake gitlab:tcp_check[example.com,80] RAILS_ENV=production
  

배타적 리스 지우기 (위험)#

GitLab은 공유 리소스에서 동시 작업이 발생하지 않도록 공유 잠금 메커니즘인 ExclusiveLease를 사용합니다. 리포지터리에서 주기적인 가비지 컬렉션을 실행하는 것이 그 예입니다.

매우 특수한 상황에서는 Exclusive Lease로 잠긴 작업이 잠금을 해제하지 않은 채 실패할 수 있습니다. 만료를 기다릴 수 없다면 이 작업을 실행해 수동으로 지울 수 있습니다.

모든 배타적 리스를 지우려면 다음을 실행합니다:

sudo gitlab-rake gitlab:exclusive_lease:clear

리스 type 또는 리스 type + id를 지정하려면 스코프를 지정합니다:

# to clear all leases for repository garbage collection:
sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:*]

# to clear a lease for repository garbage collection in a specific project: (id=4)
sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:4]

데이터베이스 마이그레이션 상태 표시#

GitLab을 업그레이드할 때 마이그레이션이 완료되었는지 확인하는 방법은 백그라운드 마이그레이션 문서를 참고합니다.

특정 마이그레이션의 상태를 확인하려면 다음 Rake 작업을 사용할 수 있습니다:

sudo gitlab-rake db:migrate:status

Geo 보조 사이트의 추적 데이터베이스를 확인하려면 다음 Rake 작업을 사용할 수 있습니다:

sudo gitlab-rake db:migrate:status:geo

각 마이그레이션에 대해 up 또는 down의 Status가 포함된 표를 출력합니다. 예시:

database: gitlabhq_production

 Status   Migration ID    Type     Milestone    Name
--------------------------------------------------
   up     20240701074848  regular  17.2         AddGroupIdToPackagesDebianGroupComponents
   up     20240701153843  regular  17.2         AddWorkItemsDatesSourcesSyncToIssuesTrigger
   up     20240702072515  regular  17.2         AddGroupIdToPackagesDebianGroupArchitectures
   up     20240702133021  regular  17.2         AddWorkspaceTerminationTimeoutsToRemoteDevelopmentAgentConfigs
   up     20240604064938  post     17.2         FinalizeBackfillPartitionIdCiPipelineMessage
   up     20240604111157  post     17.2         AddApprovalPolicyRulesFkOnApprovalGroupRules

GitLab 17.1부터 마이그레이션은 GitLab 릴리스 주기에 맞는 순서로 실행됩니다.

불완전한 데이터베이스 마이그레이션 실행#

데이터베이스 마이그레이션은 불완전한 상태로 멈출 수 있으며, 이 경우 sudo gitlab-rake db:migrate:status 명령의 출력에 down 상태로 표시됩니다.

1. 이러한 마이그레이션을 완료하려면 다음 Rake 작업을 사용합니다:

   sudo gitlab-rake db:migrate
   

2. 명령이 완료되면 sudo gitlab-rake db:migrate:status를 실행해 모든 마이그레이션이 완료되었는지(up 상태인지) 확인합니다.

3. puma 및 sidekiq 서비스를 핫 리로드합니다:

   sudo gitlab-ctl hup puma
   sudo gitlab-ctl restart sidekiq
   

GitLab 17.1부터 마이그레이션은 GitLab 릴리스 주기에 맞는 순서로 실행됩니다.

데이터베이스 인덱스 재빌드#

히스토리

• GitLab 13.5에서 database_reindexing이라는 이름의 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 13.9에서 GitLab.com에 활성화되었습니다.
• GitLab 18.0에서 GitLab Self-Managed 및 GitLab Dedicated에 활성화되었습니다.

데이터베이스 인덱스를 정기적으로 재빌드하면 공간을 회수하고 시간이 지나도 인덱스 부풀림을 건전한 수준으로 유지할 수 있습니다. 재인덱싱은 정기 cron job으로도 실행할 수 있습니다. 「건전한」 부풀림 수준은 인덱스마다 크게 다르지만 일반적으로 30% 미만이어야 합니다.

데이터베이스 재인덱싱은 다음 작업을 수행합니다:

1. 수동으로 큐에 등록된 PostgreSQL 인덱스를 재인덱싱합니다. 인덱스는 재인덱싱을 위해 수동으로 큐에 추가할 수 있습니다. PostgreSQL 인덱스를 재인덱싱하면 일반적으로 인덱스 부풀림이 줄어듭니다.
2. 인덱스 부풀림 휴리스틱을 사용해 PostgreSQL 인덱스를 자동으로 재인덱싱합니다. PostgreSQL은 휴리스틱으로 가장 많이 부푼 인덱스를 식별합니다. 이 프로세스는 실행할 때마다 최대 2개의 인덱스를 선택해 재인덱싱합니다.

사전 요구 사항:

• 이 기능에는 PostgreSQL 12 이상이 필요합니다.
• 다음 인덱스 유형은 지원되지 않습니다. 표현식 인덱스와 제약 조건 제외에 사용되는 인덱스입니다.

재인덱싱 실행#

다음 작업은 각 데이터베이스에서 부풀림이 가장 큰 두 개의 인덱스만 재빌드합니다. 두 개보다 많은 인덱스를 재빌드하려면 원하는 인덱스가 모두 재빌드될 때까지 작업을 다시 실행합니다.

1. 재인덱싱 작업을 실행합니다:

   sudo gitlab-rake gitlab:db:reindex
   

2. 실행을 확인하거나 문제를 해결하려면 application_json.log를 확인합니다.

Toolbox 차트를 사용해 이 작업을 실행하는 GitLab 클라우드 네이티브 설치에서는 로그가 Pod의 표준 출력에 있습니다.

재인덱싱 설정 사용자 지정#

규모가 작은 인스턴스이거나 재인덱싱 동작을 조정하려면 Rails 콘솔을 사용해 다음 설정을 수정할 수 있습니다:

sudo gitlab-rails console

그런 다음 구성을 사용자 지정합니다:

# Lower minimum index size to 100 MB (default is 1 GB)
Gitlab::Database::Reindexing.minimum_index_size!(100.megabytes)

# Change minimum bloat threshold to 30% (default is 20%, there is no benefit from setting it lower)
Gitlab::Database::Reindexing.minimum_relative_bloat_size!(0.3)

자동화된 재인덱싱#

데이터베이스 크기가 상당히 큰 대규모 인스턴스에서는 활동이 적은 시간대에 실행되도록 예약해 데이터베이스 재인덱싱을 자동화합니다.

crontab으로 예약#

패키지로 설치한 GitLab에서는 crontab을 사용합니다:

1. crontab을 편집합니다:

   sudo crontab -e
   

2. 원하는 일정에 따라 항목을 추가합니다:

   1. 옵션 1: 한산한 시간대에 매일 실행

   # Run database reindexing every day at 21:12
   # The log will be rotated by the packaged logrotate daemon
   12 21 * * * /opt/gitlab/bin/gitlab-rake gitlab:db:reindex >> /var/log/gitlab/gitlab-rails/cron_reindex.log 2>&1
   

   1. 옵션 2: 주말에만 실행

   # Run database reindexing at 01:00 AM on weekends
   0 1 * * 0,6 /opt/gitlab/bin/gitlab-rake gitlab:db:reindex >> /var/log/gitlab/gitlab-rails/cron_reindex.log 2>&1
   

   1. 옵션 3: 트래픽이 적은 시간대에 자주 실행

   # Run database reindexing every 3 hours during night hours (22:00-07:00)
   0 22,1,4,7 * * * /opt/gitlab/bin/gitlab-rake gitlab:db:reindex >> /var/log/gitlab/gitlab-rails/cron_reindex.log 2>&1
   

Kubernetes 배포에서는 CronJob 리소스를 사용해 재인덱싱 작업을 실행하는 유사한 일정을 만들 수 있습니다.

참고 사항#

• 데이터베이스 인덱스 재빌드는 디스크 집약적인 작업이므로 사용량이 적은 시간대에 작업을 수행해야 합니다. 피크 시간대에 작업을 실행하면 부풀림이 늘어나고 특정 쿼리가 느리게 수행될 수 있습니다.
• 이 작업에는 복원 중인 인덱스를 위한 여유 디스크 공간이 필요합니다. 생성된 인덱스에는 _ccnew가 추가됩니다. 재인덱싱 작업이 실패하면 작업을 다시 실행할 때 임시 인덱스가 정리됩니다.
• 데이터베이스 인덱스 재빌드가 완료되는 데 걸리는 시간은 대상 데이터베이스의 크기에 따라 다릅니다. 몇 시간에서 며칠까지 걸릴 수 있습니다.
• 이 작업은 Redis 잠금을 사용하므로 자주 실행되도록 예약해도 안전합니다. 다른 재인덱싱 작업이 이미 실행 중이면 아무 작업도 수행하지 않습니다.

데이터베이스 스키마 덤프#

드물게 모든 데이터베이스 마이그레이션이 완료되었더라도 데이터베이스 스키마가 애플리케이션 코드가 기대하는 것과 다를 수 있습니다. 이런 경우 GitLab에서 이상한 오류가 발생할 수 있습니다.

데이터베이스 스키마를 덤프하려면 다음을 실행합니다:

SCHEMA=/tmp/structure.sql gitlab-rake db:schema:dump

이 Rake 작업은 데이터베이스 스키마 덤프가 포함된 /tmp/structure.sql 파일을 만듭니다.

차이가 있는지 확인하려면 다음을 수행합니다:

1. gitlab 프로젝트의 db/structure.sql 파일로 이동합니다. 사용 중인 GitLab 버전과 일치하는 브랜치를 선택합니다. 예를 들어 GitLab 19.2의 파일은 https://gitlab.com/gitlab-org/gitlab/-/blob/19-2-stable-ee/db/structure.sql입니다.
2. /tmp/structure.sql을 사용 중인 버전의 db/structure.sql 파일과 비교합니다.

스키마 불일치에 대한 데이터베이스 확인#

이 Rake 작업은 데이터베이스 스키마에 불일치가 있는지 확인하고 터미널에 출력합니다. 이 작업은 GitLab Support의 안내에 따라 사용하는 진단 도구입니다. 데이터베이스 불일치는 예상된 것일 수 있으므로 일상적인 점검에는 이 작업을 사용하지 않습니다.

gitlab-rake gitlab:db:schema_checker:run

데이터베이스에 대한 정보 및 통계 수집#

히스토리

• GitLab 17.11에서 도입되었습니다.

gitlab:db:sos 명령은 문제 해결에 도움이 되도록 GitLab 데이터베이스에 대한 구성, 성능, 진단 데이터를 수집합니다. 이 명령을 실행하는 위치는 구성에 따라 다릅니다. 이 명령은 GitLab이 설치된 위치 (/gitlab)를 기준으로 실행해야 합니다.

• 스케일 아웃된 GitLab: Puma 또는 Sidekiq 서버에서 실행합니다.
• 클라우드 네이티브 설치: toolbox Pod에서 실행합니다.
• 기타 모든 구성: GitLab 서버에서 실행합니다.

필요에 따라 명령을 수정합니다:

• 기본 경로 - 기본 파일 경로(/var/opt/gitlab/gitlab-rails/tmp/sos.zip)로 명령을 실행하려면 gitlab-rake gitlab:db:sos를 실행합니다.
• 사용자 지정 경로 - 파일 경로를 변경하려면 gitlab-rake gitlab:db:sos["/absolute/custom/path/to/file.zip"]를 실행합니다.
• Zsh 사용자 - Zsh 구성을 수정하지 않았다면 다음과 같이 전체 명령을 따옴표로 감싸야 합니다: gitlab-rake "gitlab:db:sos[/absolute/custom/path/to/file.zip]"

이 Rake 작업은 5분 동안 실행됩니다. 지정한 경로에 압축 폴더를 만듭니다. 압축 폴더에는 많은 수의 파일이 들어 있습니다.

선택적 쿼리 통계 데이터 활성화#

gitlab:db:sos Rake 작업은 pg_stat_statements 확장을 사용해 느린 쿼리 문제 해결을 위한 데이터도 수집할 수 있습니다.

이 확장의 활성화는 선택 사항이며 PostgreSQL과 GitLab을 재시작해야 합니다. 이 데이터는 느린 데이터베이스 쿼리로 인한 GitLab 성능 문제를 해결할 때 필요할 가능성이 높습니다.

사전 요구 사항:

• 확장을 활성화하거나 비활성화하려면 수퍼유저 권한이 있는 PostgreSQL 사용자여야 합니다.

1. 데이터베이스 콘솔에서 다음을 실행합니다:

   CREATE EXTENSION pg_stat_statements;
   

2. 확장이 작동하는지 확인합니다:

   SELECT extname FROM pg_extension WHERE extname = 'pg_stat_statements';
   SELECT * FROM pg_stat_statements LIMIT 10;
   

CI/CD 중복 태그에 대한 데이터베이스 확인#

히스토리

• GitLab 17.10에서 도입되었습니다.

이 Rake 작업은 ci 데이터베이스의 tags 테이블에서 중복 태그를 확인합니다. 이 문제는 오랜 기간에 걸쳐 여러 번의 주요 업그레이드를 거친 인스턴스에 영향을 줄 수 있습니다. 다음 명령을 실행하면 중복 태그를 검색한 뒤, 중복 태그를 참조하는 태그 할당이 원래 태그를 사용하도록 다시 씁니다.

sudo gitlab-rake gitlab:db:deduplicate_tags

이 명령을 드라이 런 모드로 실행하려면 환경 변수 DRY_RUN=true를 설정합니다.

PostgreSQL 콜레이션 버전 불일치 감지#

히스토리

• GitLab 18.2에서 도입되었습니다.
• GitLab 18.3에서 사전 정의된 인덱스 세트의 손상 스팟 확인이 도입되었습니다.
• GitLab 18.4에서 MAX_TABLE_SIZE를 사용자 지정하고 PgBouncer를 우회하는 옵션이 도입되었습니다.

PostgreSQL 콜레이션 검사기는 다음을 수행합니다:

• 인덱스 손상을 유발할 수 있는 데이터베이스와 운영 체제 간의 콜레이션 버전 불일치를 감지합니다. PostgreSQL은 문자열 콜레이션(정렬 및 비교 규칙)에 운영 체제의 glibc 라이브러리를 사용합니다.
• 사전 정의된 인덱스 세트에 대해 손상 스팟 확인(중복 감지)을 수행합니다. 이러한 인덱스는 콜레이션 불일치로 인한 손상 문제가 발생하기 쉬운 것으로 알려져 있습니다.

기반이 되는 glibc 라이브러리를 변경하는 운영 체제 업그레이드 후에 이 작업을 실행합니다.

사전 요구 사항:

• PostgreSQL 13 이상.

모든 데이터베이스에서 PostgreSQL 콜레이션 불일치와 관련 인덱스 손상을 확인하려면 다음을 실행합니다:

sudo gitlab-rake gitlab:db:collation_checker

특정 데이터베이스를 확인하려면 다음을 실행합니다:

# Check main database
sudo gitlab-rake gitlab:db:collation_checker:main

# Check CI database
sudo gitlab-rake gitlab:db:collation_checker:ci

테이블 크기 한도 조정#

기본적으로 1GB보다 큰 테이블은 데이터베이스 성능에 영향을 줄 수 있는 오래 실행되는 쿼리를 방지하기 위해 건너뜁니다. MAX_TABLE_SIZE 환경 변수를 설정해 테이블 크기 임계값을 조정할 수 있습니다.

# Set custom table size limit (in bytes)
# to increase the max table size threshold to 10 GB
MAX_TABLE_SIZE=10737418240 sudo gitlab-rake gitlab:db:collation_checker:main

오래 실행되는 쿼리를 위한 PgBouncer 우회#

문제 해결 섹션의 명령문 시간 초과 오류 해결을 참고합니다.

출력 예시#

문제가 발견되지 않은 경우:

Checking for PostgreSQL collation mismatches on main database...
No collation mismatches detected on main.
Found 8 indexes to corruption spot check.
No corrupted indexes detected.

불일치가 감지되면 이 작업은 영향받은 인덱스를 수정하기 위한 조치 단계를 제공합니다.

불일치가 있는 경우의 출력 예시:

Checking for PostgreSQL collation mismatches on main database...
⚠️ COLLATION MISMATCHES DETECTED on main database!
2 collation(s) have version mismatches:
  - en_US.utf8: stored=428.1, actual=513.1
  - es_ES.utf8: stored=428.1, actual=513.1

Found 8 indexes to corruption spot check.
Affected indexes that need to be rebuilt:
  - index_projects_on_name (btree) on table projects
    • Issues detected: duplicates
    • Affected columns: name
    • Type: UNIQUE
    • Needs deduplication: Yes

REMEDIATION STEPS:
1. Put GitLab into maintenance mode
2. Run the following SQL commands:

# Step 1: Check for duplicate entries in unique indexes
SELECT name, COUNT(*), ARRAY_AGG(id) FROM projects GROUP BY name HAVING COUNT(*) > 1 LIMIT 1;

# If duplicates exist, you may need to use gitlab:db:deduplicate_tags or similar tasks
# to fix duplicate entries before rebuilding unique indexes.

# Step 2: Rebuild affected indexes
# Option A: Rebuild individual indexes with minimal downtime:
REINDEX INDEX CONCURRENTLY index_projects_on_name;

# Option B: Alternatively, rebuild all indexes at once (requires downtime):
REINDEX DATABASE main;

# Step 3: Refresh collation versions
ALTER DATABASE main REFRESH COLLATION VERSION;

3. Take GitLab out of maintenance mode

PostgreSQL 콜레이션 문제와 그것이 데이터베이스 인덱스에 미치는 영향에 대한 자세한 내용은 PostgreSQL 운영 체제 업그레이드 문서를 참고합니다.

손상된 데이터베이스 인덱스 복구#

히스토리

• GitLab 18.2에서 도입되었습니다.
• GitLab 18.4에서 PgBouncer를 우회하는 옵션이 도입되었습니다.

인덱스 복구 도구는 데이터 정합성 문제를 유발할 수 있는 손상되거나 누락된 데이터베이스 인덱스를 수정합니다. 이 도구는 콜레이션 불일치나 그 밖의 손상 문제로 영향을 받은 특정 문제 인덱스를 처리합니다. 이 도구는 다음을 수행합니다:

• 고유 인덱스가 손상된 경우 데이터를 중복 제거합니다.
• 데이터 정합성을 유지하기 위해 참조를 업데이트합니다.
• 올바른 구성으로 인덱스를 재빌드하거나 생성합니다.

인덱스를 복구하기 전에 드라이 런 모드로 도구를 실행해 변경될 수 있는 내용을 분석합니다:

sudo DRY_RUN=true gitlab-rake gitlab:db:repair_index

다음 출력 예시는 변경 내용을 보여 줍니다:

INFO -- : DRY RUN: Analysis only, no changes will be made.
INFO -- : Running Index repair on database main...
INFO -- : Processing index 'index_merge_request_diff_commit_users_on_name_and_email'...
INFO -- : Index is unique. Checking for duplicate data...
INFO -- : No duplicates found in 'merge_request_diff_commit_users' for columns: name,email.
INFO -- : Index exists. Reindexing...
INFO -- : Index reindexed successfully.

모든 데이터베이스에서 알려진 모든 문제 인덱스를 복구하려면 다음을 실행합니다:

sudo gitlab-rake gitlab:db:repair_index

이 명령은 각 데이터베이스를 처리하고 인덱스를 복구합니다. 예를 들어 다음과 같습니다:

INFO -- : Running Index repair on database main...
INFO -- : Processing index 'index_merge_request_diff_commit_users_on_name_and_email'...
INFO -- : Index is unique. Checking for duplicate data...
INFO -- : No duplicates found in 'merge_request_diff_commit_users' for columns: name,email.
INFO -- : Index does not exist. Creating new index...
INFO -- : Index created successfully.
INFO -- : Index repair completed for database main.

특정 데이터베이스의 인덱스를 복구하려면 다음을 실행합니다:

# Repair indexes in main database
sudo gitlab-rake gitlab:db:repair_index:main

# Repair indexes in CI database
sudo gitlab-rake gitlab:db:repair_index:ci

오래 실행되는 쿼리를 위한 PgBouncer 우회#

문제 해결 섹션의 명령문 시간 초과 오류 해결을 참고합니다.

문제 해결#

어드바이저리 잠금 연결 정보#

db:migrate Rake 작업을 실행한 후 다음과 같은 출력이 표시될 수 있습니다:

main: == [advisory_lock_connection] object_id: 173580, pg_backend_pid: 5532
main: == [advisory_lock_connection] object_id: 173580, pg_backend_pid: 5532

반환된 메시지는 정보 제공용이며 무시할 수 있습니다.

gitlab:env:info Rake 작업 실행 시 PostgreSQL 소켓 오류#

Gitaly 또는 그 밖의 비 Rails 노드에서 sudo gitlab-rake gitlab:env:info를 실행한 후 다음 오류가 표시될 수 있습니다:

PG::ConnectionBad: could not connect to server: No such file or directory
Is the server running locally and accepting
connections on Unix domain socket "/var/opt/gitlab/postgresql/.s.PGSQL.5432"?

멀티 노드 환경에서 gitlab:env:info Rake 작업은 GitLab Rails를 실행하는 노드에서만 실행해야 하기 때문입니다.

명령문 시간 초과 오류 해결#

GitLab 인스턴스가 PgBouncer를 사용하고 데이터베이스 유지 관리 작업(콜레이션 검사기 또는 인덱스 복구 등) 중에 명령문 시간 초과가 발생하면, PostgreSQL 직접 연결을 사용해 PgBouncer를 우회합니다.

# Example with direct connection
GITLAB_BACKUP_PGUSER=postgres GITLAB_BACKUP_PGHOST=localhost sudo gitlab-rake gitlab:db:collation_checker

GITLAB_BACKUP_PGUSER=postgres GITLAB_BACKUP_PGHOST=localhost sudo gitlab-rake gitlab:db:repair_index

지원되는 환경 변수:

• GITLAB_BACKUP_PGHOST
• GITLAB_BACKUP_PGUSER
• GITLAB_BACKUP_PGPORT
• GITLAB_BACKUP_PGPASSWORD

PgBouncer 우회와 지원되는 환경 변수의 전체 목록에 대한 자세한 내용은 PgBouncer 우회 절차를 참고합니다.