PostgreSQL 확장 기능 관리
이 가이드는 외부 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 확장 기능을 설치하려면 다음 절차를 따라야 합니다:
-
슈퍼유저를 사용하여 GitLab PostgreSQL 데이터베이스에 연결합니다. 예:
sudo gitlab-psql -d gitlabhq_production
-
CREATE EXTENSION
을 사용하여 확장 기능을 설치합니다 (이 예시에서는
btree_gist`를 사용합니다):CREATE EXTENSION IF NOT EXISTS btree_gist
-
설치된 확장 기능 확인:
gitlabhq_production=# \dx 설치된 확장 기능 목록 이름 | 버전 | 스키마 | 설명 ------------+---------+------------+------------------------------------------------------------------- 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'에 설치된 PostgreSQL 확장 'btree_gist'가 필요합니다.
데이터베이스 슈퍼유저를 사용하여 확장 기능을 수동으로 설치할 수 있습니다:
CREATE EXTENSION IF NOT EXISTS btree_gist
또는 이 문제를 해결하려면 슈퍼유저로 로그인하여 GitLab 데이터베이스(gitlabhq_production)에서 다음을 실행하면 됩니다:
ALTER regular WITH SUPERUSER
이 쿼리를 실행하면 사용자에게 슈퍼유저 권한이 부여되어 어떤 데이터베이스 확장이나 마이그레이션을 통해 설치할 수 있게 됩니다.
마이그레이션 실패로부터 복구하려면 확장 기능을 슈퍼유저에 의해 수동으로 설치하고, GitLab 업그레이드를 완료하기 위해 데이터베이스 마이그레이션을 다시 실행해야 합니다:
sudo gitlab-rake db:migrate