批量后台迁移

Feature.disable(:batched_migrations_health_status_autovacuum)

Feature.enable(:batched_migrations_health_status_autovacuum)

bundle exec rails g batched_background_migration my_batched_migration --table_name=<table-name> --column_name=<column-name> --feature_category=<feature-category>

queue_batched_background_migration(
  JOB_CLASS_NAME,
  TABLE_NAME,
  JOB_ARGUMENTS
)

# frozen_string_literal: true

class QueueResolveVulnerabilitiesForRemovedAnalyzers < Gitlab::Database::Migration[2.2]
  milestone '17.3'

MIGRATION = "ResolveVulnerabilitiesForRemovedAnalyzers"

def up
    # 无操作，因为原始迁移存在错误，已通过以下方式修复
  end

def down
    # 无操作，因为原始迁移存在错误，已在https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162527中修复
  end
end

# frozen_string_literal: true

class RequeueResolveVulnerabilitiesForRemovedAnalyzers < Gitlab::Database::Migration[2.2]
  milestone '17.4'

restrict_gitlab_migration gitlab_schema: :gitlab_main

MIGRATION = "ResolveVulnerabilitiesForRemovedAnalyzers"
  BATCH_SIZE = 10_000
  SUB_BATCH_SIZE = 100

def up
    # 清理之前由QueueResolveVulnerabilitiesForRemovedAnalyzers执行的背景迁移
    delete_batched_background_migration(MIGRATION, :vulnerability_reads, :id, [])

queue_batched_background_migration(
      MIGRATION,
      :vulnerability_reads,
      :id,
      batch_size: BATCH_SIZE,
      sub_batch_size: SUB_BATCH_SIZE
    )
  end

def down
    delete_batched_background_migration(MIGRATION, :vulnerability_reads, :id, [])
  end
end

---
migration_job_name: ResolveVulnerabilitiesForRemovedAnalyzers
description: 解决所有检测到的已移除分析器的漏洞。
feature_category: static_application_security_testing
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/162691
milestone: '17.4'
queued_migration_version: 20240814085540
finalized_by: # 最终确定此BBM的迁移版本

class BackfillNamespaceType < Gitlab::Database::Migration[2.1]
  # 不再需要BBM的原因。例如：此BBM不再需要，因为它将被另一个具有不同逻辑的BBM取代。
  def up; end

def down; end
end

class CleanupBackfillNamespaceType < Gitlab::Database::Migration[2.1]
  MIGRATION = "MyMigrationClass"

restrict_gitlab_migration gitlab_schema: :gitlab_main

def up
    delete_batched_background_migration(MIGRATION, :vulnerabilities, :id, [])
  end

def down; end
end

queue_batched_background_migration(
  'CopyColumnUsingBackgroundMigrationJob',
  TABLE_NAME,
  'name', 'name_convert_to_text'
)

class CopyColumnUsingBackgroundMigrationJob < BatchedMigrationJob
  job_arguments :copy_from, :copy_to
  operation_name :update_all

def perform
    from_column = connection.quote_column_name(copy_from)
    to_column = connection.quote_column_name(copy_to)

assignment_clause = "#{to_column} = #{from_column}"

each_sub_batch do |relation|
      relation.update_all(assignment_clause)
    end
  end
end

# PrimaryKeyBatchingStrategy
Namespace.each_batch(of: 100) do |relation|
  relation.where(type: nil).update_all(type: 'User') # 此操作在每个后台作业中执行
end

# 若存在以下任一索引则效果良好：
#  - `id WHERE type IS NULL`
#  - `(type, id)`
# 否则效果不佳。
Namespace.where(type: nil).each_batch(of: 100) do |relation|
  relation.update_all(type: 'User')
end

   class BackfillNamespaceType < BatchedMigrationJob

# 若存在以下任一索引则效果良好：
     #  - `id WHERE type IS NULL`
     #  - `(type, id)`
     # 否则效果不佳。
     scope_to ->(relation) { relation.where(type: nil) }
     operation_name :update_all
     feature_category :source_code_management

