データベース設定

GitLabは、PostgreSQLデータベース管理システムのみをサポートしています。

したがって、Linuxパッケージインストールで使用するデータベースサーバーには、次の2つのオプションがあります:

• Linuxパッケージインストールに含まれる、パッケージ化されたPostgreSQLデータベースサーバーを使用します（設定は不要、推奨）。
• パッケージ化されていないPostgreSQLデータベースサーバーを使用します。

Linuxパッケージに同梱されているPostgreSQLデータベースサービスの使用

再構成およびPostgreSQLの再起動

Linuxパッケージインストールでは通常、そのサービスの設定がgitlab.rbファイルで変更された場合、再構成時にサービスが再起動されます。PostgreSQLは、一部の設定がリロード（HUP）で有効になる一方、PostgreSQLの再起動が必要になる点で独特です。管理者はPostgreSQLが再起動されるタイミングを正確に制御したいことが多いため、Linuxパッケージインストールは、再構成時にPostgreSQLを再起動ではなくリロードするように設定されています。つまり、再起動が必要なPostgreSQLの設定を変更した場合は、再構成後にPostgreSQLを手動で再起動する必要があります。

GitLab設定テンプレートは、PostgreSQLのどの設定に再起動が必要で、どの設定にリロードのみが必要かを識別します。また、データベースに対してクエリを実行して、個々の設定に再起動が必要かどうかを判断することもできます。sudo gitlab-psqlでデータベースコンソールを開始し、次のクエリの<setting name>を変更する設定に置き換えます:

SELECT name,setting FROM pg_settings WHERE context = 'postmaster' AND name = '<setting name>';

設定の変更に再起動が必要な場合、クエリは、実行中のPostgreSQLデータベースインスタンス内の設定の名前と現在の値を返します。

PostgreSQLのバージョン変更時の自動再起動

デフォルトでは、Linuxパッケージインストールは、アップストリームドキュメントで推奨されているように、基盤となるバージョンが変更されると、PostgreSQLを自動的に再起動します。この動作は、postgresqlおよびgeo-postgresqlで使用可能なauto_restart_on_version_change設定を使用して制御できます。

PostgreSQLのバージョン変更時に自動再起動を無効にするには:

1. /etc/gitlab/gitlab.rbを編集し、次の行を追加します:

   # For PostgreSQL/Patroni
   postgresql['auto_restart_on_version_change'] = false
   
   # For Geo PostgreSQL
   geo_postgresql['auto_restart_on_version_change'] = false

2. GitLabを再設定します:

   sudo gitlab-ctl reconfigure

SSLの設定

Linuxパッケージインストールは、PostgreSQLサーバーでSSLを自動的に有効にしますが、デフォルトでは暗号化された接続と暗号化されていない接続の両方を受け入れます。SSLを強制するには、pg_hba.confでhostssl設定を使用する必要があります。詳細については、pg_hba.confドキュメントを参照してください。

SSLサポートは、次のファイルに依存します:

• データベースの公開SSL証明書（server.crt）。
• SSL証明書に対応する秘密キー（server.key）。
• サーバーの証明書を検証するルート証明書バンドル（root.crt）。デフォルトでは、Linuxパッケージインストールは、/opt/gitlab/embedded/ssl/certs/cacert.pemに埋め込まれた証明書バンドルを使用します。これは、自己署名証明書には必要ありません。

10年間の自己署名証明書と秘密キーは、使用するためにLinuxパッケージインストールによって生成されます。CA署名証明書を使用するか、これを独自の自己署名証明書に置き換える場合は、次の手順に従ってください。

これらのファイルの場所は設定可能ですが、秘密キーはgitlab-psqlユーザーが読み取り可能である必要があります。Linuxパッケージインストールはファイルのアクセス許可を管理しますが、パスがカスタマイズされている場合は、gitlab-psqlがファイルが配置されているディレクトリにアクセスできることを確認する必要があります。

詳細については、PostgreSQLドキュメントを参照してください。

server.crtとserver.keyは、GitLabへのアクセスに使用されるデフォルトのSSL証明書とは異なる場合があることに注意してください。たとえば、データベースの外部ホスト名がdatabase.example.comで、外部GitLabホスト名がgitlab.example.comであるとします。*.example.comのワイルドカード証明書か、2つの異なるSSL証明書のいずれかが必要になります。

ssl_cert_file、ssl_key_file、およびssl_ca_fileファイルは、証明書、キー、およびバンドルを検索するためにファイルシステム上のどこにPostgreSQLを指示します。これらの変更はpostgresql.confに適用されます。ディレクティブinternal_certificateとinternal_keyは、これらのファイルの内容を入力するために使用されます。コンテンツは、次の例に示すように、直接追加することも、ファイルからロードすることもできます。

これらのファイルを入手したら、SSLを有効にします:

1. /etc/gitlab/gitlab.rbを編集します:

   postgresql['ssl_cert_file'] = '/custom/path/to/server.crt'
   postgresql['ssl_key_file'] = '/custom/path/to/server.key'
   postgresql['ssl_ca_file'] = '/custom/path/to/bundle.pem'
   postgresql['internal_certificate'] = File.read('/custom/path/to/server.crt')
   postgresql['internal_key'] = File.read('/custom/path/to/server.key')

   相対パスは、PostgreSQLデータベースのデータディレクトリ（デフォルトでは/var/opt/gitlab/postgresql/data）にルート化されます。

2. GitLabを再構成して、設定の変更を適用します。

3. 変更を有効にするには、PostgreSQLを再起動します:

   gitlab-ctl restart postgresql

   PostgreSQLの起動に失敗した場合は、詳細についてログ（たとえば、/var/log/gitlab/postgresql/current）を確認してください。

SSLを要求する

1. 次の内容を/etc/gitlab/gitlab.rbに追加します。

   gitlab_rails['db_sslmode'] = 'require'

2. GitLabを再構成して、設定の変更を適用します。

SSLの無効化

