이 페이지는 GitLab 지원팀이 문제 해결 시 사용하는 PostgreSQL 관련 정보를 포함합니다. GitLab은 지원팀의 축적된 지식을 누구나 활용할 수 있도록 이 정보를 공개합니다.

유료 티어를 사용 중이고 이러한 명령을 사용하는 방법이 확실하지 않다면 문제 해결을 위해 지원팀에 문의하세요.

데이터베이스 콘솔 시작#

sudo gitlab-psql

sudo gitlab-rails dbconsole --database main

docker exec -it <container-id> gitlab-psql

sudo -u git -H psql -d gitlabhq_production

콘솔을 종료하려면 quit을 입력하세요.

기타 GitLab PostgreSQL 문서#

이 섹션은 GitLab 문서의 다른 곳에 있는 정보 링크를 제공합니다.

절차#

• SSL 활성화, 비활성화 및 검증을 포함한 Linux 패키지 설치를 위한 데이터베이스 절차:
  • Write Ahead Log(WAL) 아카이빙 활성화.
  • 외부(비 Omnibus) PostgreSQL 설치 사용 및 백업.
  • 소켓 외에도 또는 대신 TCP/IP에서 수신 대기.
  • 다른 위치에 데이터 저장.
  • GitLab 데이터베이스 파괴적 재시드.
  • 패키지된 PostgreSQL 업데이트에 관한 지침(자동 업데이트 중지 방법 포함).
• 외부 PostgreSQL 정보.
• 외부 PostgreSQL로 Geo 실행.
• HA를 위해 PostgreSQL이 구성된 경우 업그레이드.
• CI 러너 내에서 PostgreSQL 사용.
• Linux 패키지 개발 문서에서 Linux 패키지 설치의 PostgreSQL 버전 관리.
• PostgreSQL 스케일링
  • gitlab-ctl patroni check-leader 및 PgBouncer 오류에 대한 문제 해결 포함.
• 개발자 데이터베이스 문서, 그 중 일부는 절대 프로덕션에서 사용하지 않아야 합니다. 포함:
  • EXPLAIN 계획 이해.

지원 주제#

데이터베이스 데드락#

참조:

• 인스턴스가 푸시로 폭주하면 데드락이 발생할 수 있습니다. GitLab 코드가 비정상적인 상황에서 이런 종류의 예상치 못한 영향을 미칠 수 있다는 컨텍스트를 제공합니다.

ERROR: deadlock detected

이슈 #30528에서 세 가지 적용 가능한 타임아웃이 확인됩니다; 권장 설정은 다음과 같습니다:

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

이슈 #30528에서 인용:

"데드락이 발생하고 짧은 시간 후 트랜잭션을 중단하여 해결하면, 이미 가지고 있는 재시도 메커니즘이 데드락된 작업을 다시 시도하게 하며, 여러 번 연속으로 데드락이 발생할 가능성은 낮습니다."

이 경우, 개발팀에서 받은 지침은 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을 재구성합니다.

statement timeout 임시 변경#

일부 상황에서는 Puma와 Sidekiq를 재시작하는 GitLab 재구성 없이 다른 statement timeout을 설정하는 것이 바람직할 수 있습니다.

예를 들어 백업 명령 출력에서 statement timeout이 너무 짧아 다음 오류로 백업이 실패할 수 있습니다:

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

PostgreSQL 로그에서도 오류를 볼 수 있습니다:

canceling statement due to statement timeout

Linux 패키지 설치의 경우#

statement timeout을 임시로 변경하려면:

1. 편집기에서 /var/opt/gitlab/gitlab-rails/etc/database.yml을 엽니다.

2. statement_timeout 값을 0으로 설정하여 무제한 statement timeout을 설정합니다.

3. 새 Rails 콘솔 세션에서 이 값이 사용되는지 확인합니다:

   sudo gitlab-rails runner "ActiveRecord::Base.connection_db_config[:variables]"
   

4. 다른 타임아웃이 필요한 작업을 수행합니다(예: 백업 또는 Rails 명령).

5. /var/opt/gitlab/gitlab-rails/etc/database.yml의 편집을 되돌립니다.

클라우드 네이티브 배포의 경우#

관리형 PostgreSQL 서비스(예: AWS RDS, Azure Database for PostgreSQL, Google Cloud SQL)를 사용하는 클라우드 네이티브 배포의 경우, 데이터베이스 구성 파일을 직접 수정할 수 없습니다. 대신 클라우드 서비스의 파라미터 그룹 또는 구성 인터페이스를 통해 statement_timeout 파라미터를 구성합니다:

• AWS RDS: 데이터베이스 인스턴스와 관련된 파라미터 그룹을 수정하고 statement_timeout을 0(무제한)으로 설정합니다.
• Azure Database for PostgreSQL: Azure 포털의 서버 파라미터를 업데이트하고 statement_timeout을 0으로 설정합니다.
• Google Cloud SQL: 데이터베이스 플래그를 수정하고 statement_timeout을 0으로 설정합니다.

파라미터 그룹 또는 구성을 변경한 후 변경 사항이 적용되도록 데이터베이스 인스턴스를 재부팅해야 할 수 있습니다. 구체적인 지침은 클라우드 제공업체의 문서를 참조하세요.

(RE)INDEX 진행 보고서 관찰#

일부 상황에서는 CREATE INDEX 또는 REINDEX 작업의 진행 상황을 관찰하고 싶을 수 있습니다. 예를 들어 CREATE INDEX 또는 REINDEX 작업이 활성 상태인지 확인하거나 작업의 단계를 확인하기 위해 수행할 수 있습니다.

사전 요구 사항:

• PostgreSQL 버전 12 이상을 사용해야 합니다.

CREATE INDEX 또는 REINDEX 작업을 관찰하려면:

• 내장된 pg_stat_progress_create_index 뷰를 사용합니다.

예를 들어 데이터베이스 콘솔 세션에서 다음 명령을 실행합니다:

SELECT * FROM  pg_stat_progress_create_index \watch 0.2

사람이 읽기 쉬운 출력 생성 및 로그 파일에 데이터 쓰기에 대해 자세히 알아보려면 이 스니펫을 참조하세요.

문제 해결#

데이터베이스 연결 거부#

다음 오류가 발생하면 안정적인 연결을 위해 max_connections가 충분히 높은지 확인하세요.

connection to server at "xxx.xxx.xxx.xxx", port 5432 failed: Connection refused
      Is the server running on that host and accepting TCP/IP connections?

psql: error: connection to server on socket "/var/opt/gitlab/postgresql/.s.PGSQL.5432" failed:
FATAL:  sorry, too many clients already

max_connections를 조정하려면 여러 데이터베이스 연결 구성을 참조하세요.

데이터베이스가 래퍼라운드 데이터 손실 방지를 위해 명령을 수락하지 않음#

이 오류는 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을 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

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