def perform
       each_sub_batch do |sub_batch|
         sub_batch.update_all(type: 'User')
       end
     end
   end

   class BackfillNamespaceType < Gitlab::Database::Migration[2.1]
     MIGRATION = 'BackfillNamespaceType'

restrict_gitlab_migration gitlab_schema: :gitlab_main

def up
       queue_batched_background_migration(
         MIGRATION,
         :namespaces,
         :id
       )
     end

def down
       delete_batched_background_migration(MIGRATION, :namespaces, :id, [])
     end
   end

# 好
class Gitlab::BackgroundMigration::ExtractIntegrationsUrl
  class Project < ::ApplicationRecord
    self.table_name = 'projects'
  end

  class Build < ::Ci::ApplicationRecord
    self.table_name = 'ci_builds'
  end
end

# 坏
class Gitlab::BackgroundMigration::ExtractIntegrationsUrl
  class Project < ActiveRecord::Base
    self.table_name = 'projects'
  end

  class Build < ActiveRecord::Base
    self.table_name = 'ci_builds'
  end
end

# 好
Project.connection.execute("SELECT * FROM projects")

# 可接受
ApplicationRecord.connection.execute("SELECT * FROM projects")

# 坏
ActiveRecord::Base.connection.execute("SELECT * FROM projects")

class ProjectsWithIssuesMigration < Gitlab::Database::Migration[2.1]
  MIGRATION = 'BatchProjectsWithIssues'
  BATCH_SIZE = 5000
  SUB_BATCH_SIZE = 500
  restrict_gitlab_migration gitlab_schema: :gitlab_main

  disable_ddl_transaction!
  def up
    queue_batched_background_migration(
      MIGRATION,
      :issues,
      :project_id,
      batch_size: BATCH_SIZE,
      batch_class_name: 'LooseIndexScanBatchingStrategy', # 覆盖默认分批策略
      sub_batch_size: SUB_BATCH_SIZE
    )
  end

  def down
    delete_batched_background_migration(MIGRATION, :issues, :project_id, [])
  end
end

module Gitlab
  module BackgroundMigration
    class BatchProjectsWithIssues < Gitlab::BackgroundMigration::BatchedMigrationJob
      include Gitlab::Database::DynamicModelHelpers

      operation_name :backfill_issues

      def perform
        distinct_each_batch do |batch|
          project_ids = batch.pluck(batch_column)
          # 对唯一的 project_ids 执行操作
        end
      end
    end
  end
end

def up
  instance = Gitlab::BackgroundMigration::YourBackgroundMigrationClass.new(
      start_id: <batch start_id>,
      end_id: <batch end_id>,
      batch_table: <table name>,
      batch_column: <batching column>,
      sub_batch_size: <sub batch size>,
      pause_ms: <milliseconds between batches>,
      job_arguments: <job arguments if any>,
      connection: connection
    )

instance.perform
end

def down
  # 无操作
end

diff --git a/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb b/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb
index b8d1d21a0d2d2a23d9e8c8a0a17db98ed1ed40b7..912e20659a6919f771045178c66828563cb5a4a1 100644
--- a/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb
+++ b/lib/gitlab/database/migration_helpers/restrict_gitlab_schema.rb
@@ -55,7 +55,7 @@ def unmatched_schemas
         end

def allowed_schemas_for_connection

-          Gitlab::Database.gitlab_schemas_for_connection(connection)