1. 次の内容を/etc/gitlab/gitlab.rbに追加します。

   postgresql['ssl'] = 'off'

2. GitLabを再構成して、設定の変更を適用します。

3. 変更を有効にするには、PostgreSQLを再起動します:

   gitlab-ctl restart postgresql

   PostgreSQLの起動に失敗した場合は、詳細についてログ（たとえば、/var/log/gitlab/postgresql/current）を確認してください。

SSLが使用されていることの検証

クライアントがSSLを使用しているかどうかを判断するには、次を実行します:

sudo gitlab-rails dbconsole --database main

起動時に、次のようなバナーが表示されます:

psql (13.14)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: on)
Type "help" for help.

クライアントがSSLを使用しているかどうかを判断するには、次のSQLクエリを発行します:

SELECT * FROM pg_stat_ssl;

例:

gitlabhq_production=> select * from pg_stat_ssl;
 pid  | ssl | version |         cipher         | bits | compression |  clientdn
------+-----+---------+------------------------+------+-------------+------------
  384 | f   |         |                        |      |             |
  386 | f   |         |                        |      |             |
  998 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
  933 | f   |         |                        |      |             |
 1003 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1016 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1022 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1211 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1214 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1213 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1215 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
 1252 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           |
 1280 | t   | TLSv1.3 | TLS_AES_256_GCM_SHA384 |  256 | f           | /CN=gitlab
  382 | f   |         |                        |      |             |
  381 | f   |         |                        |      |             |
  383 | f   |         |                        |      |             |
(16 rows)

1. ssl列のtにリストされている行が有効になっています。
2. clientdnに値がある行は、cert認証方式を使用しています

SSLクライアント認証の設定

クライアントSSL証明書を使用して、データベースサーバーに対して認証できます。証明書の作成は、omnibus-gitlabのスコープ外です。ただし、既存のSSL証明書管理ソリューションをお持ちのユーザーは、これを使用できます。

データベースサーバーの設定

1. サーバーの証明書とキーを作成します。共通名はサーバーのDNS名と一致する必要があります

2. サーバー証明書、キー、およびCAファイルをPostgreSQLデータベースサーバーにコピーし、アクセス許可が正しいことを確認します

   1. 証明書は、データベースユーザー（デフォルト: gitlab-psql）が所有している必要があります
   2. キーファイルはデータベースユーザーが所有している必要があり、そのアクセス許可は0400である必要があります
   3. CAファイルはデータベースユーザーが所有している必要があり、そのアクセス許可は0400である必要があります
   これらのファイルにファイル名server.crtまたはserver.keyを使用しないでください。これらのファイル名は、omnibus-gitlabの内部使用のために予約されています。

3. 次のものがgitlab.rbに設定されていることを確認します:

   postgresql['ssl_cert_file'] = 'PATH_TO_CERTIFICATE'
   postgresql['ssl_key_file'] = 'PATH_TO_KEY_FILE'
   postgresql['ssl_ca_file'] = 'PATH_TO_CA_FILE'
   postgresql['listen_address'] = 'IP_ADDRESS'
   postgresql['cert_auth_addresses'] = {
     'IP_ADDRESS' => {
       'database' => 'gitlabhq_production',
       'user' => 'gitlab'
     }
   }

   listen_addressを、クライアントがデータベースへの接続に使用するサーバーのIPアドレスとして設定します。cert_auth_addressesに、IPアドレスのリストと、データベースへの接続が許可されているデータベースとユーザーが含まれていることを確認します。cert_auth_addressesのキーを指定するときにCIDR表記を使用して、IPアドレス範囲を組み込むことができます。

4. gitlab-ctl reconfigureを実行し、新しい設定を有効にするにはgitlab-ctl restart postgresqlを実行します。

Railsクライアントの設定

Railsクライアントがサーバーに接続するには、commonNameがgitlabに設定された証明書とキーが必要になります。これは、データベースサーバーのssl_ca_fileで指定されたCAファイルで信頼されている認証局によって署名されています。

1. gitlab.rbを設定します

   gitlab_rails['db_host'] = 'IP_ADDRESS_OR_HOSTNAME_OF_DATABASE_SERVER'
   gitlab_rails['db_sslcert'] = 'PATH_TO_CERTIFICATE_FILE'
   gitlab_rails['db_sslkey'] = 'PATH_TO_KEY_FILE'
   gitlab_rails['db_rootcert'] = 'PATH_TO_CA_FILE'

2. Railsクライアントが新しい設定を使用するようにgitlab-ctl reconfigureを実行します

3. SSLが使用されていることの検証の手順に従って、認証が機能していることを確認します。

TCP/IPでリッスンするようにパッケージ化されたPostgreSQLサーバーを設定する

パッケージ化されたPostgreSQLサーバーは、TCP/IP接続をリッスンするように設定できます。ただし、重要でない一部のスクリプトはUNIXソケットを想定しており、誤動作する可能性があります。

データベースサービスにTCP/IPを使用するように設定するには、gitlab.rbのpostgresqlセクションとgitlab_railsセクションの両方に変更を加えます。

PostgreSQLブロックの設定

次の設定は、postgresqlブロックで影響を受けます:

• listen_address: PostgreSQLがリッスンするアドレスを制御します。
• port: PostgreSQLがリッスンするポートを制御します。デフォルトは5432です。
• md5_auth_cidr_addresses: パスワードによる認証後、サーバーへの接続が許可されるCIDRアドレスブロックのリスト。
• trust_auth_cidr_addresses: あらゆる種類の認証なしで、サーバーへの接続が許可されるCIDRアドレスブロックのリスト。この設定は、GitLab RailsやSidekiqなど、接続を必要とするノードからの接続を許可するようにのみ設定する必要があります。これには、同じノードにデプロイされた場合、またはPostgres Exporter（127.0.0.1/32）などのコンポーネントからのローカル接続が含まれます。
• sql_user: MD5認証に予想されるユーザー名を制御します。これはデフォルトでgitlabになり、必須の設定ではありません。
• sql_user_password: PostgreSQLがMD5認証に受け入れるパスワードを設定します。

