数据库后台迁移
- 批处理后台迁移
- 后台迁移
  - 检查未完成的后台迁移
  - 检查失败的后台迁移
检查未完成的高级搜索迁移

升级迁移

在升级极狐GitLab 时，有两种类型的迁移需要检查：

数据库迁移。
高级搜索迁移。

请阅读以下有关这两种迁移的详细信息。

数据库后台迁移

在极狐GitLab 13.12 中，功能标志 execute_batched_migrations_on_schedule 默认启用。
对于自托管的极狐GitLab 实例，极狐GitLab 管理员可以选择禁用它。

某些版本可能需要在更新到新版本之前完成不同的迁移。存在两种迁移。它们有所不同，您应确保在升级极狐GitLab 之前两者都已完成：

批处理后台迁移在极狐GitLab 14.0 中引入。极狐GitLab 15.1 及更高版本中的所有迁移仅使用这种格式。
非批处理后台迁移。在极狐GitLab 15.0 及更早版本中使用。

为了减少完成这些迁移所需的时间，请增加可以处理 background_migration 队列中的作业的 Sidekiq 工作进程的数量。

批处理后台迁移

为了批量更新数据库表，极狐GitLab 可以使用批处理后台迁移。这些迁移由极狐GitLab 开发人员创建，并在升级时自动运行。然而，这样的迁移范围有限，以帮助将一些 integer 数据库列迁移到 bigint。这是为了防止某些表的整数溢出。

批处理后台迁移由 Sidekiq 处理，并在隔离中运行，因此在迁移处理中实例可以保持运作。然而，在运行批处理后台迁移时，大型实例的性能可能会下降。您应积极监控 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 检查

前提条件：

您必须具有实例的管理员访问权限。

要检查批处理后台迁移的状态：

在左侧边栏的底部，选择 Admin。
选择 Monitoring > Background migrations。
选择 Queued 或 Finalizing 以查看未完成的迁移，以及 Failed 以查看失败的迁移。

从数据库查询

前提条件：

您必须具有实例的管理员访问权限。

要直接查询数据库以获取批处理后台迁移的状态：

登录到 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 小时才能完成。

自动批处理大小优化

在极狐GitLab 13.2 中引入带有标志的功能，名为 optimize_batched_migrations。默认启用。

禁用已发布功能时可能存在风险。请参考该功能的历史记录以获取更多详细信息。

在自托管的极狐GitLab 上，默认情况下此功能是可用的。要隐藏该功能，请让管理员禁用名为 optimize_batched_migrations 的功能标志。在 GitLab.com 上，此功能是可用的。在 GitLab Dedicated 上，此功能不可用。

为了最大化批处理后台迁移的吞吐量（以每时间单位更新的元组数计算），批处理大小会根据前一个批次完成所需的时间自动调整。

并行执行

在极狐GitLab 15.7 中引入，使用名为 batched_migrations_parallel_execution 的功能标志。默认禁用。
在极狐GitLab 15.11 中在 JihuLab.com 上启用。
在极狐GitLab 16.1 中 GA。功能标志 batched_migrations_parallel_execution 被移除。

禁用已发布功能时可能存在风险。请参考该功能的历史记录以获取更多详细信息。

为了加快批处理后台迁移的执行，两次迁移会同时执行。

具有极狐GitLab Rails 控制台访问权限的极狐GitLab 管理员可以更改并行执行的批处理后台迁移数量：

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

解决失败的批处理后台迁移

如果批处理后台迁移失败，请修复并重试。如果迁移继续出现错误，可以：

手动完成失败的迁移
标记失败的迁移为已完成

修复并重试迁移

所有失败的批处理后台迁移必须在升级到新版本的极狐GitLab 之前解决。如果您检查批处理后台迁移的状态，某些迁移可能会在 Failed 选项卡中显示 failed 状态：

要确定批处理后台迁移失败的原因，可以查看失败错误日志或在 UI 中查看错误信息。

前提条件：

您必须具有实例的管理员访问权限。

在左侧边栏的底部，选择 管理中心。
选择 监控 > 后台迁移。
选择失败选项卡。这将显示失败的批处理后台迁移列表。
选择失败的迁移以查看迁移参数和失败的作业。
在 失败作业 下，选择每个 ID 以查看作业失败的原因。

如果您是极狐GitLab 的客户，建议提交支持请求以调试批处理后台迁移失败的原因。

要解决问题，您可以重试失败的迁移。

前提条件：

您必须具有实例的管理员访问权限。

在左侧边栏的底部，选择 Admin。
选择 Monitoring > Background migrations。
选择 Failed 选项卡。这将显示失败的批处理后台迁移列表。
选择一个失败的批处理后台迁移以重试，点击重试按钮（）。

要监控重试的批处理后台迁移，您可以定期检查批处理后台迁移的状态。

手动完成失败的迁移

要手动完成由于错误而失败的批处理后台迁移，可以使用失败错误日志或数据库中的信息：

::Tabs

:::TabTitle 从失败错误日志

查看失败错误日志，查找 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"]]']

:::TabTitle 从数据库

检查迁移的状态。
使用查询结果构造迁移命令，替换尖括号中的值为正确的参数：
```
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"]]']

::EndTabs

标记失败的迁移为已完成

在使用这些说明之前，请联系极狐GitLab 支持。此操作可能导致数据丢失，并使您的实例出现难以恢复的故障。

可能会有后台迁移失败的情况：当跳过太多版本升级时，或者发生不向后兼容的数据库架构更改时。（例如，参见问题 393216）。失败的后台迁移会阻止进一步的应用程序升级。

当确定后台迁移可以“安全”跳过时，可以手动标记迁移为已完成：

在继续之前，请确保创建备份。

# 启动 rails 控制台

connection = ApplicationRecord.connection # 或 Ci::ApplicationRecord.connection，取决于迁移是在哪个数据库上计划的

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,
    []
  )

  # 标记所有作业完成
  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

后台迁移

非批处理迁移被批处理后台迁移取代。非批处理迁移在极狐GitLab 14 期间逐步淘汰，最后一次在极狐GitLab 15.0 中使用。

检查未完成的后台迁移

要检查未完成的非批处理后台迁移：

::Tabs

:::TabTitle Linux 软件包（Omnibus）

sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count'

:::TabTitle 自编译（源代码）

cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining'
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count'

::EndTabs

检查失败的后台迁移

要检查失败的非批处理后台迁移：

::Tabs

:::TabTitle Linux 软件包（Omnibus）

对于极狐GitLab 版本 14.10 及更高版本：

sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.with_status(:failed).count'

对于极狐GitLab 版本 14.0-14.9：

sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.failed.count'

:::TabTitle 自编译（源代码）

对于极狐GitLab 版本 14.10 及更高版本：

cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.with_status(:failed).count'

对于极狐GitLab 版本 14.0-14.9：

cd /home/git/gitlab
sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.failed.count'

::EndTabs

检查未完成的高级搜索迁移

此部分仅适用于已启用 Elasticsearch 集成的情况。主要版本更新要求所有高级搜索迁移必须从您当前版本中的最新次要版本完成，才能进行主要版本升级。您可以通过运行以下命令找到未完成的迁移。

::Tabs

:::TabTitle Linux 软件包（Omnibus）

sudo gitlab-rake gitlab:elastic:list_pending_migrations

:::TabTitle 自编译（源代码）

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

::EndTabs