PostgreSQL拡張機能を管理する

このドキュメントでは、外部PostgreSQLデータベースを使用するインストール環境向けのPostgreSQL拡張機能を管理する方法について説明します。

次の拡張機能をメインのGitLabデータベース（gitlabhq_productionがデフォルト）に読み込む必要があります:

GitLabを使用している場合は、次の拡張機能をすべてのセカンダリ追跡データベース（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