1. /etc/gitlab/gitlab.rbを編集します:

   postgresql['listen_address'] = '0.0.0.0'
   postgresql['port'] = 5432
   postgresql['md5_auth_cidr_addresses'] = %w()
   postgresql['trust_auth_cidr_addresses'] = %w(127.0.0.1/24)
   postgresql['sql_user'] = "gitlab"
   
   ##! SQL_USER_PASSWORD_HASH can be generated using the command `gitlab-ctl pg-password-md5 'gitlab'`,
   ##! where 'gitlab' (single-quoted to avoid shell interpolation) is the name of the SQL user that connects to GitLab.
   ##! You will be prompted for a password which other clients will use to authenticate with database, such as `securesqlpassword` in the below section.
   postgresql['sql_user_password'] = "SQL_USER_PASSWORD_HASH"
   
   # force ssl on all connections defined in trust_auth_cidr_addresses and md5_auth_cidr_addresses
   postgresql['hostssl'] = true

2. GitLabを再構成し、PostrgreSQLを再起動します:

   sudo gitlab-ctl reconfigure
   sudo gitlab-ctl restart postgresql

ネットワーク経由で接続するクライアントまたはGitLabサービスは、PostgreSQLサーバーへの接続時に、ユーザー名のsql_userの値と設定に提供されたパスワードを提供する必要があります。また、md5_auth_cidr_addressesに提供されるネットワークブロックに含まれている必要があります

GitLab Railsブロックの設定

ネットワーク経由でPostgreSQLデータベースに接続するようにgitlab-railsアプリケーションを設定するには、いくつかの設定を設定する必要があります:

• db_host: データベースサーバーのIPアドレスに設定する必要があります。これがPostgreSQLサービスと同じインスタンス上にある場合は、127.0.0.1にすることができ、パスワード認証は必要ありません。
• db_port: 接続するPostgreSQLサーバーのポートを設定します。db_hostが設定されている場合は、設定する必要があります。
• db_username: PostgreSQLへの接続に使用するユーザー名を設定します。これはデフォルトでgitlabになります。
• db_password: TCP/IP経由でPostgreSQLに接続する場合、および上記の設定のpostgresql['md5_auth_cidr_addresses']ブロック内のインスタンスから提供する必要があります。これは、127.0.0.1に接続していて、postgresql['trust_auth_cidr_addresses']にそれを含めるように設定している場合は必要ありません。

1. /etc/gitlab/gitlab.rbを編集します:

   gitlab_rails['db_host'] = '127.0.0.1'
   gitlab_rails['db_port'] = 5432
   gitlab_rails['db_username'] = "gitlab"
   gitlab_rails['db_password'] = "securesqlpassword"

2. GitLabを再構成し、PostrgreSQLを再起動します:

   sudo gitlab-ctl reconfigure
   sudo gitlab-ctl restart postgresql

サービスの適用と再起動

以前の変更を加えた後、管理者はgitlab-ctl reconfigureを実行する必要があります。TCPでリッスンしていないサービスに関して問題が発生した場合は、gitlab-ctl restart postgresqlを使用してサービスを直接再起動してみてください。

Linuxパッケージ（gitlab-psqlなど）に含まれる一部のスクリプトは、PostgreSQLへの接続がUNIXソケット経由で処理されることを想定しており、正しく機能しない場合があります。UNIXソケットを無効にせずにTCP/IPを有効にすることができます。

他のクライアントからのアクセスをテストするには、次を実行します:

sudo gitlab-rails dbconsole --database main

PostgreSQLWAL（Write Ahead Log）アーカイブの有効化

デフォルトでは、パッケージ化されたPostgreSQLのWALアーカイブは有効になっていません。WALアーカイブを有効にする場合は、次の点を考慮してください:

• WALレベルは「replica」以上である必要があります（9.6+オプションはminimal、replica、またはlogicalです）
• WALレベルを上げると、通常操作で消費されるストレージの量が増加します

WALアーカイブを有効にするには:

1. /etc/gitlab/gitlab.rbを編集します:

   # Replication settings
   postgresql['sql_replication_user'] = "gitlab_replicator"
   postgresql['wal_level'] = "replica"
       ...
       ...
   # Backup/Archive settings
   postgresql['archive_mode'] = "on"
   postgresql['archive_command'] = "/your/wal/archiver/here"
   postgresql['archive_timeout'] = "60"

2. 変更を有効にするには、GitLabを再設定します。これにより、データベースが再起動されます。

PostgreSQLデータを別のディレクトリに保存する

デフォルトでは、すべて/var/opt/gitlab/postgresqlの下に保存され、postgresql['dir']属性によって制御されます。

内容は次のとおりです:

• データベースソケットは/var/opt/gitlab/postgresql/.s.PGSQL.5432になります。これはpostgresql['unix_socket_directory']によって制御されます。
• gitlab-psqlシステムユーザーには、そのHOMEディレクトリがこれに設定されます。これはpostgresql['home']によって制御されます。
• 実際のデータは/var/opt/gitlab/postgresql/dataに保存されます。

PostgreSQLデータの場所を変更するには

1. 既存のインストールの場合、GitLabを停止します: gitlab-ctl stop。
2. postgresql['dir']を目的の場所に更新します。
3. gitlab-ctl reconfigureを実行します。
4. GitLab gitlab-ctl startを起動します。

パッケージ化されたPostgreSQLサーバーのアップグレード

Linuxパッケージには、gitlab-ctl pg-upgradeコマンドが用意されており、パッケージ化されたPostgreSQLサーバーを（パッケージに含まれている場合）より新しいバージョンに更新します。これにより、特にオプトアウトしない限り、パッケージのアップグレード中にPostgreSQLがデフォルトで出荷されるバージョンに更新されます。

