데이터베이스 설정

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

GitLab은 PostgreSQL 데이터베이스 관리 시스템만 지원합니다.

따라서 Linux 패키지 설치와 함께 사용할 수 있는 데이터베이스 서버에는 두 가지 옵션이 있습니다:

Linux 패키지 설치에 포함된 패키지 PostgreSQL 서버 사용 (구성 필요 없음, 추천)
외부 PostgreSQL 서버 사용

Linux 패키지와 함께 제공되는 PostgreSQL 데이터베이스 서비스 사용

재구성 및 PostgreSQL 재시작

Linux 패키지 설치는 일반적으로 gitlab.rb 파일에서 해당 서비스의 구성 설정이 변경된 경우 재구성 시 서비스를 재시작합니다. PostgreSQL은 일부 설정이 리로드(HUP)와 함께 적용되는 반면, 다른 설정은 PostgreSQL을 재시작해야 하는 점에서 독특합니다. 관리자는 PostgreSQL이 언제 재시작되는지에 대한 더 많은 제어를 원하기 때문에, Linux 패키지 설치는 재구성 시 PostgreSQL을 재시작하는 것이 아니라 리로드하도록 구성되어 있습니다. 이는 재시작이 필요한 PostgreSQL 설정을 수정하면, 재구성 후 수동으로 PostgreSQL을 재시작해야 함을 의미합니다.

GitLab 구성 템플릿은 어떤 PostgreSQL 설정이 재시작이 필요하고 어떤 설정이 리로드만 필요한지를 식별합니다. 데이터베이스에 대해 쿼리를 실행하여 개별 설정이 재시작이 필요한지 확인할 수도 있습니다. sudo gitlab-psql로 데이터베이스 콘솔을 시작한 후, 다음 쿼리에서 <setting name>을 변경하려는 설정으로 대체하세요:

SELECT name,setting FROM pg_settings WHERE context = 'postmaster' AND name = '<setting name>';

설정을 변경하는 데 재시작이 필요하면, 쿼리는 해당 설정의 이름과 현재 PostgreSQL 인스턴스에서 해당 설정의 값을 반환합니다.

PostgreSQL 버전 변경 시 자동 재시작

기본적으로, Linux 패키지 설치는 기본 버전이 변경될 때 PostgreSQL을 자동으로 재시작합니다. 이는 업스트림 문서에서 제안한 대로입니다. 이 동작은 postgresql 및 geo-postgresql에 대해 사용할 수 있는 auto_restart_on_version_change 설정을 사용하여 제어할 수 있습니다.

PostgreSQL 버전이 변경될 때 자동 재시작을 비활성화하려면:

/etc/gitlab/gitlab.rb를 편집하고 다음 줄을 추가합니다:

# PostgreSQL/Patroni용
postgresql['auto_restart_on_version_change'] = false

# Geo PostgreSQL용
geo_postgresql['auto_restart_on_version_change'] = false

GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

참고:
기본 버전이 변경될 때 PostgreSQL을 재시작하는 것이 적극 권장되며, 이는 필요한 라이브러리를 로드하는 것과 관련된 오류와 같은 문제를 피할 수 있습니다.

SSL 구성

Linux 패키지 설치는 자동으로 PostgreSQL 서버에서 SSL을 활성화하지만, 기본적으로 암호화된 연결과 암호화되지 않은 연결을 모두 수용합니다. SSL을 강제하려면 pg_hba.conf에서 hostssl 구성을 사용해야 합니다. 자세한 내용은 pg_hba.conf 문서를 참조하세요.

SSL 지원은 다음 파일에 의존합니다:

데이터베이스용 공개 SSL 인증서 (server.crt)
SSL 인증서에 대한 해당 개인 키 (server.key)
서버 인증서를 검증하는 루트 인증서 번들 (root.crt)
기본적으로 Linux 패키지 설치는 /opt/gitlab/embedded/ssl/certs/cacert.pem에 내장된 인증서 번들을 사용합니다. 이것은 자체 서명된 인증서에는 필요하지 않습니다.

Linux 패키지 설치를 통해 사용하기 위해 10년 유효한 자체 서명된 인증서와 개인 키가 생성됩니다. CA 서명된 인증서를 사용하거나 사용자의 자체 서명된 인증서로 교체하려면 다음 단계를 따르세요.

이 파일들의 위치는 구성 가능하지만, 개인 키는 gitlab-psql 사용자가 읽을 수 있어야 합니다. Linux 패키지 설치는 파일의 권한을 관리하지만, 경로가 사용자 지정된 경우 gitlab-psql이 파일이 배치된 디렉터리에 접근할 수 있도록 해야 합니다.

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

server.crt와 server.key는 GitLab에 접근하는 데 사용되는 기본 SSL 인증서와 다를 수 있습니다. 예를 들어, 데이터베이스의 외부 호스트 이름이 database.example.com이고 GitLab의 외부 호스트 이름이 gitlab.example.com이라고 가정하면, *.example.com에 대한 와일드카드 인증서 또는 두 개의 다른 SSL 인증서가 필요합니다.

ssl_cert_file, ssl_key_file, 및 ssl_ca_file 파일은 PostgreSQL이 파일 시스템에서 인증서, 키, 및 번들을 찾는 위치를 지정합니다. 이러한 변경 사항은 postgresql.conf에 적용됩니다. 지시문 internal_certificate와 internal_key는 이러한 파일의 내용을 채우는 데 사용됩니다. 내용은 직접 추가하거나 다음 예와 같이 파일에서 로드할 수 있습니다.

이 파일들을 준비한 후, SSL을 활성화하세요:

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

postgresql['ssl_cert_file'] = '/custom/path/to/server.crt'
postgresql['ssl_key_file'] = '/custom/path/to/server.key'
postgresql['ssl_ca_file'] = '/custom/path/to/bundle.pem'
postgresql['internal_certificate'] = File.read('/custom/path/to/server.crt')
postgresql['internal_key'] = File.read('/custom/path/to/server.key')

상대 경로는 PostgreSQL 데이터 디렉터리(/var/opt/gitlab/postgresql/data 기본값)에 뿌리를 두게 됩니다.

GitLab 재구성을 통해 구성 변경 사항을 적용합니다.
변경 사항이 적용되도록 PostgreSQL을 재시작합니다:
```
gitlab-ctl restart postgresql
```
PostgreSQL이 시작되지 않으면, 로그(예: /var/log/gitlab/postgresql/current)를 확인하여 더 자세한 내용을 확인하세요.

SSL 필요

/etc/gitlab/gitlab.rb에 다음을 추가하세요:
```
gitlab_rails['db_sslmode'] = 'require'
```
GitLab 재구성하기하여 구성 변경 사항을 적용합니다.
변경 사항을 적용하기 위해 PostgreSQL을 재시작합니다:
```
gitlab-ctl restart postgresql
```
PostgreSQL이 시작되지 않으면, 더 많은 세부정보를 위해 로그(예: /var/log/gitlab/postgresql/current)를 확인하세요.

SSL 비활성화

/etc/gitlab/gitlab.rb에 다음을 추가하세요:
```
postgresql['ssl'] = 'off'
```
GitLab 재구성하기하여 구성 변경 사항을 적용합니다.
변경 사항을 적용하기 위해 PostgreSQL을 재시작합니다:
```
gitlab-ctl restart postgresql
```
PostgreSQL이 시작되지 않으면, 더 많은 세부정보를 위해 로그(예: /var/log/gitlab/postgresql/current)를 확인하세요.

SSL 사용 여부 확인

클라이언트가 SSL을 사용하고 있는지 확인하려면 다음을 실행할 수 있습니다:

sudo gitlab-rails dbconsole --database main

