{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: 私有化部署

{{< /details >}}

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

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

请阅读下面关于这两种类型迁移的详细信息。

数据库背景迁移

{{< history >}}

  • 在极狐GitLab 13.1 中，功能标志 execute_batched_migrations_on_schedule 默认启用。
  • 对于极狐GitLab 私有化部署，管理员可以选择 禁用它。

{{< /history >}}

某些版本可能需要在更新到新版本之前完成不同的迁移。存在两种类型的迁移。它们有所不同，您应该检查两者是否在升级极狐GitLab 之前完成：

  • 批量背景迁移 在极狐GitLab 14.0 中引入。极狐GitLab 15.1 及以后的所有迁移均使用这种格式。
  • 背景迁移 不批量。在极狐GitLab 15.0 及以前使用。

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

批量背景迁移

为了批量更新数据库表，极狐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

先决条件：

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

要检查批量背景迁移的状态：

  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);"

如果查询返回零行，则所有批量背景迁移已完成。

启用或禁用高级功能

批量背景迁移提供功能标志，使您可以自定义迁移或完全暂停它们。这些功能标志仅应由了解这样做风险的高级用户禁用。

暂停批量背景迁移

{{< alert type=”warning” >}}

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

{{< /alert >}}

要暂停正在进行的批量背景迁移，禁用批量背景迁移功能。禁用功能会完成当前批次的迁移，然后在功能再次启用后等待启动下一批次。

先决条件：

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

使用以下数据库查询查看当前批量背景迁移的状态：

  1. 获取正在运行迁移的 ID：

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

  2. 运行此查询，将上一步中获取的 ID 替换为 XX，查看迁移的状态：

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

自动批处理大小优化

{{< history >}}

  • 引入于极狐GitLab 13.2，使用名为 optimize_batched_migrations 的功能标志。默认启用。

{{< /history >}}

{{< alert type=”warning” >}}

禁用已发布的功能可能存在 风险。

{{< /alert >}}

{{< alert type=”flag” >}}

在极狐GitLab 私有化部署中，默认情况下此功能可用。要隐藏该功能，请要求管理员禁用名为 optimize_batched_migrations 的功能标志。 在 JihuLab.com 上，此功能可用。在极狐GitLab 专用版上，此功能不可用。

{{< /alert >}}

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

并行执行

{{< history >}}

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

{{< /history >}}

{{< alert type=”warning” >}}

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

{{< /alert >}}

为了加快批量背景迁移的执行速度，同时执行两个迁移。

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

ApplicationSetting.update_all(database_max_running_batched_background_migrations: 4)

解决失败的批量背景迁移

如果批量背景迁移失败，修复并重试它。如果迁移继续失败并出现错误，则可以选择：

修复并重试迁移

所有失败的批量背景迁移必须解决才能升级到极狐GitLab 的新版本。如果您检查批量背景迁移的状态，某些迁移可能会在 失败 标签中显示为 failed 状态：

failed batched background migrations table

要确定批量背景迁移失败的原因，查看失败错误日志或在 UI 中查看错误信息。

先决条件：

  • 您必须具有实例的管理员访问权限。
  1. 在左侧边栏底部，选择 管理员。
  2. 选择 监控 > 背景迁移。
  3. 选择 失败 标签。这会显示一系列失败的批量背景迁移。
  4. 选择失败的 迁移 查看迁移参数和失败的作业。
  5. 在 失败的作业 下，选择每个 ID 查看作业失败的原因。

如果您是极狐GitLab 客户，考虑开设 支持请求 来调试批量背景迁移失败的原因。

要纠正问题，您可以重试失败的迁移。

先决条件：

  • 您必须具有实例的管理员访问权限。
  1. 在左侧边栏底部，选择 管理员。
  2. 选择 监控 > 背景迁移。
  3. 选择 失败 标签。这会显示一系列失败的批量背景迁移。
  4. 通过点击重试按钮 ({{< icon name=”retry” >}}) 选择要重试的失败批量背景迁移。

要监控重试的批量背景迁移，您可以定期检查批量背景迁移的状态。

手动完成失败的迁移

要手动完成因错误而失败的批量背景迁移，请使用失败错误日志或数据库中的信息：

{{< tabs >}}

{{< tab title=”从失败错误日志中” >}}

  1. 查看失败错误日志并查找 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"]]
  }

  2. 运行以下命令，将尖括号中的值替换为正确的参数：

    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"]]']

{{< /tab >}}

{{< tab title=”从数据库中” >}}

  1. 检查迁移在数据库中的状态。

  2. 使用查询结果构造迁移命令，将尖括号中的值替换为正确的参数：

    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"]]']

{{< /tab >}}

{{< /tabs >}}

标记失败的迁移已完成

{{< alert type=”warning” >}}

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

{{< /alert >}}

可能会出现背景迁移失败的情况：当跳过太多版本升级或向后兼容性数据库架构更改时。失败的背景迁移阻止进一步的应用程序升级。

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

{{< alert type=”warning” >}}

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

{{< /alert >}}

# 启动 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 >}}

{{< tab title=”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'

{{< /tab >}}

{{< tab title=”自编译 (源代码)” >}}

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'

{{< /tab >}}

{{< /tabs >}}

检查失败的背景迁移

要检查失败的非批量背景迁移：

{{< tabs >}}

{{< tab title=”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'

{{< /tab >}}

{{< tab title=”自编译 (源代码)” >}}

对于极狐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'

{{< /tab >}}

{{< /tabs >}}

高级搜索迁移

检查待定迁移

{{< details >}}

  • Tier: 专业版, 旗舰版
  • Offering: 极狐GitLab 私有化部署

{{< /details >}}

如果您启用了 Elasticsearch 集成，此部分仅适用。主要版本发布要求从当前版本的最新次要版本完成所有 高级搜索迁移，然后进行主要版本升级。您可以通过运行以下命令找到待定迁移。

{{< tabs >}}

{{< tab title=”Linux 软件包 (Omnibus)” >}}

sudo gitlab-rake gitlab:elastic:list_pending_migrations

{{< /tab >}}

{{< tab title=”自编译 (源代码)” >}}

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

{{< /tab >}}

{{< /tabs >}}

如果您处于长升级路径并且有许多待定迁移，您可能希望配置 重新排队索引作业 和 非代码索引的分片数 以加速索引。另一种选择是忽略待定迁移，并在您将极狐GitLab 升级到目标版本后 重新索引实例。您还可以在此过程中使用 启用 Elasticsearch 的搜索 设置禁用高级搜索。

{{< alert type=”warning” >}}

索引大型实例存在风险。有关更多信息，请参阅 有效索引大型实例。

{{< /alert >}}