GitLabを新しいバージョンにアップグレードする前に、Linuxパッケージのバージョン固有の変更を参照して、次のいずれかを確認してください:

• データベースのバージョンが変更された場合。
• アップグレードが正当化される場合。

PostgreSQLのバージョンをアップグレードするには、次のことを確認してください:

• 現在のバージョンのPostgreSQLをサポートする最新バージョンのGitLabを実行しています。

• 最近アップグレードした場合は、続行する前にsudo gitlab-ctl reconfigureが正常に実行されていること。

• データベースの2つのコピーに十分なディスク容量がある。十分な空き容量がない場合は、アップグレードを試みないでください。

  • sudo du -sh /var/opt/gitlab/postgresql/data（またはデータベースパスを更新します）を使用して、データベースのサイズを確認します。
  • sudo df -hを使用して使用可能なスペースを確認します。データベースが存在するパーティションに十分なスペースがない場合は、--tmp-dir $DIR引数をコマンドに渡します。アップグレードタスクには、利用可能なディスク容量チェックが含まれており、要件が満たされない場合はアップグレードを中止します。

上記のチェックリストが満たされていることを確認したら、アップグレードに進むことができます:

sudo gitlab-ctl pg-upgrade

特定のPostgreSQLバージョンにアップグレードするには、-Vフラグを使用してバージョンを追加します。たとえば、PostgreSQL 16にアップグレードするには:

sudo gitlab-ctl pg-upgrade -V 16

gitlab-ctl pg-upgradeは、次のステップを実行します:

1. データベースが既知の良好な状態であることを確認します。
2. 十分な空きディスク容量があるかどうかを確認し、ない場合は中止します。--skip-disk-checkフラグを付加すると、これをスキップできます。
3. 既存のデータベースと不要なサービスをすべてシャットダウンし、GitLabがデプロイページをデプロイできるようにします。
4. PostgreSQLの/opt/gitlab/embedded/bin/内のシンボリックリンクを、データベースの新しいバージョンを指すように変更します。
5. 既存のデータベースと一致するロケールを持つ、新しい空のデータベースを含む新しいディレクトリを作成します。
6. pg_upgradeツールを使用して、古いデータベースから新しいデータベースにデータをコピーします。
7. 古いデータベースを移動します。
8. 新しいデータベースを期待される場所に移動します。
9. sudo gitlab-ctl reconfigureを呼び出して、必要な設定変更を行い、新しいデータベースサーバーを起動します。
10. ANALYZEを実行してデータベース統計を生成します。
11. 残りのサービスを開始し、デプロイページを削除します。
12. このプロセス中にエラーが検出された場合は、古いバージョンのデータベースに戻ります。

アップグレードが完了したら、すべてが期待どおりに動作していることを確認してください。

ANALYZEステップの実行中に出力にエラーが発生した場合、データベース統計が生成されるまで、アップグレードは引き続き動作しますが、データベースのパフォーマンスが低下します。gitlab-psqlを使用して、ANALYZEを手動で実行する必要があるかどうかを判断します:

sudo gitlab-psql -c "SELECT relname, last_analyze, last_autoanalyze FROM pg_stat_user_tables WHERE last_analyze IS NULL AND last_autoanalyze IS NULL;"

上記のクエリで行が返された場合は、手動でANALYZEを実行できます:

sudo gitlab-psql -c 'SET statement_timeout = 0; ANALYZE VERBOSE;'

ANALYZEコマンドの実行時間は、データベースのサイズによって大きく異なる場合があります。この操作の進行状況を監視するには、別のコンソールセッションで次のクエリを定期的に実行します。tables_remaining列は徐々に0に達するはずです:

sudo gitlab-psql -c "
SELECT
    COUNT(*) AS total_tables,
    SUM(CASE WHEN last_analyze IS NULL OR last_analyze < (NOW() - INTERVAL '2 hours') THEN 1 ELSE 0 END) AS tables_remaining
FROM pg_stat_user_tables;
"

GitLabインスタンスが正しく実行されていることを確認したら、古いデータベースファイルをクリーンアップできます:

sudo rm -rf /var/opt/gitlab/postgresql/data.<old_version>
sudo rm -f /var/opt/gitlab/postgresql-version.old

さまざまなGitLabバージョンに同梱されているPostgreSQLバージョンの詳細は、Linuxパッケージに同梱されているPostgreSQLバージョンにあります。

PostgreSQLの自動アップグレードをオプトアウト

GitLabパッケージのアップグレード中にPostgreSQLの自動アップグレードをオプトアウトするには、次を実行します:

sudo touch /etc/gitlab/disable-postgresql-upgrade

Dockerイメージを使用している場合は、GITLAB_SKIP_PG_UPGRADE環境変数をtrueに設定すると、自動アップグレードを無効にできます。

パッケージ化されたPostgreSQLサーバーを前のバージョンに戻す

以前のバージョンのLinuxパッケージは、複数のバージョンのPostgreSQLをバンドルしています。これらのバージョンのいずれかを使用している場合は、gitlab-ctl revert-pg-upgradeコマンドを使用して、Linuxパッケージでサポートされている以前のPostgreSQLバージョンにロールバックできます。このコマンドは、ターゲットバージョンを指定するための-Vフラグもサポートしています。たとえば、PostgreSQLバージョン14にロールバックするには、次のようにします:

gitlab-ctl revert-pg-upgrade -V 14

ターゲットバージョンが指定されていない場合、コマンドは利用可能な場合は/var/opt/gitlab/postgresql-version.old内のバージョンを使用します。それ以外の場合は、GitLabに同梱されているデフォルトのバージョンにフォールバックします。

1つのPostgreSQLバージョンのみを同梱するLinuxパッケージのバージョンを使用している場合は、PostgreSQLバージョンをロールバックできません。これらのLinuxパッケージのバージョンでは、以前のPostgreSQLバージョンを使用するには、GitLabを以前のバージョンにロールバックする必要があります。

