PostgreSQL

Tier: Free, Premium, Ultimate Offering: Self-managed

이 페이지에는 GitLab 지원팀이 문제 해결 시 사용하는 PostgreSQL에 대한 정보가 포함되어 있습니다. GitLab은 이 정보를 공개하여 누구나 지원팀이 수집한 지식을 활용할 수 있도록 합니다.

caution
여기에 문서화된 일부 프로시저는 GitLab 인스턴스를 손상시킬 수 있습니다. 본인 책임 하에 사용해 주십시오.

만약 유료 티어를 사용 중이고 이 명령어를 사용하는 방법을 잘 모르는 경우, 문제 해결에 도움을 받으려면 지원팀에 문의하십시오.

데이터베이스 콘솔 시작

Linux 패키지 (Omnibus)

권장 사항:

  • 단일 노드 인스턴스.
  • 스케일 아웃 또는 하이브리드 환경에서 Patroni 노드, 일반적으로 리더에서 실행.
  • 스케일 아웃 또는 하이브리드 환경에서 PostgreSQL 서비스를 실행하는 서버. 
sudo gitlab-psql

단일 노드 인스턴스 또는 웹 또는 Sidekiq 노드의 경우 Rails 데이터베이스 콘솔을 사용할 수도 있지만 초기화하는 데 더 오래 걸립니다:

  • GitLab 14.2 및 이후: 

    sudo gitlab-rails db-console --database main

  • GitLab 14.1 및 이전: 

    sudo gitlab-rails db-console
도커
docker exec -it <container-id> gitlab-psql
직접 컴파일(소스)

설치된 PostgreSQL의 일부인 psql 명령어를 사용합니다. 여기를 참조하세요. 

sudo -u git -H psql -d gitlabhq_production
Helm 차트 (Kubernetes)
  • 하이브리드 환경을 실행 중이고 PostgreSQL이 Linux 패키지 설치(Omnibus)에서 실행 중인 경우 권장되는 접근 방식은 해당 서버에서 로컬로 데이터베이스 콘솔을 사용하는 것입니다. Linux 패키지에 대한 자세한 내용은 세부 정보를 참조하십시오.
  • 외부 제3자 PostgreSQL 서비스의 콘솔을 사용합니다.
  • toolbox pod에서 gitlab-rails db-console을 실행합니다.

콘솔을 종료하려면 quit을 입력하십시오.

기타 GitLab PostgreSQL 문서

이 섹션은 GitLab 문서의 다른 위치에 대한 링크를 포함합니다.

프로시저

지원 주제

데이터베이스 데드락

note
ERROR: deadlock detected

이슈 #30528에서 세 가지 적용 가능한 타임아웃이 식별되고 다음과 같이 권장되는 설정이 있습니다: 

deadlock_timeout = 5s
statement_timeout = 15s
idle_in_transaction_session_timeout = 60s

이슈 #30528에서 인용하자면:

“데드락이 발생하고 우리가 짧은 시간 후에 트랜잭션을 중단하여 해결하면 이미 가지고 있는 재시도 메커니즘이 데드락에 걸린 작업을 다시 시도하게 만들고 여러 번 데드락이 발생할 가능성이 적다.”

지원팀에서 타임아웃을 재구성하는 일반적인 접근 방식은 (HTTP 스택도 포함하여) 일시적으로 문제를 해결하기 위해 허용됩니다. 만약 이로써 GitLab을 사용할 수 있는 상태가 된다면, 이는 문제를 보다 완전히 이해하거나 핫 픽스를 구현하거나 루트 원인을 해결하는 다른 변경을 하는 데 시간을 벌어줍니다. 일반적으로 루트 원인이 해결되면 타임아웃을 합리적인 기본값으로 돌려놓아야 합니다. 일반적으로 타임아웃은 루트 원인이 해결될 때 합리적인 기본값으로 되돌려야 합니다. 보통, 타임아웃은 루트 원인이 완전히 해결되면 제데로 된 기본값으로 돌려놓아야 합니다. 이 경우, 개발팀으로부터 가이드는 deadlock_timeout 또는 statement_timeout 설정을 삭제하라고 했지만, 세 번째 설정 값을 60초로 유지하는 것입니다. idle_in_transaction은 잠재적으로 몇 일 동안 정지할 수 있는 세션으로부터 데이터베이스를 보호합니다. 더 많은 토론은 GitLab.com에 이러한 타임아웃을 도입하는 이슈와 관련된 이슈에 있습니다.

PostgreSQL 기본 설정:

  • statement_timeout = 0 (절대 아님)
  • idle_in_transaction_session_timeout = 0 (절대 아님)

이슈 #30528에 대한 주석에서 모든 Linux 패키지 설치의 경우 최소한 몇 분 동안은 이러한 설정들을 설정하지 않도록 해야 함을 나타냅니다(계속해서 영원히 굉장히 짧은 경우). 그러나 statement_timeout을 15초로 설정하는 것은 아주 짧으며 기반이 매우 뛰어날 때만 효과적입니다.

현재 설정은 다음과 같이 확인할 수 있습니다: 

sudo gitlab-rails runner "c = ApplicationRecord.connection ; puts c.execute('SHOW statement_timeout').to_a ;
puts c.execute('SHOW deadlock_timeout').to_a ;
puts c.execute('SHOW idle_in_transaction_session_timeout').to_a ;"

응답에는 어느 정도 시간이 걸릴 수 있습니다. 

{"statement_timeout"=>"1min"}
{"deadlock_timeout"=>"0"}
{"idle_in_transaction_session_timeout"=>"1min"}

이러한 설정은 다음과 같이 /etc/gitlab/gitlab.rb에서 업데이트할 수 있습니다: 

