• PostgreSQL 확장을 수동으로 설치하기
• 일반적인 실패 시나리오

PostgreSQL 확장 관리

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

다음 확장을 기본 GitLab 데이터베이스(gitlabhq_production 기본값)에 로드해야 합니다:

GitLab Geo를 사용하는 경우, 모든 보조 추적 데이터베이스(gitlabhq_geo_production 기본값)에 다음 확장을 로드해야 합니다:

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

PostgreSQL 확장을 수동으로 설치하기

PostgreSQL 확장을 설치하려면 다음 절차를 따라야 합니다:

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

   sudo gitlab-psql -d gitlabhq_production
   

2. CREATE EXTENSION을 사용하여 확장(btree_gist의 경우) 설치합니다:

   CREATE EXTENSION IF NOT EXISTS btree_gist
   

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

    gitlabhq_production=# \dx
                                        List of installed extensions
        Name    | Version |   Schema   |                            Description
    ------------+---------+------------+-------------------------------------------------------------------
    btree_gist | 1.5     | public     | GiST에서 일반 데이터 유형의 인덱싱 지원
    pg_trgm    | 1.4     | public     | 삼그램 기반 텍스트 유사도 측정 및 인덱스 검색
    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: migrating =========================
-- execute("CREATE EXTENSION IF NOT EXISTS btree_gist")

GitLab은 데이터베이스 'gitlabhq_production'에 'btree_gist' PostgreSQL 확장이 설치되어야 하지만, 데이터베이스 사용자가 확장을 설치할 수 있는 권한이 없습니다.

다음과 같이 데이터베이스 슈퍼유저를 사용하여 확장을 수동으로 설치할 수 있습니다:

  CREATE EXTENSION IF NOT EXISTS btree_gist

또는, 다음 쿼리를 실행하여 GitLab 데이터베이스(gitlabhq_production)에 슈퍼유저로 로그인하여 해결할 수 있습니다:

    ALTER regular WITH SUPERUSER

이 쿼리는 사용자에게 슈퍼유저 권한을 부여하여 마이그레이션을 통해 데이터베이스 확장을 설치할 수 있도록 합니다.

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

sudo gitlab-rake db:migrate