アップグレードする前に移行を確認する

GitLabをアップグレードする前に、既存のすべてのバックグラウンド移行が完了していることを確認する必要があります。

保留中のデータベースバックグラウンド移行を確認する

データベーステーブルをバッチで更新するために、GitLabはバッチバックグラウンド移行を使用できます。これらの移行はGitLabのデベロッパーにより作成され、アップグレード時に自動的に実行されます。ただし、このような移行は、テーブルの整数オーバーフローを防ぐために一部のintegerデータベース列をbigintに移行するなど、用途が限られています。

バッチバックグラウンド移行はSidekiqによって処理され、独立して実行されるため、移行の処理中もインスタンスは動作し続けることができます。ただし、大規模なインスタンスで負荷が高い場合、バッチバックグラウンド移行の実行中にパフォーマンスが低下する可能性があります。すべての移行が完了するまで、Sidekiqのステータスを注意深くモニタリングする必要があります。

これらの移行を完了するために必要な時間を短縮するには、background_migrationキューでジョブを処理できるSidekiqワーカーの数を増やします。

バッチバックグラウンド移行のステータスを確認する

GitLab UIで、またはデータベースに直接クエリを実行することで、バッチバックグラウンド移行のステータスを確認できます。GitLabをアップグレードする前に、すべての移行がFinishedステータスになっている必要があります。

移行が完了していない状態でGitLabをアップグレードしようとすると、次のエラーが表示されることがあります:

Expected batched background migration for the given configuration to be marked
as 'finished', but it is 'active':

このエラーが発生した場合は、GitLabのアップグレードに必要なバッチバックグラウンド移行を完了させる方法について、オプションを確認してください。

GitLab UIから

前提要件:

• インスタンスへの管理者アクセス権が必要です。

バッチバックグラウンド移行のステータスを確認するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. モニタリング > バックグラウンド移行を選択します。
3. 待機中または完了中を選択すると未完了の移行を確認できます。失敗を選択すると失敗した移行を確認できます。

データベースから

前提要件:

• インスタンスへの管理者アクセス権が必要です。

データベースに直接クエリを実行して、バッチバックグラウンド移行のステータスを確認するには:

1. インスタンスのインストール方法の説明に従って、psqlプロンプトにサインインします。たとえば、Linuxパッケージインストールの場合は、sudo gitlab-psqlを使用します。

2. 未完了のバッチバックグラウンド移行の詳細を確認するには、psqlセッションで次のクエリを実行します:

   SELECT
     job_class_name,
     table_name,
     column_name,
     job_arguments
   FROM batched_background_migrations
   WHERE status NOT IN(3, 6);

または、gitlab-psql -c "<QUERY>"でクエリをラップして、バッチバックグラウンド移行のステータスを確認することもできます:

gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"

クエリの結果がゼロ行の場合、すべてのバッチバックグラウンド移行が完了しています。

高度な機能を有効または無効にする

バッチバックグラウンド移行は、移行をカスタマイズしたり、完全に一時停止したりできる機能フラグを提供します。これらの機能フラグは、無効にするリスクを理解している上級ユーザーのみが無効にするようにしてください。

バッチバックグラウンド移行を一時停止する

進行中のバッチバックグラウンド移行を一時停止するには、バッチバックグラウンド移行機能を無効にします。この機能を無効にすると、現在の移行のバッチが完了した後、機能が再び有効にされるまで次のバッチは開始されません。

前提要件:

• インスタンスへの管理者アクセス権が必要です。

現在のバッチバックグラウンド移行の状態を確認するには、次のデータベースクエリを使用します:

1. 実行中の移行のIDを取得します:

   SELECT
    id,
    job_class_name,
    table_name,
    column_name,
    job_arguments
   FROM batched_background_migrations
   WHERE status NOT IN(3, 6);

2. XXを前の手順で取得したIDに置き換えて次のクエリを実行し、移行のステータスを確認します:

   SELECT
    started_at,
    finished_at,
    finished_at - started_at AS duration,
    min_value,
    max_value,
    batch_size,
    sub_batch_size
   FROM batched_background_migration_jobs
   WHERE batched_background_migration_id = XX
   ORDER BY id DESC
   limit 10;