시작 시 다음과 같은 배너가 표시되어야 합니다:

psql (13.14)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: on)
Type "help" for help.

클라이언트가 SSL을 사용하고 있는지 확인하려면 이 SQL 쿼리를 실행하세요:

SELECT * FROM pg_stat_ssl;

예를 들어:

gitlabhq_production=> select * from pg_stat_ssl;
 pid  | ssl | version |         cipher         | bits | compression |  clientdn
------+-----+---------+------------------------+------+-------------+------------
| f   |         |                        |      |             |
| f   |         |                        |      |             |
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| f   |         |                        |      |             |
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           |
| t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
| f   |         |                        |      |             |
| f   |         |                        |      |             |
| f   |         |                        |      |             |
(16 rows)

ssl 열 아래에 t가 나열된 행은 활성화되어 있습니다.
clientdn에 값이 있는 행은 cert 인증 방법을 사용하고 있습니다.

SSL 클라이언트 인증 구성

클라이언트 SSL 인증서는 데이터베이스 서버에 인증하는 데 사용할 수 있습니다. 인증서 생성을 omnibus-gitlab의 범위를 넘어섭니다. 그러나 기존 SSL 인증서 관리 솔루션이 있는 사용자는 이를 사용할 수 있습니다.

데이터베이스 서버 구성

서버용 인증서와 키를 생성하며, 공통 이름은 서버의 DNS 이름과 같아야 합니다.
서버 인증서, 키, 및 CA 파일을 PostgreSQL 서버로 복사하고 권한이 올바른지 확인합니다.
1. 인증서는 데이터베이스 사용자(기본값: gitlab-psql)의 소유여야 합니다.
2. 키 파일은 데이터베이스 사용자의 소유여야 하며, 그 권한은 0400이어야 합니다.
3. CA 파일은 데이터베이스 사용자의 소유여야 하며, 그 권한은 0400이어야 합니다.
주의: 이러한 파일에 대해 server.crt 또는 server.key라는 파일 이름을 사용하지 마십시오. 이 파일 이름은 omnibus-gitlab의 내부 용도로 예약되어 있습니다.
gitlab.rb에 다음 사항이 설정되어 있는지 확인합니다:
```
postgresql['ssl_cert_file'] = 'PATH_TO_CERTIFICATE'
postgresql['ssl_key_file'] = 'PATH_TO_KEY_FILE'
postgresql['ssl_ca_file'] = 'PATH_TO_CA_FILE'
postgresql['listen_address'] = 'IP_ADDRESS'
postgresql['cert_auth_addresses'] = {
'IP_ADDRESS' => {
  'database' => 'gitlabhq_production',
  'user' => 'gitlab'
}
```
listen_address를 클라이언트가 데이터베이스에 연결하는 데 사용할 서버의 IP 주소로 설정합니다.

cert_auth_addresses에는 데이터베이스에 연결할 수 있는 IP 주소 목록과 데이터베이스 및 사용자가 포함되어야 합니다. cert_auth_addresses의 키를 지정할 때 CIDR 표기법을 사용할 수 있어 IP 주소 범위를 포함할 수 있습니다.
새로운 설정이 적용되도록 gitlab-ctl reconfigure를 실행한 다음 gitlab-ctl restart postgresql을 실행합니다.

Rails 클라이언트 구성

Rails 클라이언트가 서버에 연결하려면 commonName이 gitlab으로 설정된 인증서와 키가 필요하며, 이는 데이터베이스 서버의 ssl_ca_file에 지정된 CA 파일에서 신뢰받는 인증 기관에 의해 서명되어야 합니다.

gitlab.rb를 구성합니다:

gitlab_rails['db_host'] = 'IP_ADDRESS_OR_HOSTNAME_OF_DATABASE_SERVER'
gitlab_rails['db_sslcert'] = 'PATH_TO_CERTIFICATE_FILE'
gitlab_rails['db_sslkey'] = 'PATH_TO_KEY_FILE'
gitlab_rails['db_rootcert'] = 'PATH_TO_CA_FILE'

Rails 클라이언트가 새로운 설정을 사용하도록 gitlab-ctl reconfigure를 실행합니다.
인증이 작동하는지 확인하기 위해 SSL 사용 확인 단계를 따릅니다.

패키지된 PostgreSQL 서버를 TCP/IP에서 수신하도록 구성

패키지된 PostgreSQL 서버는 TCP/IP 연결을 수신하도록 구성할 수 있으며, 비-critical 스크립트가 UNIX 소켓을 예상하며 잘못 작동할 수 있다는 주의 사항이 있습니다.

데이터베이스 서비스에 TCP/IP 사용을 구성하려면 gitlab.rb의 postgresql 및 gitlab_rails 섹션 모두에 변경 사항을 적용합니다.

PostgreSQL 블록 구성

다음 설정은 postgresql 블록에서 영향을 받습니다:

listen_address: PostgreSQL이 기다리는 주소를 제어합니다.
port: PostgreSQL이 듣는 포트를 제어합니다. 기본값은 5432입니다.
md5_auth_cidr_addresses: 비밀번호로 인증한 후에 서버에 연결할 수 있는 CIDR 주소 블록의 목록입니다.
trust_auth_cidr_addresses: 어떤 종류의 인증 없이 서버에 연결할 수 있는 CIDR 주소 블록의 목록입니다. 이 설정은 GitLab Rails 또는 Sidekiq와 같은 연결이 필요할 수 있는 노드에서만 설정해야 합니다. 이에는 동일한 노드에 배포할 때의 로컬 연결이나 Postgres Exporter와 같은 구성 요소에서 연결하는 경우도 포함됩니다(127.0.0.1/32).
sql_user: MD5 인증에 대한 예상 사용자 이름을 제어합니다. 기본값은 gitlab이며, 필수 설정은 아닙니다.
sql_user_password: MD5 인증을 위해 PostgreSQL이 수용할 비밀번호를 설정합니다.

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

postgresql['listen_address'] = '0.0.0.0'
postgresql['port'] = 5432
postgresql['md5_auth_cidr_addresses'] = %w()
postgresql['trust_auth_cidr_addresses'] = %w(127.0.0.1/24)
postgresql['sql_user'] = "gitlab"

##! SQL_USER_PASSWORD_HASH는 `gitlab-ctl pg-password-md5 'gitlab'` 명령어를 사용하여 생성할 수 있습니다,
##! 여기서 'gitlab'은 GitLab에 연결하는 SQL 사용자의 이름입니다. (쉘 보간을 피하기 위해 단일 인용 부호로 묶음)
##! 데이터베이스에 인증하기 위해 다른 클라이언트가 사용할 비밀번호를 입력하라는 메시지가 표시됩니다, 아래 섹션의 `securesqlpassword`와 같은 비밀번호입니다.
postgresql['sql_user_password'] = "SQL_USER_PASSWORD_HASH"

# trust_auth_cidr_addresses 및 md5_auth_cidr_addresses에 정의된 모든 연결에서 ssl 강제
postgresql['hostssl'] = true

GitLab을 재구성하고 PostgreSQL을 재시작합니다:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart postgresql

네트워크를 통해 연결할 모든 클라이언트나 GitLab 서비스는 PostgreSQL 서버에 연결할 때 사용자 이름에 대해 sql_user의 값을 제공하고, 구성에서 제공된 비밀번호를 제공해야 합니다. 또한 md5_auth_cidr_addresses에 제공된 네트워크 블록 내에 있어야 합니다.

GitLab Rails 블록 구성

네트워크를 통해 PostgreSQL 데이터베이스에 연결하도록 gitlab-rails 애플리케이션을 구성하려면, 여러 설정을 구성해야 합니다:

db_host: 데이터베이스 서버의 IP 주소로 설정해야 합니다. PostgreSQL 서비스와 동일한 인스턴스에 있는 경우, 127.0.0.1로 설정할 수 있으며, 비밀번호 인증이 필요하지 않습니다.
db_port: PostgreSQL 서버에 연결할 포트를 설정하며, db_host가 설정되면 설정해야 합니다.
db_username: PostgreSQL에 연결할 때 사용할 사용자 이름을 구성합니다. 기본값은 gitlab입니다.
db_password: TCP/IP를 통해 PostgreSQL에 연결할 때 제공해야 하며, 위의 설정에서 postgresql['md5_auth_cidr_addresses'] 블록에 있는 인스턴스에서 연결하는 경우 제공해야 합니다. 127.0.0.1에 연결하고 postgresql['trust_auth_cidr_addresses']에 이를 포함하도록 구성한 경우에는 필요하지 않습니다.

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

gitlab_rails['db_host'] = '127.0.0.1'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_username'] = "gitlab"
gitlab_rails['db_password'] = "securesqlpassword"

GitLab을 재구성하고 PostgreSQL을 재시작합니다:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart postgresql

적용하고 서비스 재시작하기

이전 변경 사항을 적용한 후, 관리자는 gitlab-ctl reconfigure를 실행해야 합니다.

TCP에서 서비스를 수신하지 않는 문제가 발생하는 경우, gitlab-ctl restart postgresql로 서비스를 직접 재시작해 보십시오.

Linux 패키지에 포함된 일부 스크립트(예: gitlab-psql)는 PostgreSQL에 대한 연결이 UNIX 소켓을 통해 처리되기를 기대하며, 제대로 작동하지 않을 수 있습니다.

UNIX 소켓을 비활성화하지 않고 TCP/IP를 활성화할 수 있습니다.

다른 클라이언트에서 액세스를 테스트하려면 다음 명령을 실행할 수 있습니다:

sudo gitlab-rails dbconsole --database main

PostgreSQL WAL(Write Ahead Log) 아카이빙 활성화하기

기본적으로, 패키지된 PostgreSQL의 WAL 아카이빙은 활성화되어 있지 않습니다. WAL 아카이빙을 활성화하고자 할 때는 다음 사항을 고려하십시오:

WAL 수준은 ‘replica’ 또는 그 이상이어야 합니다(9.6+ 옵션은 minimal, replica, 또는 logical).
WAL 수준을 높이면 일반 작업에서 소모되는 저장소의 양이 증가합니다.

WAL 아카이빙을 활성화하려면:

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

# 복제 설정
postgresql['sql_replication_user'] = "gitlab_replicator"
postgresql['wal_level'] = "replica"
    ...
    ...
# 백업/아카이브 설정
postgresql['archive_mode'] = "on"
postgresql['archive_command'] = "/your/wal/archiver/here"
postgresql['archive_timeout'] = "60"

GitLab 재구성을 진행하여 변경 사항이 적용되도록 하십시오. 이로 인해 데이터베이스가 재시작됩니다.

PostgreSQL 데이터를 다른 디렉토리에 저장하기

기본적으로 모든 데이터는 /var/opt/gitlab/postgresql에 저장되며, postgresql['dir'] 속성에 의해 제어됩니다.

이는 다음으로 구성됩니다:

데이터베이스 소켓은 /var/opt/gitlab/postgresql/.s.PGSQL.5432입니다. 이는 postgresql['unix_socket_directory']로 제어됩니다.
gitlab-psql 시스템 사용자는 HOME 디렉토리가 이곳으로 설정됩니다. 이는 postgresql['home']으로 제어됩니다.
실제 데이터는 /var/opt/gitlab/postgresql/data에 저장됩니다.

PostgreSQL 데이터의 위치를 변경하려면:

경고: 기존 데이터베이스가 있는 경우, 먼저 데이터를 새 위치로 이동해야 합니다.

경고: 이 작업은 침습적인 작업입니다. 기존 설치에서 다운타임 없이 수행할 수 없습니다.

이는 기존 설치인 경우, GitLab을 중지하십시오: gitlab-ctl stop.
postgresql['dir']를 원하는 위치로 업데이트합니다.
gitlab-ctl reconfigure를 실행합니다.
GitLab을 시작합니다: gitlab-ctl start.

패키지된 PostgreSQL 서버 업그레이드하기

Linux 패키지는 пакет된 PostgreSQL 서버를 최신 버전으로 업데이트하는 gitlab-ctl pg-upgrade 명령을 제공합니다(패키지에 포함된 경우). 이러한 업데이트는 패키지 업그레이드 동안 PostgreSQL을 기본 제공 버전으로 업데이트하며, 특정적으로 옵트 아웃 하지 않은 경우입니다.

GitLab을 최신 버전으로 업그레이드하기 전에, Linux 패키지의 버전별 변경 사항을 참조하여 다음 사항을 확인하십시오:

데이터베이스 버전이 변경되었습니다.
업그레이드가 필요한 경우입니다.

경고: 업그레이드 전, 명령을 실행하기 전에 이 섹션을 모두 읽는 것이 중요합니다. 단일 노드 설치의 경우, 데이터베이스가 업그레이드되는 동안 다운타임이 필요합니다. 소요 시간은 데이터베이스의 크기에 따라 다릅니다.

참고: 업그레이드 중 문제가 발생하면, omnibus-gitlab 이슈 트래커에 전체 설명과 함께 이슈를 제기하십시오.

PostgreSQL 버전을 업그레이드하려면 다음을 확인하십시오:

현재 PostgreSQL 버전을 지원하는 최신 버전의 GitLab을 실행 중입니다.
최근에 업그레이드한 경우, 진행하기 전에 sudo gitlab-ctl reconfigure를 성공적으로 실행했습니다.
두 개의 데이터베이스 복사본을 위한 충분한 디스크 공간이 있습니다. 여유 공간이 충분하지 않으면 업그레이드를 시도하지 마십시오.
- sudo du -sh /var/opt/gitlab/postgresql/data를 사용하여 데이터베이스 크기를 확인합니다(또는 데이터베이스 경로를 업데이트합니다).
- sudo df -h를 사용하여 사용 가능한 공간을 확인합니다. 데이터베이스가 있는 파티션에 충분한 공간이 없다면, 명령에 --tmp-dir $DIR 인수를 전달하십시오. 업그레이드 작업에는 사용 가능한 디스크 공간 확인이 포함되며, 요건이 충족되지 않을 경우 업그레이드가 중단됩니다.

위 체크리스트가 만족스러워지면, 업그레이드를 진행할 수 있습니다:

sudo gitlab-ctl pg-upgrade

특정 PostgreSQL 버전으로 업그레이드하려면, -V 플래그를 사용하여 버전을 추가하십시오. 예를 들어, PostgreSQL 16으로 업그레이드하려면:

sudo gitlab-ctl pg-upgrade -V 16

참고: pg-upgrade는 인수를 받을 수 있습니다; 예를 들어, 기본 명령 실행 시간 제한을 설정할 수 있습니다(--timeout=1d2h3m4s5ms). 전체 목록을 보려면 gitlab-ctl pg-upgrade -h를 실행하십시오.

gitlab-ctl pg-upgrade는 다음 단계를 수행합니다:

데이터베이스가 알려진 좋은 상태인지 확인합니다.
충분한 여유 디스크 공간이 있는지 확인하고, 그렇지 않은 경우 중단합니다. --skip-disk-check 플래그를 추가하면 이를 건너뛸 수 있습니다.
기존 데이터베이스와 불필요한 서비스를 중지하고, GitLab이 배포 페이지를 사용할 수 있도록 활성화합니다.
PostgreSQL의 /opt/gitlab/embedded/bin/의 심볼릭 링크를 변경하여 데이터베이스의 최신 버전을 가리킵니다.
새로운 빈 데이터베이스가 포함된 새 디렉토리를 생성합니다. 이는 기존 데이터베이스와 일치하는 로케일을 가집니다.
pg_upgrade 도구를 사용하여 데이터를 기존 데이터베이스에서 새 데이터베이스로 복사합니다.
기존 데이터베이스를 치워버립니다.
새 데이터베이스를 예상 위치로 이동합니다.
필요한 구성 변경을 수행하기 위해 sudo gitlab-ctl reconfigure를 호출하고 새로운 데이터베이스 서버를 시작합니다.
데이터베이스 통계를 생성하기 위해 ANALYZE를 실행합니다.
나머지 서비스를 시작하고 배포 페이지를 제거합니다.
이 과정 중 오류가 감지되면, 기존 데이터베이스의 이전 버전으로 되돌립니다.

업그레이드가 완료되면 모든 것이 예상대로 작동하는지 확인하십시오.

ANALYZE 단계 실행 중 출력에 오류가 발생한 경우, 업그레이드는 여전히 작동하지만 데이터베이스 통계가 생성될 때까지 데이터베이스 성능이 저하됩니다. gitlab-psql을 사용하여 ANALYZE를 수동으로 실행해야 하는지 여부를 확인하십시오:

sudo gitlab-psql -c "SELECT relname, last_analyze, last_autoanalyze FROM pg_stat_user_tables WHERE last_analyze IS NULL AND last_autoanalyze IS NULL;"

위 쿼리가 행을 반환한 경우, 수동으로 ANALYZE를 실행할 수 있습니다:

sudo gitlab-psql -c 'SET statement_timeout = 0; ANALYZE VERBOSE;'

ANALYZE 명령의 실행 시간은 데이터베이스 크기에 따라 크게 달라질 수 있습니다. 이 작업의 진행 상황을 모니터링하려면, 다른 콘솔 세션에서 주기적으로 다음 쿼리를 실행할 수 있습니다. tables_remaining 열은 점진적으로 0에 도달해야 합니다:

sudo gitlab-psql -c "
SELECT
    COUNT(*) AS total_tables,
    SUM(CASE WHEN last_analyze IS NULL OR last_analyze < (NOW() - INTERVAL '2 hours') THEN 1 ELSE 0 END) AS tables_remaining
FROM pg_stat_user_tables;
"

귀하의 GitLab 인스턴스가 올바르게 실행되고 있는지 확인한 후, 이전 데이터베이스 파일을 정리할 수 있습니다:

sudo rm -rf /var/opt/gitlab/postgresql/data.<old_version>
sudo rm -f /var/opt/gitlab/postgresql-version.old

다양한 GitLab 버전과 함께 제공되는 PostgreSQL 버전의 자세한 내용은 Linux 패키지와 함께 제공되는 PostgreSQL 버전에서 확인할 수 있습니다.

자동 PostgreSQL 업그레이드 선택 해제

GitLab 패키지 업그레이드 중 자동 PostgreSQL 업그레이드를 선택 해제하려면 다음을 실행하세요:

sudo touch /etc/gitlab/disable-postgresql-upgrade

패키지된 PostgreSQL 서버를 이전 버전으로 되돌리기

경고: 이 작업은 현재 데이터베이스를 데이터를 포함하여, 마지막 업그레이드 이전 상태로 되돌립니다. 패키지된 PostgreSQL 데이터베이스를 다운그레이드하기 전에 반드시 백업을 생성하세요.

여러 PostgreSQL 버전이 제공되는 GitLab 버전에서는 사용자들이 이미 업그레이드된 PostgreSQL 버전을 이전 버전으로 되돌릴 수 있습니다. 이때는 gitlab-ctl revert-pg-upgrade 명령어를 사용합니다. 이 명령어는 두 개 이상의 PostgreSQL 버전이 패키지에 포함된 경우를 위해 타겟 버전을 지정할 수 있는 -V 플래그도 지원합니다 (예: PostgreSQL 9.6.x, 10.x 및 11.x가 포함된 GitLab 12.8).

PostgreSQL 14의 타겟 버전을 지정하려면:

gitlab-ctl revert-pg-upgrade -V 14

타겟 버전이 지정되지 않으면, 사용 가능한 경우 /var/opt/gitlab/postgresql-version.old의 버전을 사용합니다. 그렇지 않으면 GitLab과 함께 제공된 기본 버전으로 되돌아갑니다.

단일 PostgreSQL 버전만 포함된 다른 GitLab 버전에서는 PostgreSQL 버전을 다운그레이드할 수 없습니다. 이렇게 하려면 GitLab을 이전 버전으로 다운그레이드해야 합니다.

여러 데이터베이스 연결 구성

gitlab:db:decomposition:connection_status Rake 작업은 도입됨 GitLab 15.11에서.

단일 데이터베이스 지원은 GitLab 18.0에서 제거됩니다.

GitLab 16.0에서는 GitLab이 동일한 PostgreSQL 데이터베이스를 가리키는 두 개의 데이터베이스 연결을 기본으로 사용합니다.

GitLab 16.0로 업그레이드하기 전에 PostgreSQL max_connections 설정이 충분히 높아서 사용 가능한 연결의 50% 이상이 사용되지 않도록 나타나야 합니다. 예를 들어, max_connections가 100으로 설정되어 있고 사용 중인 연결이 75개 보인다면, 업그레이드하기 전에 max_connections를 최소 150으로 증가시켜야 합니다. 업그레이드 후 사용 중인 연결이 150으로 두 배가 되기 때문입니다.

다음 Rake 작업을 실행하여 이를 확인할 수 있습니다:

sudo gitlab-rake gitlab:db:decomposition:connection_status

작업 결과가 max_connections가 충분히 높다고 나타나면 업그레이드를 진행할 수 있습니다.

패키지되지 않은 PostgreSQL 데이터베이스 관리 서버 사용하기

기본적으로 GitLab은 리눅스 패키지에 포함된 PostgreSQL 서버를 사용하도록 구성되어 있습니다. 외부 PostgreSQL 인스턴스를 사용하도록 재구성할 수도 있습니다.

경고: 패키지되지 않은 PostgreSQL 서버를 사용하는 경우, PostgreSQL이 데이터베이스 요구 사항 문서 에 따라 설정되었는지 확인해야 합니다.

/etc/gitlab/gitlab.rb를 편집하세요:
```
# 내장 Postgres 비활성화
postgresql['enable'] = false

# database.yml에 대한 연결 세부정보 입력
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'utf8'
gitlab_rails['db_host'] = '127.0.0.1'
gitlab_rails['db_port'] = 5432
gitlab_rails['db_username'] = 'USERNAME'
gitlab_rails['db_password'] = 'PASSWORD'
```
이러한 줄의 시작 부분에 있는 # 주석 문자를 제거하는 것을 잊지 마세요.

주의할 점:
- /etc/gitlab/gitlab.rb는 평문 비밀번호를 포함하고 있어야 하므로 파일 권한이 0600이어야 합니다.
- PostgreSQL은 여러 주소에서 수신을 허용합니다.
  
  gitlab_rails['db_host']에 여러 주소를 쉼표로 구분하여 사용하는 경우, 목록의 첫 번째 주소가 연결에 사용됩니다.
변경 사항이 적용되도록 GitLab 재구성을 수행합니다.
데이터베이스 초기화합니다.

비포장 PostgreSQL을 위한 UNIX 소켓 구성

GitLab과 동일한 시스템에 설치된 시스템의 PostgreSQL 서버를 사용하려는 경우, UNIX 소켓을 사용하여 이를 수행할 수 있습니다:

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

