PostgreSQL 확장 기능 관리

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

이 가이드는 외부 PostgreSQL 데이터베이스를 사용하는 설치에 대한 PostgreSQL 확장 기능을 관리하는 방법을 문서화합니다.

다음 확장 기능을 기본 GitLab 데이터베이스(defaults to gitlabhq_production)에 로드해야 합니다.

확장 기능 최소 GitLab 버전
pg_trgm 8.6
btree_gist 13.1
plpgsql 11.7

만약 GitLab Geo를 사용 중이라면, 모든 보조 추적 데이터베이스(defaults to gitlabhq_geo_production)에 다음 확장 기능을 로드해야 합니다.

확장 기능 최소 GitLab 버전
plpgsql 9.0

확장 기능을 설치하려면, PostgreSQL은 사용자가 슈퍼유저 권한을 가지고 있어야 합니다. 일반적으로 GitLab 데이터베이스 사용자는 슈퍼유저가 아닙니다. 따라서, 일반 데이터베이스 마이그레이션은 확장 기능을 설치하는 데 사용할 수 없으며, 대신 확장 기능은 GitLab을 더 높은 버전으로 업그레이드하기 전에 수동으로 설치해야 합니다.

PostgreSQL 확장 기능 수동 설치

PostgreSQL 확장 기능을 설치하려면 다음 절차에 따라야 합니다.

  1. 예를 들어, 다음과 같이 슈퍼유저를 사용하여 GitLab PostgreSQL 데이터베이스에 연결합니다. 

    sudo gitlab-psql -d gitlabhq_production

  2. 다음 [CREATE EXTENSION](https://www.postgresql.org/docs/11/sql-createextension.html)을 사용하여 확장 기능(btree_gist 예제)을 설치합니다. 

    CREATE EXTENSION IF NOT EXISTS btree_gist

  3. 설치된 확장 기능을 확인합니다. 

     gitlabhq_production=# \dx
                                     설치된 확장 기능 목록
     Name    | Version |   Schema   |                            설명
 ------------+---------+------------+-------------------------------------------------------------------
 btree_gist | 1.5     | public     | 일반적 데이터 타입을 GiST에 인덱싱하는 지원
 pg_trgm    | 1.4     | public     | 3-gram을 기반으로 한 텍스트 유사성 측정 및 인덱스 검색
 plpgsql    | 1.0     | pg_catalog | PL/pgSQL 절차형 언어
 (3 rows)

일부 시스템에서는 특정 확장 기능을 사용하려면 추가 패키지(예: postgresql-contrib)를 설치해야 할 수 있습니다.

일반적인 실패 시나리오

다음은 확장 기능이 먼저 설치되지 않아 새로운 GitLab 설치에서 실패하는 예제입니다. 

---- Begin output of "bash"  "/tmp/chef-script20210513-52940-d9b1gs" ----
STDOUT: psql:/opt/gitlab/embedded/service/gitlab-rails/db/structure.sql:9: ERROR:  permission denied to create extension "btree_gist"
HINT:  Must be superuser to create this extension.
rake aborted!
failed to execute:
psql -v ON_ERROR_STOP=1 -q -X -f /opt/gitlab/embedded/service/gitlab-rails/db/structure.sql --single-transaction gitlabhq_production

다음은 마이그레이션을 실행하기 전에 확장 기능이 설치되지 않은 상황의 예제입니다. 이 시나리오에서는 데이터베이스 마이그레이션에 필요한 권한 부족으로 확장기능 ‘btree_gist’를 생성하지 못해 실패합니다. 

== 20200515152649 EnableBtreeGistExtension: 마이그레이션 실행 중 =========================
-- execute("CREATE EXTENSION IF NOT EXISTS btree_gist")

GitLab은 데이터베이스 사용자가 확장 기능 'btree_gist'를 설치할 수 없지만 'gitlabhq_production' 데이터베이스에 설치되어야 하는 경우 에러가 발생합니다.

데이터베이스 슈퍼유저로 로그인하여 다음을 실행하여 이 문제를 해결할 수 있습니다.

    ALTER regular WITH SUPERUSER

이 쿼리를 실행하면 사용자에게 슈퍼유저 권한이 부여되어 데이터베이스 확장 기능이 마이그레이션을 통해 설치될 수 있습니다.

마이그레이션 실패에서 복구하려면, 슈퍼유저에 의해 확장 기능을 수동으로 설치하고, GitLab 업그레이드를 완료하기 위해 데이터베이스 마이그레이션을 다시 실행해야 합니다. 

sudo gitlab-rake db:migrate