postgresql['deadlock_timeout'] = '5s'
postgresql['statement_timeout'] = '15s'
postgresql['idle_in_transaction_session_timeout'] = '60s'

저장한 후에는 GitLab 재구성을 실행하여 변경 사항이 적용되도록 합니다.

note
이러한 설정은 Linux 패키지 설정입니다. 고객의 PostgreSQL 설치 또는 Amazon RDS와 같은 외부 데이터베이스를 사용하는 경우 이러한 값은 설정되지 않으며 외부에서 설정해야 합니다.

문장 시간 제한 일시적으로 변경

caution
다음의 조언은 다음의 경우에는 적용되지 않습니다. PgBouncer가 활성화된 경우, 변경된 시간 제한은 의도치 않게 더 많은 트랜잭션에 영향을 줄 수 있습니다.

특정 상황에서는 GitLab을 다시 구성하지 않고도 다른 문장 시간 제한을 설정하는 것이 바람직할 수 있습니다. 이 경우에는 Puma와 Sidekiq을 다시 시작해야 합니다.

예를 들어, 백업 명령어의 출력에 다음과 같은 오류가 나타나면 문장 시간 제한이 너무 짧은 것입니다: 백업 명령어 에서 다음과 같은 오류가 발생할 수 있습니다. 

pg_dump: error: Error message from server: server closed the connection unexpectedly

또한 PostgreSQL 로그에도 다음과 같은 오류가 표시될 수 있습니다: 

canceling statement due to statement timeout

문장 시간 제한을 일시적으로 변경하려면:

  1. 편집기에서 /var/opt/gitlab/gitlab-rails/etc/database.yml를 엽니다.
  2. statement_timeout의 값을 0으로 설정하여 무제한 문장 시간을 설정합니다.

  3. 새로운 Rails 콘솔 세션에서 확인 합니다. 이 값을 사용하도록 확인하세요: 

    sudo gitlab-rails runner "ActiveRecord::Base.connection_config[:variables]"
  4. 필요한 다른 시간 제한이 필요한 작업을 수행합니다 (예: 백업 또는 Rails 명령).
  5. /var/opt/gitlab/gitlab-rails/etc/database.yml의 편집을 되돌립니다.

문제 해결

데이터베이스가 wraparound 데이터 손실을 피하려고 명령을 받아들이지 않음

이 오류는 autovacuum이 실행을 완료하지 못하고 실패했음을 의미합니다: 

ERROR:  database is not accepting commands to avoid wraparound data loss in database "gitlabhq_production"

또는 

 ERROR:  failed to re-find parent key in index "XXX" for deletion target page XXX

이 오류를 해결하려면 매뉴얼으로 VACUUM을 실행합니다:

  1. 명령어 gitlab-ctl stop으로 GitLab을 중지합니다.

  2. 명령어로 데이터베이스를 단일 사용자 모드로 설정합니다: 

    /opt/gitlab/embedded/bin/postgres --single -D /var/opt/gitlab/postgresql/data gitlabhq_production
  3. backend> 프롬프트에서 VACUUM;을 실행합니다. 이 명령어는 완료까지 몇 분이 걸릴 수 있습니다.
  4. 명령어가 완료되기를 기다린 후, Control + D를 눌러 종료합니다.
  5. 명령어 gitlab-ctl start로 GitLab을 시작합니다.

GitLab 데이터베이스 요구 사항

데이터베이스 요구 사항을 확인하고 필요한 확장 디렉터리을 검토하고 설치하세요.

production/sidekiq 로그의 직렬화 오류

production/sidekiq 로그에서 이 예시와 같은 오류를 받으면, 문제를 해결하기 위해 default_transaction_isolation을 읽기 전용으로 설정해야 합니다: 

ActiveRecord::StatementInvalid PG::TRSerializationFailure: ERROR:  could not serialize access due to concurrent update

PostgreSQL 복제 슬롯 오류

다음과 같은 오류를 받으면, PostgreSQL HA의 복제 슬롯 오류를 해결하는 방법을 읽어보세요: 

pg_basebackup: could not create temporary replication slot "pg_basebackup_12345": ERROR:  all replication slots are in use
HINT:  Free one or increase max_replication_slots.

Geo 복제 오류

다음과 같은 오류를 받으면, Geo 복제 오류를 해결하는 방법을 읽어보세요: 

ERROR: replication slots can only be used if max_replication_slots > 0

FATAL: could not start WAL streaming: ERROR: replication slot "geo_secondary_my_domain_com" does not exist

Command exceeded allowed execution time

PANIC: could not write to file 'pg_xlog/xlogtemp.123': No space left on device

Geo 구성 및 일반적인 오류 확인

Geo에서 문제를 해결할 때 다음을 해야 합니다:

  • 일반 Geo 오류를 확인합니다.
  • Geo 구성을 검토하고:
    • 호스트와 포트를 다시 구성합니다.
    • 사용자 및 패스워드 매핑을 검토하고 수정합니다.

pg_dump 및 psql 버전 불일치

다음과 같은 오류를 받으면, 비 패키지화된 PostgreSQL 데이터베이스 백업 및 복원에 대해 읽어보세요: 

Dumping PostgreSQL database gitlabhq_production ... pg_dump: error: server version: 13.3; pg_dump version: 14.2
pg_dump: error: aborting because of server version mismatch

btree_gist 확장이 허용 디렉터리에 없음

Azure Database for PostgreSQL - Flexible Server에 PostgreSQL을 배포하면 이 오류가 발생할 수 있습니다: 

extension "btree_gist" is not allow-listed for "azure_pg_admin" users in Azure Database for PostgreSQL

이 오류를 해결하려면 설치 전에 확장을 허용 디렉터리에 추가하세요.