# 내장 Postgres 비활성화
postgresql['enable'] = false

# database.yml의 연결 세부정보를 입력합니다
gitlab_rails['db_adapter'] = 'postgresql'
gitlab_rails['db_encoding'] = 'utf8'
# 소켓이 있는 경로
gitlab_rails['db_host'] = '/var/run/postgresql/'

변경 사항이 적용되도록 GitLab을 재구성합니다:
```
sudo gitlab-ctl-reconfigure
```

SSL 구성

SSL 요구

다음을 /etc/gitlab/gitlab.rb에 추가합니다:
```
gitlab_rails['db_sslmode'] = 'require'
```
구성을 적용하려면 GitLab을 재구성합니다.
변경 사항이 적용되도록 PostgreSQL을 재시작합니다:
```
gitlab-ctl restart postgresql
```
PostgreSQL이 시작되지 않으면 로그(예: /var/log/gitlab/postgresql/current)를 확인하여 자세한 내용을 알아보세요.

SSL 요구 및 CA 번들에 대해 서버 인증서 검증

PostgreSQL은 SSL을 요구하고 CA 번들에 대해 서버 인증서를 검증하도록 구성할 수 있어 스푸핑을 방지할 수 있습니다.

gitlab_rails['db_sslrootcert']에 지정된 CA 번들에는 루트와 중간 인증서가 모두 포함되어야 합니다.

다음을 /etc/gitlab/gitlab.rb에 추가합니다:
```
gitlab_rails['db_sslmode'] = "verify-full"
gitlab_rails['db_sslrootcert'] = "<full_path_to_your_ca-bundle.pem>"
```
Amazon RDS를 PostgreSQL 서버로 사용하는 경우, 결합된 CA 번들을 다운로드하여 gitlab_rails['db_sslrootcert']에 사용해야 합니다. 이와 관련된 더 많은 정보는 AWS의 DB 인스턴스에 대한 연결을 암호화하는 SSL/TLS 사용 기사에서 확인할 수 있습니다.
구성을 적용하려면 GitLab을 재구성합니다.
변경 사항이 적용되도록 PostgreSQL을 재시작합니다:
```
gitlab-ctl restart postgresql
```
PostgreSQL이 시작되지 않으면 로그(예: /var/log/gitlab/postgresql/current)를 확인하여 자세한 내용을 알아보세요.

비포장 PostgreSQL 데이터베이스 백업 및 복원

백업 및 복원 명령을 사용할 때, GitLab은 패키지된 pg_dump 명령을 사용하여 데이터베이스 백업 파일을 생성하고 패키지된 psql 명령을 사용하여 백업을 복원하려고 합니다. 이는 올바른 버전일 때만 작동합니다. 패키지된 pg_dump와 psql의 버전을 확인하세요:

/opt/gitlab/embedded/bin/pg_dump --version
/opt/gitlab/embedded/bin/psql --version

이 버전이 비포장 외부 PostgreSQL과 다르면, 백업 명령을 실행할 때 다음과 같은 오류 출력이 발생할 수 있습니다.

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

이 예제에서는 GitLab 14.1에서 PostgreSQL 버전 13.3을 사용할 때 오류가 발생하며, 이는 기본 제공 PostgreSQL 버전 12.6이 아닙니다.

이 경우, 데이터베이스 버전에 맞는 도구를 설치한 후 아래 단계를 따르세요. PostgreSQL 클라이언트 도구를 설치하는 방법은 여러 가지가 있습니다. https://www.postgresql.org/download/에서 옵션을 확인하세요.

올바른 psql 및 pg_dump 도구가 시스템에 사용 가능해지면, 새로 설치한 도구의 경로를 사용하여 다음 단계를 따르세요:

비포장 버전의 심볼릭 링크를 추가합니다:

ln -s /path/to/new/pg_dump /path/to/new/psql /opt/gitlab/bin/

버전을 체크합니다:
```
/opt/gitlab/bin/pg_dump --version
/opt/gitlab/bin/psql --version
```
이제 이들은 비포장 외부 PostgreSQL과 동일해야 합니다.

이 작업이 완료되면, 다음의 백업 및 복원 명령을 실행하여 백업 및 복원 작업이 올바른 실행 파일을 사용하고 있는지 확인하세요.

비포장 PostgreSQL 데이터베이스 업그레이드

데이터베이스에 연결된 모든 프로세스(Puma, Sidekiq)를 중지한 후 외부 데이터베이스를 업그레이드할 수 있습니다:

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq

업그레이드를 진행하기 전에 다음 사항을 유의하세요:

GitLab 릴리즈와 PostgreSQL 버전 간의 호환성을 확인하세요:
- 최소 PostgreSQL 버전에 대한 요구 사항이 도입된 GitLab 버전에 대해 읽어보세요.
- 리눅스 패키지와 함께 제공된 PostgreSQL 버전에 대한 중요한 변경 사항에 대해 읽어보세요: 리눅스 패키지는 함께 제공된 PostgreSQL의 주요 릴리즈와의 호환성 테스트를 거쳤습니다.
GitLab 백업이나 복원을 사용할 때, 같은 버전의 GitLab을 유지해야 합니다. 이후에 더 높은 GitLab 버전으로 업그레이드할 계획이라면 PostgreSQL을 먼저 업그레이드하세요.
백업 및 복원 명령을 사용하여 데이터베이스를 더 높은 PostgreSQL 버전으로 백업하고 복원할 수 있습니다.
postgresql['version']으로 지정된 PostgreSQL 버전이 해당 리눅스 패키지 릴리즈와 함께 제공되지 않으면, 호환성 표의 기본 버전이 활성화될 클라이언트 바이너리(예: PostgreSQL 백업/복원 바이너리)를 결정합니다.

다음 예시는 PostgreSQL 13을 실행하는 데이터베이스 호스트에서 PostgreSQL 14를 실행하는 다른 데이터베이스 호스트로 업그레이드 하는 과정을 보여줍니다.

데이터베이스 요구 사항에 따라 설정된 새로운 PostgreSQL 14 데이터베이스 서버를 시작하세요.
GitLab Rails 인스턴스에서 호환되는 버전의 pg_dump와 pg_restore를 사용하고 있는지 확인하세요. GitLab 구성을 수정하려면 /etc/gitlab/gitlab.rb를 편집하고 postgresql['version']의 값을 지정하세요:
```
postgresql['version'] = 14
```
GitLab을 재구성하세요:
```
sudo gitlab-ctl reconfigure
```
GitLab을 중지하세요(이 단계는 다운타임을 초래합니다):
```
sudo gitlab-ctl stop
```

경고:

백업 명령은 추가 매개변수가 필요합니다

설치에서 PgBouncer를 사용할 경우.

데이터베이스만 백업하기 위해 SKIP 옵션을 사용하여 백업 Rake 작업을 실행하세요. 백업 파일 이름을 기록해두세요; 나중에 복원할 때 사용할 것입니다.
```
sudo gitlab-backup create SKIP=repositories,uploads,builds,artifacts,lfs,pages,registry
```
PostgreSQL 13 데이터베이스 호스트를 종료하세요.
/etc/gitlab/gitlab.rb를 편집하고 gitlab_rails['db_host'] 설정을 PostgreSQL 데이터베이스 14 호스트를 가리키도록 업데이트하세요.
GitLab을 재구성하세요:
```
sudo gitlab-ctl reconfigure
```
경고: 백업 명령은 추가 매개변수가 필요합니다 설치에서 PgBouncer를 사용할 경우.
이전에 생성된 데이터베이스 백업 파일을 사용하여 데이터베이스를 복원하세요. “이 작업은 authorized_keys 파일을 재구성합니다”라고 질문할 때 아니오라고 대답하세요:
```
# 백업 타임스탬프를 사용하세요 https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html#backup-timestamp
sudo gitlab-backup restore BACKUP=<backup-timestamp>
```
GitLab을 시작하세요:
```
sudo gitlab-ctl start
```
PostgreSQL을 새로운 주요 릴리즈로 업그레이드한 후, 효율적인 쿼리 계획이 선택되도록 테이블 통계를 재구성하고 데이터베이스 서버의 CPU 부하를 줄이세요.

