0. 前提条件の確認

構成: Docker + Linuxパッケージ(Omnibus)内蔵DB
コンテナ名: コンテナ名
空き容量: / (DBディレクトリ) に現在のDBサイズ以上の空きがあること（目安: 1.5GB以上）

1. 事前バックアップ（重要）

作業前に必ず設定とデータの両方をバックアップし、ホストOS外にコピーしてください。

# 設定ファイルのバックアップ (デフォルト: /etc/gitlab/config_backup/)
docker exec -it コンテナ名 gitlab-ctl backup-etc

# アプリケーションデータのバックアップ (デフォルト: /var/opt/gitlab/backups/)
docker exec -it コンテナ名 gitlab-rake gitlab:backup:create

2. Maintenance Mode の有効化

ユーザーの書き込み操作・新規ログインをブロックし、安全にメンテナンスを開始します。

注意: 既存のログインセッションは維持されます。実行中のCIジョブは完了まで継続します。

Maintenance Mode を有効化する

docker exec -it コンテナ名 gitlab-rails console

コンソール内で以下を実行:

::Gitlab::CurrentSettings.update!(
  maintenance_mode: true,
  maintenance_mode_message: "現在メンテナンス中です。作業完了までしばらくお待ちください。"
)
exit

実行中のジョブ・マージ処理の完了待ち

Maintenance Mode 有効化後、進行中の処理が完了するまで待機します。

# Sidekiq キューが空になったことを確認（処理中ジョブが 0 になるまで待つ）
docker exec -it コンテナ名 gitlab-ctl status sidekiq

Admin Area からも確認できます:
Admin Area > Monitoring > Background Jobs (Sidekiq) → Busy（実行中）と Enqueued（待機中）が両方 0 であること

3. PostgreSQL 17 へのアップグレード

データベースのメジャーバージョンを 17 に更新します。実行中、GitLab サービスは停止します。

# アップグレードコマンドの実行
docker exec -it コンテナ名 gitlab-ctl pg-upgrade -V 17

完了確認

# バージョンが 17.8 等になっているか確認
docker exec -it コンテナ名 /opt/gitlab/embedded/bin/psql --version

# 全サービスが run 状態か確認
docker exec -it コンテナ名 gitlab-ctl status

DB統計情報の再生成

pg-upgrade はデータ統計情報を引き継がないため、アップグレード後に再生成します。
DBサイズによっては数分〜十数分かかります。サービスを上げる前に実施してください。

docker exec -it コンテナ名 gitlab-psql \
  -d gitlabhq_production \
  -c "ANALYZE VERBOSE;"

DBメンテナンス（VACUUM ANALYZE）

デッド行の回収と統計情報の更新を同時に行います。ANALYZE完了後に実施してください。

docker exec -it コンテナ名 gitlab-psql \
  -d gitlabhq_production \
  -c "VACUUM ANALYZE;" >> /var/log/gitlab-vacuum.log 2>&1

4. 不要な旧DBデータの削除

アップグレード成功後、ディスク容量を解放するために古いデータディレクトリを削除します。

# 旧バージョンデータの削除
docker exec -it コンテナ名 rm -rf /var/opt/gitlab/postgresql/data.16
docker exec -it コンテナ名 rm -f /var/opt/gitlab/postgresql-version.old

5. バックグラウンドマイグレーションの正常化

19.0 への更新前に、すべてのマイグレーションを Finished にする必要があります。

失敗ジョブの確認

Admin Area > Monitoring > Background Migrations を確認。
ステータスが Failed になっているジョブがないか確認。

失敗ジョブの手動完了処理 (Rails Console)

BackfillUserDetailsFields など、クラスが見つからないエラーで失敗している場合に実施します。★こちらは、作業状態にあわせて適宜実施して下さい。★

# Railsコンソールの起動
docker exec -it コンテナ名 gitlab-rails console

コンソール内で以下のコードを順次実行:

# 1. 対象の特定
m = Gitlab::Database::BackgroundMigration::BatchedMigration.find_by(job_class_name: 'BackfillUserDetailsFields')

if m
  # 2. 未完了の子ジョブをすべて成功(3)に書き換え
  m.batched_jobs.where.not(status: 3).update_all(status: 3)
  
  # 3. 親ジョブを成功(3)に書き換え
  m.update!(status: 3)
  
  puts "Successfully marked 'BackfillUserDetailsFields' as Finished."
end

# 4. 終了
exit

6. Maintenance Mode の無効化

すべての作業完了後、Maintenance Mode を解除してサービスを通常状態に戻します。

docker exec -it コンテナ名 gitlab-rails console

コンソール内で以下を実行:

::Gitlab::CurrentSettings.update!(maintenance_mode: false)
exit

7. 最終確認

Maintenance Mode が無効化されていること。
サービスが正常に動作し、ブラウザからアクセス可能か。
Admin Area で Background Migrations の Failed が 0 であること。