이 가이드는 외부 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
    ------------+---------+------------+-------------------------------------------------------------------
    amcheck    | 1.3     | public     | functions for verifying relation integrity
    btree_gist | 1.5     | public     | support for indexing common datatypes in GiST
    pg_trgm    | 1.4     | public     | text similarity measurement and index searching based on trigrams
    plpgsql    | 1.0     | pg_catalog | PL/pgSQL procedural language
    (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 requires the PostgreSQL extension 'btree_gist' installed in database 'gitlabhq_production', but
the database user is not allowed to install the extension.

You can either install the extension manually using a database superuser:

  CREATE EXTENSION IF NOT EXISTS btree_gist

Or, you can solve this by logging in to the GitLab database (gitlabhq_production) using a superuser and running:

    ALTER regular WITH SUPERUSER

This query will grant the user superuser permissions, ensuring any database extensions
can be installed through migrations.

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

sudo gitlab-rake db:migrate