複数のデータベース接続の設定

GitLab 16.0では、GitLabはデフォルトで、同じPostgreSQLデータベースを指す2つのデータベース接続を使用するようになっています。

GitLab 16.0にアップグレードする前に、使用可能な接続の50%以上が未使用として表示されるように、PostgreSQLのmax_connections設定が十分に高いことを確認してください。たとえば、max_connectionsが100に設定されていて、75個の接続が使用されている場合は、アップグレード後に使用中の接続が2倍の150になるため、アップグレードする前にmax_connectionsを少なくとも150に増やす必要があります。

これは、次のRakeタスクを実行して確認できます:

sudo gitlab-rake gitlab:db:decomposition:connection_status

Rakeタスクでmax_connectionsが十分に高いことが示されている場合は、アップグレードに進むことができます。

パッケージ化されていないPostgreSQLデータベース管理サーバーの使用

デフォルトでは、GitLabはLinuxパッケージに含まれているPostgreSQLサーバーを使用するように設定されています。PostgreSQLの外部インスタンスを使用するように再設定することもできます。

1. /etc/gitlab/gitlab.rbを編集します:

   # Disable the built-in Postgres
   postgresql['enable'] = false
   
   # Fill in the connection details for database.yml
   gitlab_rails['db_adapter'] = 'postgresql'
   gitlab_rails['db_encoding'] = 'utf8'
   gitlab_rails['db_host'] = '127.0.0.1'
   gitlab_rails['db_port'] = 5432
   gitlab_rails['db_username'] = 'USERNAME'
   gitlab_rails['db_password'] = 'PASSWORD'

   これらの行の先頭にある#コメント文字を削除することを忘れないでください。

   注意:

   • /etc/gitlab/gitlab.rbにはプレーンテキストのパスワードが含まれているため、ファイル権限0600が必要です。

   • PostgreSQLでは、複数のアドレスでのリスニングが可能です

     gitlab_rails['db_host']に複数のアドレスをコンマ区切りで使用する場合、リストの最初のアドレスが接続に使用されます。

2. 変更を有効にするには、GitLabを再設定します。

3. データベースのシード。

4. オプション。コンテナレジストリメタデータデータベースを有効にします。

パッケージ化されていないPostgreSQLのUNIXソケット設定

GitLabにバンドルされているものではなく、システムのPostgreSQLサーバー（GitLabと同じシステムにインストールされている）を使用する場合は、UNIXソケットを使用することでこれを行うことができます:

1. /etc/gitlab/gitlab.rbを編集します:

   # Disable the built-in Postgres
   postgresql['enable'] = false
   
   # Fill in the connection details for database.yml
   gitlab_rails['db_adapter'] = 'postgresql'
   gitlab_rails['db_encoding'] = 'utf8'
   # The path where the socket lives
   gitlab_rails['db_host'] = '/var/run/postgresql/'

2. 変更を有効にするには、GitLabを再設定します:

   sudo gitlab-ctl-reconfigure

SSLの設定

SSLを要求する

1. 次の内容を/etc/gitlab/gitlab.rbに追加します。

   gitlab_rails['db_sslmode'] = 'require'

2. GitLabを再構成して、設定の変更を適用します。

CAバンドルに対してSSLを要求し、サーバー証明書を検証します

PostgreSQLは、スプーフィングを防ぐために、SSLを要求し、CAバンドルに対してサーバー証明書を検証するように設定できます。gitlab_rails['db_sslrootcert']で指定されたCAバンドルには、ルート証明書と中間証明書の両方が含まれている必要があります。

1. 次の内容を/etc/gitlab/gitlab.rbに追加します。

   gitlab_rails['db_sslmode'] = "verify-full"
   gitlab_rails['db_sslrootcert'] = "<full_path_to_your_ca-bundle.pem>"

   PostgreSQLサーバーにAmazon RDSを使用している場合は、gitlab_rails['db_sslrootcert']の結合されたCAバンドルをダウンロードして使用してください。これに関する詳細については、AWSのSSL/TLSを使用したDBインスタンスへの接続の暗号化に関する記事をご覧ください。

2. GitLabを再構成して、設定の変更を適用します。

パッケージ化されていないPostgreSQLデータベースのバックアップと復元

バックアップコマンドと復元コマンドを使用すると、GitLabはパッケージ化されたpg_dumpコマンドを使用してデータベースバックアップファイルを作成し、パッケージ化されたpsqlコマンドを使用してバックアップを復元しようとします。これは、それらが正しいバージョンである場合にのみ機能します。パッケージ化されたpg_dumpとpsqlのバージョンを確認します:

/opt/gitlab/embedded/bin/pg_dump --version
/opt/gitlab/embedded/bin/psql --version

これらのバージョンがパッケージ化されていない外部PostgreSQLと異なる場合は、バックアップコマンドを実行しようとすると、次のエラー出力が発生する可能性があります。

Dumping PostgreSQL database gitlabhq_production ... pg_dump: error: server version: 13.3; pg_dump version: 12.6
pg_dump: error: aborting because of server version mismatch

この例では、エラーはGitLab 14.1で、default shipped PostgreSQL versionの12.6ではなくPostgreSQLバージョン13.3を使用している場合に発生します。

この場合、データベースバージョンに一致するツールをインストールし、以下の手順に従う必要があります。PostgreSQLクライアントツールをインストールする方法は複数あります。オプションについては、https://www.postgresql.org/download/を参照してください。

正しいpsqlおよびpg_dumpツールがシステムで使用可能になったら、これらの手順に従い、新しいツールをインストールした場所への正しいパスを使用します:

1. パッケージ化されていないバージョンへのシンボリックリンクを追加します:

   ln -s /path/to/new/pg_dump /path/to/new/psql /opt/gitlab/bin/

2. バージョンを確認します:

   /opt/gitlab/bin/pg_dump --version
   /opt/gitlab/bin/psql --version

   これらは、パッケージ化されていない外部PostgreSQLと同じである必要があります。