3. 数分以内にクエリを複数回実行して、新しい行が追加されていないことを確認します。新しい行が追加されていない場合、移行は一時停止されています。

4. 移行が一時停止されたことを確認したら、（上記のenableコマンドを使用して）移行を再開し、バッチを続行します。大規模なインスタンスでは、バックグラウンド移行の各バッチを完了するまでに最大48時間かかることがあります。

バッチサイズの自動最適化

バッチバックグラウンド移行のスループット（時間単位で更新されるタプル数）を最大化するために、バッチサイズは、以前のバッチの完了までにかかった時間に基づいて自動的に調整されます。

並列実行

バッチバックグラウンド移行の実行を高速化するために、2つの移行が同時に実行されます。

GitLab Railsコンソールへのアクセス権を持つGitLab管理者は、並列実行されるバッチバックグラウンド移行の数を変更できます:

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

失敗したバッチバックグラウンド移行を解決する

バッチバックグラウンド移行が失敗した場合は、修正して再試行してください。それでもなおエラーが発生して移行が失敗する場合は、次のいずれかの操作を行います:

• 失敗した移行を手動で完了する
• 失敗した移行を完了済みとしてマークする

移行を修正して再試行する

GitLabの新しいバージョンにアップグレードするには、失敗したバッチバックグラウンド移行をすべて解決する必要があります。バッチバックグラウンド移行のステータスを確認すると、失敗タブに一部の移行が失敗ステータスで表示される場合があります:

バッチバックグラウンド移行が失敗した理由を特定するには、失敗のエラーログを確認するか、UIでエラー情報を確認します。

前提要件:

• インスタンスへの管理者アクセス権が必要です。

1. 左側のサイドバーの下部で、管理者を選択します。
2. モニタリング > バックグラウンド移行を選択します。
3. 失敗タブを選択します。これにより、失敗したバッチバックグラウンド移行のリストが表示されます。
4. 失敗したマイグレーションを選択して、移行パラメータと失敗したジョブを確認します。
5. 失敗したジョブで、各IDを選択して、ジョブが失敗した理由を確認します。

GitLabのお客様は、バッチバックグラウンド移行が失敗した理由をデバッグするために、サポートリクエストを開くことを検討してください。

問題を修正するために、失敗した移行を再試行できます。

前提要件:

• インスタンスへの管理者アクセス権が必要です。

1. 左側のサイドバーの下部で、管理者を選択します。
2. モニタリング > バックグラウンド移行を選択します。
3. 失敗タブを選択します。これにより、失敗したバッチバックグラウンド移行のリストが表示されます。
4. 失敗したバッチバックグラウンド移行を選択して再試行するには、再試行ボタン（ ）をクリックします。

再試行したバッチバックグラウンド移行をモニタリングするには、定期的にバッチバックグラウンド移行のステータスを確認します。

失敗した移行を手動で完了する

エラーで失敗したバッチバックグラウンド移行を手動で完了するには、失敗のエラーログまたはデータベースの情報を使用します:

sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,ci_builds,id,'[["id"\, "stage_id"]\,["id_convert_to_bigint"\,"stage_id_convert_to_bigint"]]']

失敗した移行を完了済みとしてマークする

多数のバージョンアップグレードをスキップしたり、下位互換性のないデータベーススキーマの変更を行ったりすると、バックグラウンド移行が失敗する場合があります（例については、イシュー393216を参照してください）。バックグラウンド移行に失敗すると、それ以降のアプリケーションのアップグレードを妨げる場合があります。

バックグラウンド移行がスキップしても「安全」であると判断された場合、移行を手動で完了済みとしてマークできます:

# Start the rails console

connection = ApplicationRecord.connection # or Ci::ApplicationRecord.connection, depending on which DB was the migration scheduled

Gitlab::Database::SharedModel.using_connection(connection) do
  migration = Gitlab::Database::BackgroundMigration::BatchedMigration.find_for_configuration(
    Gitlab::Database.gitlab_schemas_for_connection(connection),
    'BackfillUserDetailsFields',
    :users,
    :id,
    []
  )

  # mark all jobs completed
  migration.batched_jobs.update_all(status: Gitlab::Database::BackgroundMigration::BatchedJob.state_machine.states['succeeded'].value)
  migration.update_attribute(:status, Gitlab::Database::BackgroundMigration::BatchedMigration.state_machine.states[:finished].value)