업그레이드가 pg_upgrade를 사용하여 “인플레이스”로 수행되었다면, PostgreSQL 데이터베이스 콘솔에서 다음 쿼리를 실행하세요:
```
SET statement_timeout = 0; ANALYZE VERBOSE;
```
ANALYZE 명령의 실행 시간은 데이터베이스 크기에 따라 상당히 달라질 수 있습니다. 이 작업의 진행 상황을 모니터링하려면, 다른 PostgreSQL 데이터베이스 콘솔에서 주기적으로 다음 쿼리를 실행하세요. tables_remaining 열은 점진적으로 0에 도달해야 합니다:
```
SELECT
  COUNT(*) AS total_tables,
  SUM(CASE WHEN last_analyze IS NULL OR last_analyze < (NOW() - INTERVAL '2 hours') THEN 1 ELSE 0 END) AS tables_remaining
FROM pg_stat_user_tables;
```
업그레이드가 pg_dump 및 pg_restore를 사용한 경우, PostgreSQL 데이터베이스 콘솔에서 다음 쿼리를 실행하세요:
```
SET statement_timeout = 0; VACUUM VERBOSE ANALYZE;
```

데이터베이스 초기화 (신규 설치 전용)

경고:
이 명령은 파괴적인 명령입니다. 기존 데이터베이스에서 실행하지 마십시오.

Linux 패키지 설치는 외부 데이터베이스를 초기화하지 않습니다. 다음 명령을 실행하여 스키마를 가져오고 첫 번째 관리 사용자를 생성하십시오:

# 'git' 사용자라면 'sudo'를 제거하십시오
sudo gitlab-rake gitlab:setup

기본 root 사용자에 대한 비밀번호를 지정하려면, 위의 gitlab:setup 명령을 실행하기 전에 /etc/gitlab/gitlab.rb 파일에 initial_root_password 설정을 지정하십시오:

gitlab_rails['initial_root_password'] = 'nonstandardpassword'

공유 GitLab 러너에 대한 초기 등록 토큰을 지정하려면, /etc/gitlab/gitlab.rb 파일에 initial_shared_runners_registration_token 설정을 위의 gitlab:setup 명령을 실행하기 전에 지정하십시오:

gitlab_rails['initial_shared_runners_registration_token'] = 'token'

패키지된 PostgreSQL 버전 고정 (신규 설치 전용)

Linux 패키지는 다양한 PostgreSQL 버전을 포함하고 있으며, 특별히 지정하지 않으면 기본 버전을 초기화합니다.

기본이 아닌 버전으로 PostgreSQL을 초기화하려면, 초기 재구성 전에 패키지된 PostgreSQL 버전 중 하나의 주 버전으로 postgresql['version']을 설정할 수 있습니다. 예를 들어, GitLab 15.0에서 postgresql['version'] = 12를 사용하여 PostgreSQL 12를 사용할 수 있습니다 (기본 PostgreSQL 13 대신).

경고:
초기 재구성 후 Linux 패키지와 함께 제공되는 PostgreSQL을 사용하는 동안
postgresql['version']을 설정하면 데이터 디렉토리가 다른 PostgreSQL 버전에서 초기화되었다는 오류가 발생할 수 있습니다. 이러한 문제가 발생하면 패키지된 PostgreSQL 서버를 이전 버전으로 되돌리기를 참조하십시오.

GitLab이 이전에 설치된 환경에서 신규 설치를 수행하고
고정된 PostgreSQL 버전을 사용 중이라면, PostgreSQL과 관련된 모든 폴더가 삭제되었는지 확인하고
인스턴스에서 PostgreSQL 프로세스가 실행되고 있지 않은지 확인하십시오.

민감한 데이터 구성을 GitLab Rails에 일반 텍스트 저장 없이 제공

자세한 내용은 구성 문서에서 예제를 참조하십시오.

데이터베이스에 대한 애플리케이션 설정

자동 데이터베이스 마이그레이션 비활성화

여러 GitLab 서버가 데이터베이스를 공유하는 경우, 재구성 중에 마이그레이션 단계를 수행하는 노드를 제한하고 싶을 것입니다.

/etc/gitlab/gitlab.rb 를 편집하여 다음을 추가하십시오:

# 모든 호스트에서 자동 데이터베이스 마이그레이션의 활성화 또는 비활성화
# 지정된 배포 노드를 제외하고
gitlab_rails['auto_migrate'] = false

/etc/gitlab/gitlab.rb는 일반 텍스트 비밀번호가 포함되어 있으므로 파일 권한이 0600이어야 합니다.

위의 구성을 가진 호스트가 다음 번에 재구성될 때, 마이그레이션 단계는 수행되지 않습니다.

스키마 관련 업그레이드 후 오류를 피하려면, 배포 노드 로 표시된 호스트는 업그레이드 중에 gitlab_rails['auto_migrate'] = true를 가져야 합니다.

클라이언트 statement_timeout 설정

Rails가 데이터베이스 트랜잭션이 완료되기를 기다리는 시간 타임아웃 전에 조정할 수 있습니다. 기본적으로 이 설정은 사용되지 않습니다.

/etc/gitlab/gitlab.rb 을 편집하십시오:

gitlab_rails['db_statement_timeout'] = 45000

이 경우, 클라이언트 statement_timeout은 45초로 설정됩니다. 값은 밀리세컨드로 지정됩니다.

연결 시간 초과 설정

Rails가 PostgreSQL 연결 시도를 성공할 때까지 기다리는 시간은 gitlab_rails['db_connect_timeout'] 설정을 사용하여 조정할 수 있습니다.

기본적으로 이 설정은 사용되지 않습니다:

/etc/gitlab/gitlab.rb를 편집합니다:
```
gitlab_rails['db_connect_timeout'] = 5
```
GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

이 경우, 클라이언트 connect_timeout은 5초로 설정됩니다. 값은 초 단위로 지정됩니다. 최소값은 2초입니다. 이를 <= 0으로 설정하거나 아예 설정을 지정하지 않으면 타임아웃이 비활성화됩니다.

TCP 제어 설정

Rails PostgreSQL 어댑터는 성능 향상을 위해 조정할 수 있는 일련의 TCP 연결 제어를 제공합니다. 각 매개변수에 대한 자세한 내용은 PostgreSQL 상위 문서를 참조하세요.

Linux 패키지는 이러한 값에 대한 기본값을 설정하지 않고 대신 PostgreSQL 어댑터가 제공하는 기본값을 사용합니다. 아래 표에 표시된 매개변수를 사용하여 gitlab.rb에서 이를 오버라이드한 다음, gitlab-ctl reconfigure를 실행합니다.

PostgreSQL 매개변수	`gitlab.rb` 매개변수
`keepalives`	`gitlab_rails['db_keepalives']`
`keepalives_idle`	`gitlab_rails['db_keepalives_idle']`
`keepalives_interval`	`gitlab_rails['db_keepalives_interval']`
`keepalives_count`	`gitlab_rails['db_keepalives_count']`
`tcp_user_timeout`	`gitlab_rails['db_tcp_user_timeout']`

자동 데이터베이스 재인덱싱

경고:
이것은 기본적으로 사용할 수 없는 실험적 기능입니다.