この操作が完了したら、バックアップコマンドと復元コマンドの両方を実行して、バックアップと復元のタスクが正しい実行可能ファイルを使用していることを確認します。

パッケージ化されていないPostgreSQLデータベースのアップグレード

データベース（Puma、Sidekiq）に接続されているすべてのプロセスを停止した後、外部データベースをアップグレードできます:

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq

アップグレードに進む前に、以下に注意してください:

• GitLabのリリースとPostgreSQLバージョンの間の互換性を確認してください:
  • 最小PostgreSQLバージョンの要件を導入したGitLabバージョンについて読んでください。
  • Linuxパッケージに同梱されているPostgreSQLバージョンの重要な変更について読んでください: Linuxパッケージは、同梱されているPostgreSQLの主要なリリースとの互換性についてテストされています。
• GitLabのバックアップまたは復元を使用する場合は、同じバージョンのGitLabを維持する必要があります。それ以降のGitLabバージョンにもアップグレードする場合は、最初にPostgreSQLをアップグレードしてください。
• バックアップコマンドと復元コマンドを使用して、データベースをバックアップおよび復元して、それ以降のバージョンのPostgreSQLに復元できます。
• postgresql['version']で指定されたPostgreSQLバージョンがそのLinuxパッケージのリリースに同梱されていない場合、どのクライアントバイナリ（PostgreSQLのバックアップ/復元のバイナリなど）がアクティブであるかを判断する決め手になるのは、互換性テーブル内のデフォルトのバージョンです。

次の例は、PostgreSQL 14を実行しているデータベースホストからPostgreSQL 16を実行している別のデータベースホストにアップグレードし、ダウンタイムが発生することを示しています:

1. データベース要件に従ってセットアップされた、新しいPostgreSQL 16データベースサーバーをスピンアップします。

2. GitLab Railsインスタンスで、互換性のあるpg_dumpおよびpg_restoreのバージョンが使用されていることを確認します。GitLabの設定を修正するには、/etc/gitlab/gitlab.rbを編集し、postgresql['version']の値を指定します:

   postgresql['version'] = 16

3. GitLabを再設定します:

   sudo gitlab-ctl reconfigure

4. GitLabを停止します（この手順によりダウンタイムが発生することに注意してください）:

   sudo gitlab-ctl stop

1. バックアップRakeタスクをSKIPオプションを使用して実行し、データベースのみをバックアップします。バックアップファイル名をメモしておきます。後で復元するために使用します。

   sudo gitlab-backup create SKIP=repositories,uploads,builds,artifacts,lfs,pages,registry

2. PostgreSQL 14データベースホストをシャットダウンします。

3. /etc/gitlab/gitlab.rbを編集し、PostgreSQLデータベース16ホストを指すようにgitlab_rails['db_host']設定を更新します。

4. GitLabを再設定します:

   sudo gitlab-ctl reconfigure

   バックアップコマンドでは、インストールでPgBouncerを使用している場合、追加のパラメータが必要です。

5. 以前に作成したデータベースバックアップファイルを使用してデータベースを復元し、「このタスクでauthorized_keysファイルが再構築されます」と尋ねられたら、必ず0と答えてください:

   # Use the backup timestamp https://docs.gitlab.com/administration/backup_restore/backup_gitlab/#backup-timestamp
   sudo gitlab-backup restore BACKUP=<backup-timestamp>

6. GitLabを起動します:

   sudo gitlab-ctl start

7. PostgreSQLを新しいメジャーリリースにアップグレードした後、テーブル統計を再作成して、効率的なクエリプランが選択されるようにし、データベースサーバーのCPU負荷を軽減します。

   アップグレードがpg_upgradeを使用して「インプレース」で行われた場合は、PostgreSQLデータベースコンソールで次のクエリを実行します:

   SET statement_timeout = 0; ANALYZE VERBOSE;

   ANALYZEコマンドの実行時間は、データベースのサイズによって大きく異なる場合があります。この操作の進行状況を監視するには、別のPostgreSQLデータベースコンソールで次のクエリを定期的に実行します。tables_remaining列は徐々に0に達するはずです:

   SELECT
     COUNT(*) AS total_tables,
     SUM(CASE WHEN last_analyze IS NULL OR last_analyze < (NOW() - INTERVAL '2 hours') THEN 1 ELSE 0 END) AS tables_remaining
   FROM pg_stat_user_tables;

   アップグレードでpg_dumpとpg_restoreが使用された場合は、PostgreSQLデータベースコンソールで次のクエリを実行します:

   SET statement_timeout = 0; VACUUM VERBOSE ANALYZE;

データベースのシード（新規インストールのみ）

Linuxパッケージのインストールでは、外部データベースはシードされません。スキーマをインポートし、最初の管理者エリアユーザーを作成するには、次のコマンドを実行します:

# Remove 'sudo' if you are the 'git' user
sudo gitlab-rake gitlab:setup

デフォルトのrootユーザーのパスワードを指定する場合は、上記のgitlab:setupコマンドを実行する前に、/etc/gitlab/gitlab.rbのinitial_root_password設定を指定します:

gitlab_rails['initial_root_password'] = 'nonstandardpassword'

共有GitLab Runnerの最初の登録トークンを指定する場合は、gitlab:setupコマンドを実行する前に、/etc/gitlab/gitlab.rbのinitial_shared_runners_registration_token設定を指定します:

gitlab_rails['initial_shared_runners_registration_token'] = 'token'

パッケージ化されたPostgreSQLバージョンを固定する（新規インストールのみ）

Linuxパッケージには異なるPostgreSQLバージョンが同梱されており、特に指定がない限り、デフォルトのバージョンが初期化されます。

デフォルト以外のバージョンでPostgreSQLを初期化するには、最初の再設定の前に、postgresql['version']をパッケージ化されたPostgreSQLバージョンのメジャーバージョンの1つに設定します。たとえば、GitLab 17.10では、postgresql['version'] = 14を使用して、デフォルトのPostgreSQL 16ではなく、PostgreSQL 14を使用できます。