end

すべてのバックグラウンド移行を同期的に実行する

メンテナンス期間中に、バックグラウンド移行をフォアグラウンドで強制的に実行したい場合があります。

このスクリプトは、すべての移行が完了する前にタイムアウトまたは終了する可能性があります。すべての移行が完了するまで、再度実行できます。

# Start the rails console

databases = ActiveRecord::Tasks::DatabaseTasks.setup_initial_database_yaml

Gitlab::Database.database_base_models.each do |database_name, model|
  Gitlab::Database::SharedModel.using_connection(model.connection) do
    Gitlab::Database::BackgroundMigration::BatchedMigration.with_status([:paused, :active]).find_each(batch_size: 100) do |migration|
      puts "#{database_name}: Finalizing migration #{migration.job_class_name} (ID: #{migration.id})... "
      Gitlab::Database::BackgroundMigration::BatchedMigrationRunner.finalize(
        migration.job_class_name,
        migration.table_name,
        migration.column_name,
        Gitlab::Json.parse(migration.job_arguments),
        connection: model.connection
      )
      puts("done!\n")
    end
  end
end

バッチバックグラウンド移行ログを表示する

バッチバックグラウンド移行のトラブルシューティングを行う場合、複数の場所で詳細な実行ログを確認できます。

Sidekiqログ

Sidekiqログには、Database::BatchedBackgroundMigrationWorkerジョブがいつ実行されたかが表示されます。これらのログでジョブの実行状況がわかりますが、どの特定の移行が実行されているかは識別できません。

アプリケーションログ

どのバッチバックグラウンド移行が実行されているかを特定するには、アプリケーションログを確認します。アプリケーションログには、次の詳細情報が含まれています:

• 特定のバッチバックグラウンド移行のクラス名（job_class_name）
• ステータスの遷移（保留中、実行中、成功、失敗）

移行の実行をトレースする

特定のバッチバックグラウンド移行をトレースするには、次の手順に従います:

1. Database::BatchedBackgroundMigrationWorkerのSidekiqログエントリでcorrelation_idを見つけます。
2. そのcorrelation_idでアプリケーションログを検索し、詳細なステータスの遷移を確認します。

アプリケーションログエントリの例:

{
  "severity": "INFO",
  "time": "2025-08-27T22:52:07.806Z",
  "meta.caller_id": "Database::BatchedBackgroundMigration::MainExecutionWorker",
  "correlation_id": "74d0295cbe4bb6147230a7d481fb0f8a",
  "message": "BatchedJob transition",
  "batched_job_id": 725,
  "previous_state": "pending",
  "new_state": "running",
  "batched_migration_id": 638,
  "job_class_name": "BackfillSentNotificationsAfterPartition",
  "job_arguments": []
},
{
  "severity": "INFO",
  "time": "2025-08-27T22:52:14.293Z",
  "meta.caller_id": "Database::BatchedBackgroundMigration::MainExecutionWorker",
  "correlation_id": "74d0295cbe4bb6147230a7d481fb0f8a",
  "message": "BatchedJob transition",
  "batched_job_id": 725,
  "previous_state": "running",
  "new_state": "succeeded",
  "batched_migration_id": 638,
  "job_class_name": "BackfillSentNotificationsAfterPartition",
  "job_arguments": []
}

保留中の高度な検索の移行を確認する

このセクションは、Elasticsearchのインテグレーションを有効にしている場合にのみ適用されます。メジャーリリースでは、メジャーバージョンのアップグレード前に、現在のバージョンで最新のマイナーリリースからすべての高度な検索の移行を完了する必要があります。保留中の移行を見つけるには、次のコマンドを実行します。

sudo gitlab-rake gitlab:elastic:list_pending_migrations

cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations

アップグレードパスが長く、保留中の移行が多い場合は、インデックス作成ワーカーをキューに再度追加と非コードインデックス作成のシャード数を設定して、インデックス作成を高速化することをおすすめします。もう1つのオプションは、保留中の移行を無視し、GitLabをターゲットバージョンにアップグレードした後でインスタンスのインデックスを再作成することです。この処理中は、高度な検索で検索設定で高度な検索を無効にすることもできます。