PostgreSQL

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

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

경고: 여기에 기술된 일부 절차는 GitLab 인스턴스를 손상시킬 수 있습니다. 사용 전 주의하십시오.

paid tier의 사용자이고 이 명령어 사용 방법을 모르는 경우, 지원팀에 문의하여 도움을 받으십시오.

데이터베이스 콘솔 시작

Linux 패키지 (Omnibus)

추천 대상:

  • 단일 노드 인스턴스.
  • 확장된 환경이거나 혼합 환경, 보통 Patroni 노드 또는 리더 노드에 있습니다.
  • 확장된 환경이거나 혼합 환경, PostgreSQL 서비스를 실행하는 서버에 있습니다. 
sudo gitlab-psql

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

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

설치 단계에 포함된 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 문서의 다른 위치에 대한 링크를 포함합니다.

절차

지원 주제

데이터베이스 데드락

참고: 

ERROR: deadlock detected

issue #30528에서 세 가지 적용 가능한 타임아웃이 식별되었으며, 권장 설정은 다음과 같습니다: 

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

issue #30528에서 인용:

“데드락이 발생하고 해당 트랜잭션을 짧은 시간 이후에 중단하여 해결하면 이미 있는 재시도 메커니즘이 데드락에 이르게 될 작업을 다시 시도하게 되며, 여러 번 연속해서 데드락에 걸릴 가능성은 낮습니다.”

지원팀에서는 타임아웃을 재구성하는 일반적인 방법(마찬가지로 HTTP 스택에도 해당됨)은 일시적으로 사용하여 문제를 이해하고 완전히 해결하는데 시간을 벌어주거나, 문제의 근본 원인을 해결하는 데 도움을 주거나, 또는 기타 변경 사항을 가하는 데 사용할 수 있습니다. 일반적으로 루트 원인이 해결된 후에 타임아웃을 합리적인 기본값으로 되돌려야 합니다. 일반적으로 타임아웃은 루트 원인이 해결될 때까지 임시로 설정되었으며, 일시적인 해결책으로 사용됩니다. 말한 설정에 관해, 개발팀의 안내에 따르면 deadlock_timeout 또는 statement_timeout을 삭제하고 세 번째 설정을 60초로 유지해야 합니다. idle_in_transaction은 세션이 잠재적으로 여러 날 동안 대기할 수 있는 데이터베이스를 보호합니다. GitLab.com에 이 타임아웃을 도입하는 데 관한 이슈에서 더 많은 토론이 있습니다.

PostgreSQL 기본 설정:

  • statement_timeout = 0 (미설정)
  • idle_in_transaction_session_timeout = 0 (미설정)

issue #30528의 코멘트에서 모든 리눅스 패키지 설치에서 이러한 값을 최소한 몇 분 동안으로 설정해야한다는 내용이 나옵니다 (무기한 대기하지 않도록 함). 그러나 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을 재구성하십시오.

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

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

경고: 변경된 제한시간이 의도한 이상 이상의 트랜잭션에 영향을 줄 수 있기 때문에 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의 편집을 되돌립니다.

문제 해결

데이터베이스가 한바퀴 돈다는 데이터 손실을 피하기 위해 명령을 수락하지 않음

이 오류는 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. 명령어로 데이터베이스를 single-user 모드로 변경합니다: 

    /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을 read committed로 설정하기를 읽어보세요. 

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

이 오류를 해결하려면 설치 전에 확장 기능을 허용 목록에 추가하세요.