以前にGitLabがインストールされていた環境に新規インストールを行っていて、固定されたPostgreSQLバージョンを使用している場合は、まずPostgreSQLに関連するフォルダーがすべて削除されていること、およびインスタンスでPostgreSQLプロセスが実行されていないことを確認してください。

プレーンテキストストレージなしで機密データ設定をGitLab Railsに提供する

詳細については、設定ドキュメントの例を参照してください。

データベースのアプリケーション設定

自動データベース移行の無効化

データベースを共有する複数のGitLabサーバーがある場合は、再設定中に移行ステップを実行するノードの数を制限する必要があります。

/etc/gitlab/gitlab.rbを編集して追加します:

# Enable or disable automatic database migrations
# on all hosts except the designated deploy node
gitlab_rails['auto_migrate'] = false

/etc/gitlab/gitlab.rbにはプレーンテキストのパスワードが含まれているため、ファイル権限0600が必要です。

上記の設定を保持しているホストを次に再設定すると、移行ステップは実行されません。

スキーマ関連のアップグレード後のエラーを回避するには、デプロイノードとしてマークされたホストは、アップグレード中にgitlab_rails['auto_migrate'] = trueを指定する必要があります。

クライアントstatement_timeoutの設定

Railsがタイムアウトする前にデータベーストランザクションが完了するのを待機する時間を、gitlab_rails['db_statement_timeout']設定で調整できるようになりました。デフォルトでは、この設定は使用されません。

/etc/gitlab/gitlab.rbを編集します:

gitlab_rails['db_statement_timeout'] = 45000

この場合、クライアントのstatement_timeoutは45秒に設定されます。値はミリ秒で指定します。

接続タイムアウトの設定

Railsがタイムアウトする前にPostgreSQL接続試行が成功するのを待機する時間を、gitlab_rails['db_connect_timeout']設定で調整できます。デフォルトでは、この設定は使用されません:

1. /etc/gitlab/gitlab.rbを編集します:

   gitlab_rails['db_connect_timeout'] = 5

2. GitLabを再設定します:

   sudo gitlab-ctl reconfigure

この場合、クライアントのconnect_timeoutは5秒に設定されます。値は秒単位で指定されます。最小値2秒が適用されます。これを<= 0に設定するか、設定をまったく指定しないと、タイムアウトが無効になります。

TCP制御の設定

Rails PostgreSQLアダプターは、パフォーマンスを向上させるために調整できる一連のTCP接続制御を提供します。各パラメータの詳細については、PostgreSQLのアップストリームドキュメントを参照してください。

Linuxパッケージは、これらの値にデフォルトを設定せず、代わりにPostgreSQLアダプターによって提供されるデフォルトを使用します。以下の表に記載されているパラメータを使用してgitlab.rb内でオーバーライドし、gitlab-ctl reconfigureを実行します。

データベースの自動インデックス再作成

バックグラウンドでデータベースのインデックスを再作成します（「インデックス再作成」と呼ばれます）。これは、インデックスに蓄積された肥大化したスペースを削除し、健全で効率的なインデックスを維持するのに役立ちます。

インデックス再作成タスクは、cronjobを介して定期的に開始できます。cronジョブを設定するには、gitlab_rails['database_reindexing']['enable']をtrueに設定する必要があります。

マルチノード環境では、この機能フラグはアプリケーションホストでのみ有効にする必要があります。インデックス再作成プロセスはPgBouncerを通過できず、直接データベース接続が必要です。

デフォルトでは、週末（トラフィックが少ない可能性が高い時間帯）のみ、毎時cronジョブを開始します。

スケジュールを変更するには、次の設定を調整します:

1. /etc/gitlab/gitlab.rbを編集します:

   gitlab_rails['database_reindexing']['hour'] = '*'
   gitlab_rails['database_reindexing']['minute'] = 0
   gitlab_rails['database_reindexing']['month'] = '*'
   gitlab_rails['database_reindexing']['day_of_month'] = '*'
   gitlab_rails['database_reindexing']['day_of_week'] = '0,6'

2. GitLabを再設定します:

   sudo gitlab-ctl reconfigure

パッケージ化されたPostgreSQLがHA/Geoクラスターにデプロイされました

GitLab HAクラスターのアップグレード

PatroniクラスターのPostgreSQLのメジャーバージョンをアップグレードするには、PatroniクラスターでのPostgreSQLメジャーバージョンのアップグレードを参照してください。

HAクラスターでのアップグレードのトラブルシューティング

HA設定にアップグレードする前に、バンドルされたPostgreSQLがノードで実行されていた場合、古いデータディレクトリが残っている可能性があります。これにより、gitlab-ctl reconfigureがそのノードで使用するPostgreSQLユーティリティのバージョンをダウングレードする可能性があります。これを防ぐために、ディレクトリを移動（または削除）します:

• mv /var/opt/gitlab/postgresql/data/ /var/opt/gitlab/postgresql/data.$(date +%s)

gitlab-ctl repmgr standby setup MASTER_NODE_NAMEでセカンダリノードを再作成するときに次のエラーが発生した場合は、postgresql['max_replication_slots'] = X（XはDBノードの数+ 1）が/etc/gitlab/gitlab.rbに含まれていることを確認してください:

pg_basebackup: could not create temporary replication slot "pg_basebackup_12345": ERROR:  all replication slots are in use
HINT:  Free one or increase max_replication_slots.

Geoインスタンスのアップグレード

GeoはデフォルトでPostgreSQLストリーミングレプリケーションに依存するため、GitLabをアップグレードするとき、またはPostgreSQLをアップグレードするときは、以下に示すように追加の考慮事項があります。

Geoを使用したPostgreSQLのアップグレード時の注意点

Geoを使用する場合のPostgreSQLのアップグレード方法