백그라운드에서 데이터베이스 인덱스를 재생성합니다(이를 “재인덱싱”이라고 부릅니다). 이는 인덱스에 축적된 부풀어진 공간을 제거하는 데 사용할 수 있으며, 건강하고 효율적인 인덱스를 유지하는 데 도움이 됩니다.

재인덱싱 작업은 정기적으로 크론잡을 통해 시작할 수 있습니다. 크론잡을 구성하려면 gitlab_rails['database_reindexing']['enable']를 true로 설정해야 합니다.

다중 노드 환경에서는 이 기능을 응용 프로그램 호스트에서만 활성화해야 합니다. 재인덱싱 프로세스는 PgBouncer를 경유할 수 없으며, 직접 데이터베이스 연결이 필요합니다.

기본적으로 크론잡은 주말에 매시간 시작됩니다(교통량이 적은 시간일 가능성이 높습니다).

다음 설정을 조정하여 일정을 변경할 수 있습니다:

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

gitlab_rails['database_reindexing']['hour'] = '*'
gitlab_rails['database_reindexing']['minute'] = 0
gitlab_rails['database_reindexing']['month'] = '*'
gitlab_rails['database_reindexing']['day_of_month'] = '*'
gitlab_rails['database_reindexing']['day_of_week'] = '0,6'

GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

HA/Geo 클러스터에 배포된 패키지 PostgreSQL

GitLab HA 클러스터 업그레이드

Patroni 클러스터에서 PostgreSQL 버전을 업그레이드하려면 Patroni 클러스터에서 PostgreSQL 주요 버전 업그레이드를 참조하세요.

GitLab HA Repmgr 클러스터 업그레이드

PostgreSQL 12로 업그레이드하는 경우, 먼저 Repmgr에서 Patroni로 전환해야 합니다. 자세한 내용은 Repmgr에서 Patroni로 전환하기를 참조하세요.

이 지침은 Repmgr를 사용하는 경우 이전 GitLab 클러스터를 PostgreSQL 11로 업그레이드하기 위해 제공됩니다.

PostgreSQL이 고가용성을 위해 구성된 경우,
pg-upgrade는 PostgreSQL을 실행하는 모든 노드에서 실행되어야 합니다. 다른 노드는
건너뛰어도 되지만 데이터베이스 노드와 동일한 GitLab 버전을 실행해야 합니다.

다음 단계를 따라 데이터베이스 노드를 업그레이드하세요:

보조 노드는 주 노드보다 먼저 업그레이드해야 합니다.
1. 보조 노드에서 /etc/gitlab/gitlab.rb를 편집하여 다음을 포함하세요:
```
# X를 DB 노드 수 + 1로 교체합니다.
postgresql['max_replication_slots'] = X
```
2. gitlab-ctl reconfigure를 실행하여 구성을 업데이트하세요.
3. sudo gitlab-ctl restart postgresql를 실행하여 새로운 구성으로 PostgreSQL을 재시작하세요.
4. PostgreSQL 보조 노드에서 pg-upgrade를 실행하면 해당 노드는 클러스터에서 제거됩니다.
5. 모든 보조 노드가 pg-upgrade를 사용하여 업그레이드되면 사용자는
  단일 노드 클러스터만 남게 됩니다. 이 클러스터에는 주 노드만 포함됩니다.
6. 보조 노드에서 pg-upgrade는
  새로운 버전에 맞게 기존 데이터를 업데이트하지 않습니다. 기존 데이터는 주 노드의
  데이터로 대체됩니다. 그러나 기존 데이터는 백업 위치로 이동됩니다.
모든 보조 노드가 업그레이드된 후 주 노드에서 pg-upgrade를 실행하세요.
1. 주 노드에서 /etc/gitlab/gitlab.rb를 편집하여 다음을 포함하세요:
```
# X를 DB 노드 수 + 1로 교체합니다.
postgresql['max_replication_slots'] = X
```
2. gitlab-ctl reconfigure를 실행하여 구성을 업데이트하세요.
3. sudo gitlab-ctl restart postgresql를 실행하여 새로운 구성으로 PostgreSQL을 재시작하세요.
4. 주 노드에서 pg-upgrade는 기존 데이터를 새로운 PostgreSQL 버전에 맞게
  업데이트합니다.
각 보조 노드에서 다음 명령을 실행하여 보조 노드를 다시 생성하세요.
```
gitlab-ctl repmgr standby setup MASTER_NODE_NAME
```
repmgr 클러스터가 원래 상태로 돌아갔는지 확인하세요.
```
gitlab-ctl repmgr cluster show
```

HA 클러스터 업그레이드 문제 해결

업그레이드 전에 번들로 제공되는 PostgreSQL이 노드에서 실행되었다면,
이전 데이터 디렉토리가 남아 있을 수 있습니다. 이는 gitlab-ctl reconfigure가
그 노드에서 사용하는 PostgreSQL 유틸리티의 버전을 다운그레이드하게 합니다.
이 문제를 방지하기 위해 디렉토리를 이동(또는 제거)하세요:

mv /var/opt/gitlab/postgresql/data/ /var/opt/gitlab/postgresql/data.$(date +%s)

gitlab-ctl repmgr standby setup MASTER_NODE_NAME로 보조 노드를 다시 생성할 때
다음 오류가 발생하면 /etc/gitlab/gitlab.rb에 postgresql['max_replication_slots'] = X
(여기서 X는 DB 노드 수 + 1)가 포함되어 있는지 확인하세요:

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는 기본적으로 PostgreSQL 스트리밍 복Replication에 의존하므로 GitLab을 업그레이드할 때 및/또는 PostgreSQL을 업그레이드할 때 추가 고려사항이 있습니다.

PostgreSQL을 Geo와 함께 업그레이드할 때의 주의사항

경고:
Geo를 사용하는 경우 PostgreSQL 업그레이드는 모든 세컨더리의 다운타임을 필요로 합니다.

Geo를 사용하는 경우 PostgreSQL을 업그레이드하려면 모든 세컨더리의 다운타임을 필요로 합니다. 이는 PostgreSQL 복제 설정을 Geo 세컨더리에 다시 초기화해야 하기 때문입니다. 이는 PostgreSQL 스트리밍 복Replication 작동 방식에 따른 것입니다. 복제를 다시 초기화하면 모든 데이터를 다시 기본에서 복사하므로 데이터베이스의 크기와 가용 대역폭에 따라 시간이 오래 걸릴 수 있습니다. 예를 들어, 전송 속도가 30 Mbps이고 데이터베이스 크기가 100 GB인 경우, 재동기화에는 약 8시간이 걸릴 수 있습니다. 자세한 사항은 PostgreSQL 문서를 참조하세요.

Geo를 사용할 때 PostgreSQL을 업그레이드하는 방법

PostgreSQL을 업그레이드하려면 복제 슬롯의 이름과 복제 사용자 암호가 필요합니다.

Geo 기본 데이터베이스 노드에서 기존 복제 슬롯의 이름을 찾으려면 다음을 실행하세요:
```
sudo gitlab-psql -qt -c 'select slot_name from pg_replication_slots'
```
여기에서 slot_name을 찾을 수 없거나 반환된 출력이 없으면 Geo 세컨더리가 건강하지 않을 수 있습니다. 이 경우 세컨더리가 건강하며 복제가 작동하는지 확인하세요.

