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

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

Rakeタスクでバックグラウンド移行を管理する

GitLabは、コマンドラインからバックグラウンド移行を管理するためのRakeタスクのセットを提供しています。これらのタスクは、Admin UIが利用できない場合（ダウンタイム中のアップグレードやメンテナンス期間中など）に、バックグラウンド移行を管理する必要があるセルフマネージドの管理者にとって特に役立ちます。

すべてのRakeタスクは、すべてのデータベース (mainとci) で機能し、統一された移行ID形式{database}_{id}を使用します。たとえば、main_85はmainデータベースの移行ID 85を指し、ci_10はciデータベースの移行ID 10を指します。

アクティブな移行の場合、progress列には、利用可能な場合に推定残り時間が含まれます（例: 42.50% (estimated time remaining: 5 minutes)）。

すべてのバックグラウンド移行を一覧表示

すべてのデータベースにわたるすべてのバッチ処理されたバックグラウンド移行を表示するには:

sudo gitlab-rake gitlab:background_migrations:list

出力例:

id      | table_name                       | job_class_name                                | status    | progress
--------|----------------------------------|-----------------------------------------------|-----------|----------------------------------------------------------
main_1  | namespace_settings               | UpdateRequireDpopForManageApiEndpointsToFalse | finished  | 100.00%
main_2  | resource_iteration_events        | BackfillResourceIterationEventsNamespaceId    | finalized | 100.00%
main_3  | identities                       | DeleteTwitterIdentities                       | finalized | 100.00%
main_4  | software_license_policies        | BackfillLicensesOutsideSpdxCatalogue          | finalized | 100.00%
main_5  | security_policies                | BackfillPipelineExecutionPoliciesMetadata     | active    | 42.50% (estimated time remaining: 5 minutes)
ci_1    | ci_runners                       | MarkAdminBotRunnersAsHosted                   | finalized | 100.00%
ci_2    | p_ci_build_trace_metadata        | BackfillUpsertedCiBuildTraceMetadataProjectId | finalized | 100.00%
ci_3    | ci_runners                       | BackfillOrganizationIdOnCiRunners             | active    | 78.30% (estimated time remaining: about 1 hour)

sudo gitlab-rake gitlab:background_migrations:status

移行の詳細を表示

特定の移行に関する詳細情報を表示するには:

sudo gitlab-rake gitlab:background_migrations:show[<migration_id>]

例:

sudo gitlab-rake gitlab:background_migrations:show[ci_1]

出力例:

id                       | ci_1
created_at               | 2025-05-06 22:40:08 UTC
updated_at               | 2025-08-20 22:29:07 UTC
min_value                | 1
max_value                | 30
batch_size               | 1000
sub_batch_size           | 100
interval                 | 120
status                   | finalized
job_class_name           | MarkAdminBotRunnersAsHosted
batch_class_name         | PrimaryKeyBatchingStrategy
table_name               | ci_runners
column_name              | id
job_arguments            | []
total_tuple_count        |
pause_ms                 | 100
max_batch_size           |
started_at               | 2025-05-06 22:40:08 UTC
on_hold_until            |
gitlab_schema            | gitlab_ci
finished_at              | 2025-05-06 22:40:13 UTC
queued_migration_version | 20250505095336
min_cursor               |
max_cursor               |

移行を一時停止する

アクティブなバックグラウンド移行を一時停止するには:

sudo gitlab-rake gitlab:background_migrations:pause[<migration_id>]

例:

sudo gitlab-rake gitlab:background_migrations:pause[main_85]

activeステータスの移行のみ一時停止できます。他の状態で移行を一時停止しようとすると、エラーになります。

移行を再開する

一時停止したバックグラウンド移行を再開するには:

sudo gitlab-rake gitlab:background_migrations:resume[<migration_id>]

例:

sudo gitlab-rake gitlab:background_migrations:resume[main_85]

pausedステータスの移行のみ再開できます。他の状態で移行を再開しようとすると、エラーになります。

移行を実行する

特定のバックグラウンド移行をすぐに実行するには:

sudo gitlab-rake gitlab:background_migrations:execute[<migration_id>]

例:

sudo gitlab-rake gitlab:background_migrations:execute[ci_10]

出力例:

Are you sure you want to execute this migration? yes
Executing background migration `ci_10`...
Done.

このタスクは、移行をフォアグラウンドで同期的に実行します。この移行は、完了するか失敗するまで実行されます。これは、大規模な移行の場合にかなりの時間を要し、データベースのパフォーマンスに影響を与える可能性があります。可能な場合は、メンテナンス期間中にこのタスクを使用してください。

このタスクは、実行前に確認を求めます。移行が完了しない場合は、詳細についてgitlab:background_migrations:show[<migration_id>]で移行ステータスを確認してください。

すべての移行を実行する

すべてのデータベースにわたる、未完了のすべてのバックグラウンド移行を実行するには:

sudo gitlab-rake gitlab:background_migrations:execute_all

出力例:

Are you sure you want to execute all unfinished migrations? yes
[main] Executing 6 background migrations...
[main_85]: Start.
[main_85]: Done.
[main_86]: Start.
[main_86]: Done.
[main_87]: Start.
[main_87]: Done.
[main_88]: Start.
[main_88]: Done.
[main_89]: Start.
[main_89]: Done.
[main_90]: Start.
[main_90]: Done.
[ci] Executing 3 background migrations...
[ci_8]: Start.
[ci_8]: Done.
[ci_9]: Start.
[ci_9]: Done.
[ci_10]: Start.
[ci_10]: Done.