PostgreSQLをアップグレードするには、レプリケーションスロットの名前と、レプリケーションユーザーのパスワードが必要です。

1. Geoプライマリデータベースのノードで既存のレプリケーションスロットの名前を検索するには、次を実行します:

   sudo gitlab-psql -qt -c 'select slot_name from pg_replication_slots'

   ここにslot_nameが見つからない場合、または出力が返されない場合、Geoのセカンダリが正常でない可能性があります。その場合は、セカンダリが正常で、レプリケーションが機能していることを確認してください。

   クエリが空の場合でも、Geoサイトの管理者エリアにあるslot_nameを使用して、セカンダリデータベースを再初期化できます。

2. レプリケーションユーザーのパスワードを収集します。これは、ステップ1でGeoを設定するときに設定されました。プライマリサイトを設定。

3. オプション。各セカンダリサイトでのレプリケーションの一時停止ディザスターリカバリー (DR) 機能を保護します。

4. GeoプライマリデータベースでPostgreSQLを手動でアップグレードします。Geoプライマリデータベースのデータベースノードで実行します:

   sudo gitlab-ctl pg-upgrade

   primary databaseがアップグレードを完了するのを待ってから、次の手順を開始してください。セカンダリはバックアップとして準備完了の状態を維持できます。その後、tracking databaseをsecondary databaseと並行してアップグレードできます。

5. GeoセカンダリでPostgreSQLを手動でアップグレードします。Geo secondary databaseとtracking databaseで実行します:

   sudo gitlab-ctl pg-upgrade

6. コマンドを使用して、Geo secondary databaseでデータベースレプリケーションを再開します:

   sudo gitlab-ctl replicate-geo-database --slot-name=SECONDARY_SLOT_NAME --host=PRIMARY_HOST_NAME --sslmode=verify-ca

   プライマリデータベースのレプリケーションユーザーのパスワードを求めるプロンプトが表示されます。上記の最初の手順で取得したスロット名でSECONDARY_SLOT_NAMEを置き換えます。

   この操作のデフォルトのタイムアウトは30分です。タイムアウトを長くする必要がある場合は、--backup-timeoutオプションを設定します。たとえば、--backup-timeout=21600は、最初のレプリケーションを完了するまでに6時間かかります。

7. pg_hba.confファイルをアップグレードするには、Geo secondary databaseでGitLabを再設定します。これは、replicate-geo-databaseがプライマリデータベースのファイルをセカンダリにレプリケートするため必要です。

8. 手順3でレプリケーションを一時停止した場合は、各セカンダリでレプリケーションを再開してください。

9. puma、sidekiq、およびgeo-logcursorを再起動します。

   sudo gitlab-ctl hup puma
   sudo gitlab-ctl restart sidekiq
   sudo gitlab-ctl restart geo-logcursor

10. https://your_primary_server/admin/geo/sitesに移動し、すべてのGeoサイトが正常であることを確認します。

PostgreSQLデータベースへの接続

PostgreSQLデータベースに接続する必要がある場合は、アプリケーションユーザーとして接続できます:

sudo gitlab-rails dbconsole --database main

トラブルシューティング

default_transaction_isolationをread committedに設定する

production/sidekiqログに次のようなエラーが表示される場合:

ActiveRecord::StatementInvalid PG::TRSerializationFailure: ERROR:  could not serialize access due to concurrent update

データベースのdefault_transaction_isolation設定がGitLabアプリケーションの要件に準拠していない可能性があります。PostgreSQLデータベースに接続し、SHOW default_transaction_isolation;を実行して、この設定を確認できます。GitLabアプリケーションはread committedが設定されていることを想定しています。

このdefault_transaction_isolation設定は、postgresql.confファイルで設定されています。設定を変更した後は、データベースを再起動/再読み込むする必要があります。この設定は、Linuxパッケージに含まれているパッケージ化されたPostgreSQLサーバーにデフォルトで付属しています。

ライブラリplpgsql.soを読み込むことができません

データベースの移行を実行中、またはPostgreSQL/Patroniのログに、次のようなエラーが表示される場合があります:

ERROR:  could not load library "/opt/gitlab/embedded/postgresql/12/lib/plpgsql.so": /opt/gitlab/embedded/postgresql/12/lib/plpgsql.so: undefined symbol: EnsurePortalSnapshotExists

このエラーは、基盤となるバージョンが変更された後、PostgreSQLを再起動しなかったために発生します。このエラーを修正するには:

1. 次のいずれかのコマンドを実行します:

   # For PostgreSQL
   sudo gitlab-ctl restart postgresql
   
   # For Patroni
   sudo gitlab-ctl restart patroni
   
   # For Geo PostgreSQL
   sudo gitlab-ctl restart geo-postgresql

2. GitLabを再設定します:

   sudo gitlab-ctl reconfigure

データベースCPU負荷が非常に高い

データベースのCPU負荷が非常に高い場合、自動キャンセル冗長パイプライン設定が原因である可能性があります。詳細については、issue 435250を参照してください。

この問題を解決するには:

• データベースサーバーにより多くのCPUリソースを割り当てることができます。
• Sidekiqがオーバーロードしている場合は、プロジェクトに非常に多数のパイプラインがある場合、ci_cancel_redundant_pipelinesキューにより多くのSidekiqプロセスを追加する必要があるかもしれません。
• disable_cancel_redundant_pipelines_service機能フラグを有効にして、この設定をインスタンス全体で無効にし、CPU負荷が低下するかどうかを確認できます。これにより、すべてのプロジェクトの機能フラグが無効になり、自動的にキャンセルされなくなったパイプラインによるリソースの使用量が増加する可能性があります。

エラー: TypeError: can't quote Array

Amazon RDSを使用している場合、gitlab::database_migrationsタスクの実行中に、TypeError: can't quote Arrayというエラーが表示されることがあります。

この既知の問題を回避するには、PostgreSQLデータベースのRDSでquote_all_identifiersパラメータを無効にします。