Gitlab::Database.gitlab_schemas_for_connection(connection) << :gitlab_ci\n```\n\n1. 将模式名称添加到 [`RestrictAllowedSchemas`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb#L82)\n\n```diff\ndiff --git a/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb b/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb\nindex 4ae3622479f0800c0553959e132143ec9051898e..d556ec7f55adae9d46a56665ce02de782cb09f2d 100644\n--- a/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb\n+++ b/lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb\n@@ -79,7 +79,7 @@ def restrict_to_dml_only(parsed)\n           tables = self.dml_tables(parsed)\n           schemas = self.dml_schemas(tables)\n \n-          if (schemas - self.allowed_gitlab_schemas).any?\n+\n           if (schemas - (self.allowed_gitlab_schemas << :gitlab_ci)).any?\n             raise DMLAccessDeniedError, \\n               "Select/DML queries (SELECT/UPDATE/DELETE) do access \'#{tables}\' (#{schemas.to_a}) " \\n               "which is outside of list of allowed schemas: \'#{self.allowed_gitlab_schemas}\'. " \\n```\n\n#### 启动数据库迁移流水线\n\n创建一个包含您更改的草稿合并请求，并触发手动 `db:gitlabcom-database-testing` 任务。\n\n### 建立依赖关系\n\n在某些情况下，迁移依赖于先前排队的批量后台迁移(BBM)的完成。如果BBM仍在运行，则依赖的迁移将失败。例如：在大表上引入唯一索引可能依赖于先前排队的BBM来处理任何重复记录。\n\n已配置以下流程，以便在编写迁移时更清晰地显示依赖关系。\n\n- 排队BBM的迁移版本存储在 `batched_background_migrations` 表和BBM字典文件中。\n\n- 在每个迁移文件中添加了 `DEPENDENT_BATCHED_BACKGROUND_MIGRATIONS` 常量（默认注释）。要建立依赖关系，请添加相关BBM的 `queued_migration_version`。如果没有，请删除注释行。\n\n- 如果相关的BBM尚未完成，`Migration::UnfinishedDependencies` cop会发出警告。它通过查看BBM字典中的 `finalized_by` 键来确定它们是否已完成。\n\n示例：\n\n```ruby\n# db/post_migrate/20231113120650_queue_backfill_routes_namespace_id.rb\nclass QueueBackfillRoutesNamespaceId < Gitlab::Database::Migration[2.1]\n  MIGRATION = \'BackfillRouteNamespaceId\'\n\nrestrict_gitlab_migration gitlab_schema: :gitlab_main\n  ...\n  ...\n\ndef up\n    queue_batched_background_migration(\n      MIGRATION,\n      ...\n    )\n  end\nend\n```\n\n```ruby\n# 这取决于QueueBackfillRoutesNamespaceId BBM的最终完成\nclass AddNotNullToRoutesNamespaceId < Gitlab::Database::Migration[2.1]\n  DEPENDENT_BATCHED_BACKGROUND_MIGRATIONS = ["20231113120650"]\n\ndef up\n    add_not_null_constraint :routes, :namespace_id\n  end\n\ndef down\n    remove_not_null_constraint :routes, :namespace_id\n  end\nend\n```\n\n## 管理\n\n

  

  

    
\n\nBBM管理通过 chatops 集成进行，仅限GitLab团队成员使用。\n\n


\n\n### 列出批量后台迁移\n\n要列出系统中的批量后台迁移，请运行以下命令：\n\n`/chatops run batched_background_migrations list`\n\n此命令支持以下选项：\n\n- 数据库选择：\n\n- `--database DATABASE_NAME`：连接到指定数据库：\n\n- `main`：使用主数据库（默认）。\n\n- `ci`：使用CI数据库。\n\n- 环境选择：\n\n- `--dev`：使用 `dev` 环境。\n\n- `--staging`：使用 `staging` 环境。\n\n- `--staging_ref`：使用 `staging_ref` 环境。\n\n- `--production` ：使用 `production` 环境（默认）。\n\n- 按作业类过滤\n\n- `--job-class-name JOB_CLASS_NAME`：仅列出给定作业类的作业。\n\n- 这是背景迁移YAML定义中的 `migration_job_name`。\n\n输出示例：\n\n![ChatOps命令输出的所有活跃批量后台迁移列表。](img/list_v15_4.png)\n\n

  

  

    
\n\nChatOps按 created_at（降序）返回20个批量后台迁移。\n\n


\n\n### 监控批量后台迁移的进度和状态\n\n要查看特定批量后台迁移的状态和进度，请运行以下命令：\n\n`/chatops run batched_background_migrations status MIGRATION_ID`\n\n此命令支持以下选项：\n\n- 数据库选择：\n\n- `--database DATABASE_NAME`：连接到指定数据库：\n\n- `main`：使用主数据库（默认）\n\n- `ci`：使用CI数据库\n\n- 环境选择：\n\n- `--dev`：使用 `dev` 环境。\n\n- `--staging`：使用 `staging` 环境。