このタスクは、未完了のすべての移行をフォアグラウンドで同期的に実行します。これは非常に長い時間がかかり、データベースのパフォーマンスに大きく影響する可能性があります。このタスクは、計画されたメンテナンス期間中にのみ使用してください。個々の移行が失敗した場合でも、このタスクは続行されますが、出力に失敗をレポートします。

このタスクは:

実行前に確認を求めます。
ID順に移行を処理します。
各移行の完了時にステータスをレポートします。
一部が失敗した場合でも、残りの移行の処理を続行します。

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

データベーステーブルをバッチで更新するために、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から

前提条件:

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

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

右上隅で、管理者を選択します。
モニタリング > バックグラウンド移行を選択します。
待機中または完了中を選択すると未完了の移行を確認できます。失敗を選択すると失敗した移行を確認できます。

データベースから

前提条件:

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

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

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

未完了のバッチバックグラウンド移行の詳細を確認するには、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);"

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

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

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

バッチ化バックグラウンドマイグレーションを一時停止する

リリースされた機能を無効にする際のリスクがあります。詳細については、各機能の履歴を参照してください。

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

前提条件:

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

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

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

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

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;

数分以内にクエリを複数回実行して、新しい行が追加されていないことを確認します。新しい行が追加されていない場合、移行は一時停止されています。
移行が一時停止されたことを確認したら、（上記のenableコマンドを使用して）移行を再開し、バッチを続行します。大規模なインスタンスでは、バックグラウンド移行の各バッチを完了するまでに最大48時間かかることがあります。

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

リリースされた機能を無効にする際のリスクがあります。詳細については、この機能の履歴を参照してください。

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

並列実行

リリースされた機能を無効にする際のリスクがあります。詳細については、この機能の履歴を参照してください。

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

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

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

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

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

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

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

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

前提条件:

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

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

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

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

前提条件:

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

右上隅で、管理者を選択します。
モニタリング > バックグラウンド移行を選択します。
失敗タブを選択します。これにより、失敗したバッチバックグラウンド移行のリストが表示されます。
失敗したバッチバックグラウンド移行を選択して再試行するには、再試行ボタン（）をクリックします。

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

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

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

失敗のエラーログを表示し、次のようなAn error has occurred, all later migrations canceledエラーメッセージを探します:

StandardError: An error has occurred, all later migrations canceled:

Expected batched background migration for the given configuration to be marked as
'finished', but it is 'active':
  {:job_class_name=>"CopyColumnUsingBackgroundMigrationJob",
   :table_name=>"push_event_payloads",
   :column_name=>"event_id",
   :job_arguments=>[["event_id"],
   ["event_id_convert_to_bigint"]]
  }

山かっこ内の値を正しい引数に置き換えたうえで、次のコマンドを実行します:
```
sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>']
```
[["id"],["id_convert_to_bigint"]]などの複数の引数を処理する場合は、無効な文字エラーを防ぐために、各引数間のカンマをバックスラッシュ\でエスケープします。たとえば、前のステップから移行を完了するには、次のようにします:
```
sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,push_event_payloads,event_id,'[["event_id"]\, ["event_id_convert_to_bigint"]]']
```

データベースで移行のステータスを確認します。
クエリ結果を使用して移行コマンドを作成し、山かっこ内の値を正しい引数に置き換えます:
```
sudo gitlab-rake gitlab:background_migrations:finalize[<job_class_name>,<table_name>,<column_name>,'<job_arguments>']
```
たとえば、クエリが次のデータを返す場合:
- job_class_name: CopyColumnUsingBackgroundMigrationJob
- table_name: events
- column_name: id
- job_arguments: [["id"], ["id_convert_to_bigint"]]
[["id"],["id_convert_to_bigint"]]などの複数の引数を処理する場合は、無効な文字エラーを防ぐために、各引数間のカンマをバックスラッシュ\でエスケープします。job_argumentsパラメータ値のすべてのカンマは、バックスラッシュでエスケープする必要があります。
例:
```
sudo gitlab-rake gitlab:background_migrations:finalize[CopyColumnUsingBackgroundMigrationJob,ci_builds,id,'[["id"\, "stage_id"]\,["id_convert_to_bigint"\,"stage_id_convert_to_bigint"]]']
```

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

これらの手順を使用する前に、GitLabサポートに連絡してください。この操作を行うと、データ損失やインスタンスの障害が発生し、復旧が困難になる可能性があります。

多数のバージョンアップグレードをスキップしたり、下位互換性のないデータベーススキーマの変更を行ったりすると、バックグラウンド移行が失敗する場合があります（例については、イシュー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）
ステータスの遷移（保留中、実行中、成功、失敗）

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

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

Database::BatchedBackgroundMigrationWorkerのSidekiqログエントリでcorrelation_idを見つけます。
その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": []
}

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

プラン: Premium、Ultimate
提供形態: GitLab Self-Managed

このセクションは、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をターゲットバージョンにアップグレードした後でインスタンスのインデックスを再作成することです。この処理中は、高度な検索で検索設定で高度な検索を無効にすることもできます。

大規模なインスタンスのインデックス作成にはリスクが伴います。詳細については、大規模なインスタンスにインデックスを効率的に作成するを参照してください。