쿼리가 비어 있더라도 Geo 사이트 관리자 영역에서 찾은 slot_name으로 세컨더리 데이터베이스를 다시 초기화해 볼 수 있습니다.
복제 사용자 암호를 수집하세요. 이는 Geo를 설정할 때 1단계. 기본 사이트 구성 중에 설정되었습니다.
선택 사항. 각 세컨더리 사이트에서 복제를 일시 중지하여 재해 복구(DR) 기능을 보호하세요.
Geo 기본에서 PostgreSQL을 수동으로 업그레이드하세요. Geo 기본 데이터베이스 노드에서 다음을 실행하세요:
```
sudo gitlab-ctl pg-upgrade
```
다음 단계에 착수하기 전에 기본 데이터베이스의 업그레이드가 완료될 때까지 기다리세요. 세컨더리는 백업으로 준비된 상태를 유지할 수 있습니다. 이후에는 세컨더리 데이터베이스와 동시에 추적 데이터베이스를 업그레이드할 수 있습니다.
Geo 세컨더리에서 PostgreSQL을 수동으로 업그레이드하세요. Geo 세컨더리 데이터베이스와 추적 데이터베이스에서 다음을 실행하세요:
```
sudo gitlab-ctl pg-upgrade
```
Geo 세컨더리 데이터베이스에서 데이터베이스 복제를 다음 명령을 사용하여 다시 시작하세요:
```
sudo gitlab-ctl replicate-geo-database --slot-name=SECONDARY_SLOT_NAME --host=PRIMARY_HOST_NAME --sslmode=verify-ca
```
기본의 복제 사용자 암호를 입력하라는 메시지가 표시됩니다. 위의 첫 번째 단계에서 가져온 슬롯 이름으로 SECONDARY_SLOT_NAME을 교체하세요.
GitLab을 재구성하여 Geo 세컨더리 데이터베이스의 pg_hba.conf 파일을 업데이트하세요. 이는 replicate-geo-database가 기본의 파일을 세컨더리로 복제하기 때문에 필요합니다.
3단계에서 복제를 일시 중지한 경우, 각 세컨더리에서 복제를 재개하세요. 그런 다음 puma, sidekiq 및 geo-logcursor를 다시 시작하세요.
```
sudo gitlab-ctl hup puma
sudo gitlab-ctl restart sidekiq
sudo gitlab-ctl restart geo-logcursor
```
https://your_primary_server/admin/geo/nodes로 이동하여 모든 노드가 건강한지 확인하세요.

PostgreSQL 데이터베이스에 연결하기

PostgreSQL 데이터베이스에 연결해야 하는 경우 애플리케이션 사용자로 연결할 수 있습니다:

sudo gitlab-rails dbconsole --database main

문제 해결

`default_transaction_isolation`을 `read committed`로 설정하기

production/sidekiq 로그에서 다음과 유사한 오류가 발생하는 경우:

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

데이터베이스의 default_transaction_isolation 구성이 GitLab 애플리케이션 요구 사항과 일치하지 않을 가능성이 높습니다. PostgreSQL 데이터베이스에 연결하여 SHOW default_transaction_isolation;을 실행하여 이 구성을 확인할 수 있습니다.

GitLab 애플리케이션은 read committed로 구성될 것으로 예상합니다.

이 default_transaction_isolation 구성은 postgresql.conf 파일에 설정됩니다. 구성을 변경한 후에는 데이터베이스를 재시작/재로드해야 합니다. 이 구성은 Linux 패키지에 포함된 패키지 PostgreSQL 서버에서 기본값으로 제공됩니다.

`plpgsql.so` 라이브러리를 로드할 수 없음

데이터베이스 마이그레이션을 실행하거나 PostgreSQL/Patroni 로그에서 다음과 유사한 오류가 발생할 수 있습니다:

ERROR:  could not load library "/opt/gitlab/embedded/postgresql/12/lib/plpgsql.so": /opt/gitlab/embedded/postgresql/12/lib/plpgsql.so: undefined symbol: EnsurePortalSnapshotExists

이 오류는 기본 버전 변경 후 PostgreSQL을 재시작하지 않아서 발생합니다. 이 오류를 수정하려면:

다음 명령 중 하나를 실행합니다:

# PostgreSQL용
sudo gitlab-ctl restart postgresql

# Patroni용
sudo gitlab-ctl restart patroni

# Geo PostgreSQL용
sudo gitlab-ctl restart geo-postgresql

GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

데이터베이스 CPU 부하가 매우 높음

데이터베이스 CPU 부하가 매우 높은 경우 자동 취소 중복 파이프라인 설정 때문일 수 있습니다. 자세한 내용은 이슈 435250을 참조하세요.

이 문제를 해결하려면:

데이터베이스 서버에 더 많은 CPU 리소스를 할당할 수 있습니다.
Sidekiq가 과부하 상태인 경우, 파이프라인 수가 매우 많은 경우 ci_cancel_redundant_pipelines 큐에 대해 더 많은 Sidekiq 프로세스를 추가해야 할 수 있습니다.
disable_cancel_redundant_pipelines_service 기능 플래그를 활성화하여 이 설정을 인스턴스 전체에서 비활성화하고 CPU 부하가 줄어드는지 확인할 수 있습니다. 이 설정은 모든 프로젝트에서 이 기능을 비활성화하며 더 이상 자동으로 취소되지 않는 파이프라인의 리소스 사용량이 증가할 수 있습니다.

데이터베이스 설정

Linux 패키지와 함께 제공되는 PostgreSQL 데이터베이스 서비스 사용

재구성 및 PostgreSQL 재시작

PostgreSQL 버전 변경 시 자동 재시작

SSL 구성

SSL 필요

SSL 비활성화

SSL 사용 여부 확인

SSL 클라이언트 인증 구성

데이터베이스 서버 구성

Rails 클라이언트 구성

패키지된 PostgreSQL 서버를 TCP/IP에서 수신하도록 구성

PostgreSQL 블록 구성

GitLab Rails 블록 구성

적용하고 서비스 재시작하기

PostgreSQL WAL(Write Ahead Log) 아카이빙 활성화하기

PostgreSQL 데이터를 다른 디렉토리에 저장하기

패키지된 PostgreSQL 서버 업그레이드하기

자동 PostgreSQL 업그레이드 선택 해제

패키지된 PostgreSQL 서버를 이전 버전으로 되돌리기

여러 데이터베이스 연결 구성

패키지되지 않은 PostgreSQL 데이터베이스 관리 서버 사용하기

비포장 PostgreSQL을 위한 UNIX 소켓 구성

SSL 구성

SSL 요구

SSL 요구 및 CA 번들에 대해 서버 인증서 검증

비포장 PostgreSQL 데이터베이스 백업 및 복원

비포장 PostgreSQL 데이터베이스 업그레이드

데이터베이스 초기화 (신규 설치 전용)

패키지된 PostgreSQL 버전 고정 (신규 설치 전용)

민감한 데이터 구성을 GitLab Rails에 일반 텍스트 저장 없이 제공

데이터베이스에 대한 애플리케이션 설정

자동 데이터베이스 마이그레이션 비활성화

클라이언트 statement_timeout 설정

연결 시간 초과 설정

TCP 제어 설정

자동 데이터베이스 재인덱싱

HA/Geo 클러스터에 배포된 패키지 PostgreSQL

GitLab HA 클러스터 업그레이드

GitLab HA Repmgr 클러스터 업그레이드

HA 클러스터 업그레이드 문제 해결

Geo 인스턴스 업그레이드

PostgreSQL을 Geo와 함께 업그레이드할 때의 주의사항

Geo를 사용할 때 PostgreSQL을 업그레이드하는 방법

PostgreSQL 데이터베이스에 연결하기

문제 해결

default_transaction_isolation을 read committed로 설정하기

plpgsql.so 라이브러리를 로드할 수 없음

데이터베이스 CPU 부하가 매우 높음

도움말

기능 사용 가능성과 제품 평가판

도움받기

`default_transaction_isolation`을 `read committed`로 설정하기

`plpgsql.so` 라이브러리를 로드할 수 없음