```markdown
- `--staging_ref`：使用 `staging_ref` 环境。

- `--production`：使用 `production` 环境（默认）。

![显示使用 MIGRATION_ID 的特定批量后台迁移进度和状态的 ChatOps 命令输出。](img/status_v15_4.png)

`Progress` 表示后台迁移的完成百分比。

批量后台迁移状态的定义：

- **活跃**：以下任一情况：
  
- 等待运行器选取
  
- 正在运行批处理作业

- **最终化**：正在运行批处理作业

- **失败**：批量后台迁移失败

- **完成**：所有作业已成功执行，批量后台迁移已完成

- **暂停**：对运行器不可见

- **已验证**：批量迁移通过 [`ensure_batched_background_migration_is_finished`](#finalize-a-batched-background-migration) 验证并已完成

### 暂停批量后台迁移

如果您想暂停一个批量后台迁移，您需要运行以下命令：

`/chatops run batched_background_migrations pause MIGRATION_ID`

此命令支持以下选项：

- 数据库选择：

- `--database DATABASE_NAME`：连接到指定数据库：

- `main`：使用主数据库（默认）。

- `ci`：使用 CI 数据库。

- 环境选择：

- `--dev`：使用 `dev` 环境。

- `--staging`：使用 `staging` 环境。

- `--staging_ref`：使用 `staging_ref` 环境。

- `--production`：使用 `production` 环境（默认）。

![显示使用 MIGRATION_ID 暂停特定批量后台迁移的 ChatOps 命令输出。](img/pause_v15_4.png)


  

  

    
您只能暂停处于 active 状态的批量后台迁移。




### 恢复批量后台迁移

如果您想恢复一个批量后台迁移，您需要运行以下命令：

`/chatops run batched_background_migrations resume MIGRATION_ID`

此命令支持以下选项：

- 数据库选择：

- `--database DATABASE_NAME`：连接到指定数据库：

- `main`：使用主数据库（默认）。

- `ci`：使用 CI 数据库。

- 环境选择：

- `--dev`：使用 `dev` 环境。

- `--staging`：使用 `staging` 环境。

- `--staging_ref`：使用 `staging_ref` 环境。

- `--production`：使用 `production` 环境（默认）。

![显示使用 MIGRATION_ID 恢复特定批量后台迁移的 ChatOps 命令输出。](img/resume_v15_4.png)


  

  

    
您只能恢复处于 active 状态的批量后台迁移




### 启用或禁用后台迁移

在极其有限的情况下，GitLab 管理员可以禁用以下一个或两个 [功能标志](../../administration/feature_flags/_index.md)：

- `execute_background_migrations`

- `execute_batched_migrations_on_schedule`

这些标志默认启用。仅在特殊情况下限制数据库操作时才禁用它们，例如数据库主机维护。


  

  

    
除非您完全理解其后果，否则不要禁用这些标志中的任何一个。如果禁用了 execute_background_migrations 或 execute_batched_migrations_on_schedule 功能标志，GitLab 升级可能会失败并且可能发生数据丢失。




## 仅限 EE 功能的批量后台迁移

所有仅限 EE 功能的后台迁移类都应该存在于 GitLab FOSS 中。
为此，请为 GitLab FOSS 创建一个空类，并按照 [实现企业版功能](../ee_features.md#code-in-libgitlabbackground_migration) 指南中所述进行扩展。


  

  

    
使用作业参数的仅限 EE 功能的后台迁移类应该在 GitLab FOSS 类中定义它们。
需要这些定义以防止在 GitLab FOSS 上下文中调度迁移时作业参数验证失败。




您可以使用 [生成器](#generate-a-batched-background-migration) 通过在生成新的批量后台迁移时传递 `--ee-only` 标志来生成仅限 EE 的迁移脚手架。

## 调试

### 查看失败错误日志

您可以通过两种方式查看失败信息：

- 通过 GitLab 日志：

1. 运行批量后台迁移后，如果有任何作业失败，
     在 [Kibana](https://log.gprd.gitlab.net/goto/4cb43f40-f861-11ec-b86b-d963a1a6788e) 中查看日志。
     查看 production Sidekiq 日志并筛选：

- `json.new_state: failed`

- `json.job_class_name: <批量后台迁移作业类名>`

- `json.job_arguments: <批量后台迁移作业类参数>`

1. 查看 `json.exception_class` 和 `json.exception_message` 值以帮助
     了解作业失败的原因。

SELECT migration.id, migration.job_class_name, transition_logs.exception_class, transition_logs.exception_message
FROM batched_background_migrations AS migration
INNER JOIN batched_background_migration_jobs AS jobs
ON jobs.batched_background_migration_id = migration.id
INNER JOIN batched_background_migration_job_transition_logs AS transition_logs
ON transition_logs.batched_background_migration_job_id = jobs.id
WHERE transition_logs.next_status = '2' AND migration.job_class_name = "CLASS_NAME";

# good
def perform
  each_sub_batch do |sub_batch|
    sub_batch.update_all(name: 'My Name')
  end
end

# acceptable
def perform
  each_sub_batch do |sub_batch|
    sub_batch.update_all(name: 'My Name')
  rescue Exception => error
    logger.error(message: error.message, class: error.class)
    raise
  end
end

# bad
def perform
  each_sub_batch do |sub_batch|
    sub_batch.update_all(name: 'My Name')
  rescue Exception => error
    logger.error(message: error.message, class: self.class.name)
  end
end

# good
def perform
  each_sub_batch do |sub_batch|
    connection.execute <<~SQL
      UPDATE fork_networks
      SET organization_id = projects.organization_id
      FROM projects
      WHERE fork_networks.id IN (#{sub_batch.pluck(:id)})
        AND fork_networks.root_project_id = projects.id
        AND fork_networks.organization_id IS NULL
    SQL
  end
end

# bad
def perform
  each_sub_batch do |sub_batch|
    sub_batch.each do |fork_network|
      fork_network.update!(organization_id: fork_network.root_project.organization_id)
    end
  end
end

SELECT id FROM users WHERE id BETWEEN 1 AND 3000;

QUERY PLAN

SELECT id FROM users WHERE id BETWEEN 1 AND 3000 AND theme_id = 4;

查询计划

--------------------------------------------------------------------------------------------------------------------------
使用 users_pkey 在 users 表上的索引扫描（成本=0.44..3773.66 行数=10 宽度=4）（实际时间=8.047..2290.528 行数=28 循环次数=1）
  索引条件：((id >= 1) AND (id <= 3000))
  过滤条件：(theme_id = 4)
  被过滤移除的行数：2626
规划时间：1.292 毫秒
执行时间：2290.582 毫秒

CREATE INDEX idx_users_theme_id ON users (theme_id);

查询计划

--------------------------------------------------------------------------------------------------------------------------------
位图堆扫描 on users （成本=691.28..706.53 行数=10 宽度=4）（实际时间=13.532..13.578 行数=28 循环次数=1）
  再检查条件：((id >= 1) AND (id <= 3000) AND (theme_id = 4))
  堆块：精确=28
  缓冲区：共享命中=41 读取=62
  I/O 时间：共享读取=0.721
  -> 位图与操作 （成本=691.28..691.28 行数=10 宽度=0）（实际时间=13.509..13.511 行数=0 循环次数=1）
        缓冲区：共享命中=13 读取=62
        I/O 时间：共享读取=0.721
        -> 位图索引扫描 on users_pkey （成本=0.00..45.95 行数=2751 宽度=0）（实际时间=0.390..0.390 行数=2654 循环次数=1）
              索引条件：((id >= 1) AND (id <= 3000))
              缓冲区：共享命中=10
        -> 位图索引扫描 on idx_users_theme_id （成本=0.00..645.08 行数=73352 宽度=0）（实际时间=12.933..12.933 行数=69872 循环次数=1）
              索引条件：(theme_id = 4)
              缓冲区：共享命中=3 读取=62
              I/O 时间：共享读取=0.721
规划：
  缓冲区：共享命中=35 读取=1 弄脏=2
  I/O 时间：共享读取=0.045
规划时间：0.514 毫秒
执行时间：13.634 毫秒

bundle exec rails g batched_background_migration BackfillRouteNamespaceId --table_name=routes --column_name=id --feature_category=source_code_management

class Gitlab::BackgroundMigration::BackfillRouteNamespaceId < BatchedMigrationJob
  # 为了说明目的，如果我们使用本地模型，可以这样定义，使用 `ApplicationRecord` 作为基类
  # class Route < ::ApplicationRecord
  #   self.table_name = 'routes'
  # end

  operation_name :update_all
  feature_category :source_code_management

  def perform
    each_sub_batch(
      batching_scope: -> (relation) { relation.where("source_type <> 'UnusedType'") }
    ) do |sub_batch|
      sub_batch.update_all('namespace_id = source_id')
    end
  end
end

class AddTriggerToRoutesToCopySourceIdToNamespaceId < Gitlab::Database::Migration[2.1]
  FUNCTION_NAME = 'example_function'
  TRIGGER_NAME = 'example_trigger'

def up
      execute(<<~SQL)
        CREATE OR REPLACE FUNCTION #{FUNCTION_NAME}() RETURNS trigger
        LANGUAGE plpgsql
        AS $$
        BEGIN
          NEW."namespace_id" = NEW."source_id"
          RETURN NEW;
        END;
        $$;

CREATE TRIGGER #{TRIGGER_NAME}() AFTER INSERT OR UPDATE
        ON routes
        FOR EACH ROW EXECUTE FUNCTION #{FUNCTION_NAME}();
      SQL
    end

def down
      drop_trigger(TRIGGER_NAME, :routes)
      drop_function(FUNCTION_NAME)
    end
end

class QueueBackfillRoutesNamespaceId < Gitlab::Database::Migration[2.1]
  MIGRATION = 'BackfillRouteNamespaceId'
  BATCH_SIZE = 1000
  SUB_BATCH_SIZE = 100

restrict_gitlab_migration gitlab_schema: :gitlab_main

def up
      queue_batched_background_migration(
        MIGRATION,
        :routes,
        :id,
        batch_size: BATCH_SIZE,
        sub_batch_size: SUB_BATCH_SIZE
      )
    end

def down
      delete_batched_background_migration(MIGRATION, :routes, :id, [])
    end
end

# db/docs/batched_background_migrations/backfill_route_namespace_id.yml
---
migration_job_name: BackfillRouteNamespaceId
description: 复制路由（routes）中的 source_id 值到 namespace_id
feature_category: 源码管理
introduced_by_url: "https://mr_url"
milestone: 16.6
queued_migration_version: 20231113120650
finalized_by: # 确保此批量迁移完成的迁移版本

class FinalizeBackfillRouteNamespaceId < Gitlab::Database::Migration[2.1]
  disable_ddl_transaction!

restrict_gitlab_migration gitlab_schema: :gitlab_main

def up
      ensure_batched_background_migration_is_finished(
        job_class_name: 'BackfillRouteNamespaceId',
        table_name: :routes,
        column_name: :id,
        job_arguments: [],
        finalize: true
      )
    end

def down
      # 无操作
    end
end

# db/docs/batched_background_migrations/backfill_route_namespace_id.yml
---
migration_job_name: BackfillRouteNamespaceId
description: 复制路由（routes）中的 source_id 值到 namespace_id
feature_category: 源码管理
introduced_by_url: "https://mr_url"
milestone: 16.6
queued_migration_version: 20231113120650
finalized_by: 20231115120912

class RemoveNamepaceIdTriggerFromRoutes < Gitlab::Database::Migration[2.1]
  FUNCTION_NAME = 'example_function'
  TRIGGER_NAME = 'example_trigger'

def up
      drop_trigger(TRIGGER_NAME, :routes)
      drop_function(FUNCTION_NAME)
    end

def down
      # 应反向执行添加触发器和函数的迁移中的 up 方法逻辑
    end
end