多数据库架构

Gitlab::Database::EachDatabase.each_model_connection([MySharedModel]) do |connection, connection_name|
  MySharedModel.select_all_data...
end

select count(*) from projects
inner join ci_runner_projects on ci_runner_projects.project_id = projects.id
where ci_runner_projects.runner_id IN (1, 2, 3)

select count(*) from ci_runner_projects
where ci_runner_projects.runner_id IN (1, 2, 3)

select ...
inner join security_scans
inner join ci_builds on security_scans.build_id = ci_builds.id
where ci_builds.id IN (1, 2, 3)

select ...
inner join security_scans
where security_scans.build_id IN (1, 2, 3)

allowed_user_id = board_user_finder
  .where(user_id: params['assignee_id'])
  .pick(:user_id)

User.find_by(id: allowed_user_id)

select projects.* from terraform_state_versions
inner join ci_builds on terraform_state_versions.ci_build_id = ci_builds.id
inner join projects on ci_builds.project_id = projects.id

select projects.* from terraform_state_versions
inner join projects on terraform_state_versions.project_id = projects.id

select projects.* from projects
inner join ci_daily_build_group_report_results on ci_daily_build_group_report_results.project_id = projects.id
where ((data->'coverage') is not null)
and ci_daily_build_group_report_results.default_branch = true
group by projects.id

select projects.* from projects
inner join projects_with_ci_feature_usage on projects_with_ci_feature_usage.project_id = projects.id
where projects_with_ci_feature_usage.ci_feature = 'code_coverage'

class Project
  has_many :pipelines
  has_many :builds, through: :pipelines
end

class Pipeline
  has_many :builds
end

class Build
  belongs_to :pipeline
end

def some_action
  @builds = Project.find(5).builds.order(created_at: :desc).limit(10)
end

select * from builds
inner join pipelines on builds.pipeline_id = pipelines.id
where pipelines.project_id = 5
order by builds.created_at desc
limit 10

class Project
  has_many :pipelines
  has_many :builds, through: :pipelines, disable_joins: true
end

select id from pipelines where project_id = 5;

select * from builds where pipeline_id in (...)
order by created_at desc
limit 10;

it 'does not join across databases' do
  with_cross_joins_prevented do
    ::Ci::Build.joins(:project).to_a
  end
end

it 'does not join across databases' do
  with_cross_joins_prevented do
    ::Ci::Build.preload(:project).to_a
  end
end

Database::PreventCrossJoins::CrossJoinAcrossUnsupportedTablesError:

Unsupported cross-join across 'users, notification_settings' querying 'gitlab_main_clusterwide, gitlab_main_cell' discovered when executing query 'SELECT "users".* FROM "users" WHERE "users"."id" IN (SELECT "notification_settings"."user_id" FROM ((SELECT "notification_settings"."user_id" FROM "notification_settings" WHERE "notification_settings"."source_id" = 119 AND "notification_settings"."source_type" = 'Project' AND (("notification_settings"."level" = 3 AND EXISTS (SELECT true FROM "notification_settings" "notification_settings_2" WHERE "notification_settings_2"."user_id" = "notification_settings"."user_id" AND "notification_settings_2"."source_id" IS NULL AND "notification_settings_2"."source_type" IS NULL AND "notification_settings_2"."level" = 2)) OR "notification_settings"."level" = 2))) notification_settings)'

# 限制执行数据库对象的代码块
::Gitlab::Database.allow_cross_joins_across_databases(url: 'https://gitlab.com/gitlab-org/gitlab/-/issues/336590') do
  subject.perform(1, 4)
end

# 将关系标记为允许跨数据库连接
def find_diff_head_pipeline
  all_pipelines
    .allow_cross_joins_across_databases(url: 'https://gitlab.com/gitlab-org/gitlab/-/issues/336891')
    .for_sha_or_source_sha(diff_head_sha)
    .first
end

class Group < Namespace
 has_many :users, -> {
    allow_cross_joins_across_databases(url: "https://gitlab.com/gitlab-org/gitlab/-/issues/422405")
  }, through: :group_members
end

class Group < Namespace
  has_many :users, through: :group_members

  # 不要这样覆盖关联。
  def users
    super.allow_cross_joins_across_databases(url: "https://gitlab.com/gitlab-org/gitlab/-/issues/422405")
  end
end

# 在主数据库上开启事务
ApplicationRecord.transaction do
  ci_build.update!(updated_at: Time.current) # 更新 CI 数据库
  ci_build.project.update!(updated_at: Time.current) # 更新主数据库
end
# 引发错误：在修改 'ci_build, projects' 表的事务中检测到 'main, ci' 的跨数据库数据修改

class GroupMember < Member
   def update_two_factor_requirement
     return unless user

     # 标记并忽略涉及 members 和 users/user_details/user_preferences 的跨数据库事务
     Gitlab::Database::QueryAnalyzers::PreventCrossDatabaseModification.temporary_ignore_tables_in_transaction(
       %w[users user_details user_preferences], url: 'https://gitlab.com/gitlab-org/gitlab/-/issues/424288'
     ) do
       user.update_two_factor_requirement
     end
   end
end

ci_build.update!(updated_at: Time.current) # CI 数据库
ci_build.project.update!(updated_at: Time.current) # 主数据库

current_time = Time.current

MyAsyncConsistencyJob.perform_async(cu_build.id)

ci_build.update!(updated_at: current_time)
ci_build.project.update!(updated_at: current_time)

allow_cross_database_modification_within_transaction(url: 'gitlab issue URL') do
  ApplicationRecord.transaction do
    ci_build.update!(updated_at: Time.current) # 更新 CI 数据库
    ci_build.project.update!(updated_at: Time.current) # 更新主数据库
  end
end
``
如有疑问，请随时联系 [Tenant Scale 组](https://handbook.gitlab.com/handbook/engineering/infrastructure-platforms/tenant-scale/) 获取建议。

##### 避免跨数据库使用 `dependent: :nullify` 和 `dependent: :destroy`
有时我们可能希望跨数据库使用 `dependent: :nullify` 或 `dependent: :destroy`。这在技术上是可行的，但存在问题，因为这些钩子在 `#destroy` 调用的外部事务上下文中运行，这会创建跨数据库事务而我们正试图避免。这种方式导致的跨数据库事务在切换到拆分架构时可能产生令人困惑的结果，因为现在某些查询发生在事务外部，它们可能部分应用而外部事务失败，可能导致意外错误。

对于需要在数据库外清理数据（例如对象存储）的非平凡对象，建议设置 [`dependent: :restrict_with_error`](https://guides.rubyonrails.org/association_basics.html#options-for-has-one-dependent)。此类对象应提前显式移除。使用 `dependent: :restrict_with_error` 可确保在未清理完时禁止销毁父对象。

如果只需要从 PostgreSQL 中清理子记录，请考虑使用[松散外键](loose_foreign_keys.md)。

## 跨数据库的外键
我们有许多地方使用跨数据库引用的外键。在两个独立的 PostgreSQL 数据库中无法实现此功能，因此我们需要以高性能方式复制 PostgreSQL 提供的行为。我们不能也不应尝试复制 PostgreSQL 防止创建无效引用的数据保证，但我们仍需要一种方法来替代级联删除，以避免出现孤立数据或指向不存在的记录，这可能导致错误。因此我们创建了["松散外键"](loose_foreign_keys.md)，这是一种异步清理孤立记录的机制。

### 现有跨数据库外键的允许列表
识别跨数据库外键的最简单方式是通过失败的流水线。

例如，在 [!130038](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130038/diffs) 中，我们将 `notification_settings` 表移动到 `gitlab_main_cell` 模式，通过在 `db/docs/notification_settings.yml` 文件中标记实现。

`notification_settings.user_id` 是指向 `users` 的列，但 `users` 表属于不同数据库，因此现在被视为跨数据库外键。

我们在 [`no_cross_db_foreign_keys_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/01d3a1e41513200368a22bbab5d4312174762ee0/spec/lib/gitlab/database/no_cross_db_foreign_keys_spec.rb) 中有一个规范来捕获此类跨数据库外键情况，如果遇到此类外键则会失败。

要使流水线通过，必须将此跨数据库外键加入允许列表。

为此，通过在相同规范中将其添加为异常（如[此示例](https://gitlab.com/gitlab-org/gitlab/-/blob/7d99387f399c548af24d93d564b35f2f9510662d/spec/lib/gitlab/database/no_cross_db_foreign_keys_spec.rb#L26)）显式允许现有跨数据库外键存在。这样规范就不会失败。

稍后，此外键可转换为松散外键，如我们在 [!130080](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130080/diffs) 中所做。

## 多数据库测试
在我们的测试 CI 流水线中，默认使用设置好的多个数据库（包括 `main` 和 `ci` 数据库）测试 GitLab。但在合并请求中，例如当我们修改某些数据库相关代码或为 MR 添加标签 `~"pipeline:run-single-db"` 时，我们还会在[另外两种数据库模式](../pipelines/_index.md#single-database-testing)下运行测试：`single-db` 和 `single-db-ci-connection`。

为处理测试需要在特定数据库模式下运行的情况，我们有一些 RSpec 辅助方法来限制测试可运行的模式，并在其他模式下跳过。

| 辅助方法名                                 | 测试运行环境 |
|---------------------------------------------| ---      |
| `skip_if_shared_database(:ci)`              | **多数据库**   |
| `skip_if_database_exists(:ci)`              | **单数据库** 和 **单数据库 CI 连接**   |
| `skip_if_multiple_databases_are_setup(:ci)` | 仅 **单数据库**   |
| `skip_if_multiple_databases_not_setup(:ci)` | **单数据库 CI 连接** 和 **多数据库**   |

## 锁定不属于数据库模式的表的写入
当独立数据库被提升并与主数据库分离时，为防止出现脑裂情况，作为额外保护措施，请运行 Rake 任务 `gitlab:db:lock_writes`。此命令锁定以下表的写入：
- 属于主数据库或安全数据库的 `gitlab_ci` 中的遗留表
- 属于 CI 数据库或安全数据库的 `gitlab_main` 中的遗留表
- 属于 CI 数据库或主数据库的 `gitlab_sec` 中的遗留表

此 Rake 任务为所有表添加触发器，防止对需要锁定的表执行任何 `INSERT`、`UPDATE`、`DELETE` 或 `TRUNCATE` 语句。

如果此任务在仅使用单个数据库同时包含 `gitlab_main` 和 `gitlab_ci` 表的 GitLab 设置上运行，则不会锁定任何表。

要撤销操作，运行相反的 Rake 任务：`gitlab:db:unlock_writes`。

### 监控
使用 [`Database::MonitorLockedTablesWorker`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/workers/database/monitor_locked_tables_worker.rb) 检查表锁状态。如果需要，它会锁定表。

此脚本结果可在 [Kibana](https://log.gprd.gitlab.net/app/r/s/4qrz2) 中查看。如果计数不为 0，则存在一些本应锁定但未锁定的表。字段 `json.extra.database_monitor_locked_tables_worker.results.ci.tables_need_locks` 和 `json.extra.database_monitor_locked_tables_worker.results.main.tables_need_locks` 应包含状态错误的表列表。

日志通过 [Elasticsearch Watcher](https://log.gprd.gitlab.net/app/management/insightsAndAlerting/watcher/watches) 监控。观察器名为 `table_locks_needed`，源代码在 [GitLab Runbook 仓库](https://gitlab.com/gitlab-com/runbooks/-/tree/master/elastic/managed-objects/log_gprd/watches)。警报发送到 [#g_tenant-scale](https://gitlab.enterprise.slack.com/archives/C01TQ838Y3T) Slack 频道。

### 自动化
有两个进程会自动锁定表：
- 数据库迁移。参见 [`Gitlab::Database::MigrationHelpers::AutomaticLockWritesOnTables`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/database/migration_helpers/automatic_writes_on_tables.rb)
- `Database::MonitorLockedTablesWorker` 在需要时锁定表。可通过 `lock_tables_in_monitoring` 功能标志禁用。

`Gitlab::Database::MigrationHelpers::AutomaticLockWritesOnTables` 比较每次数据库迁移运行前后的表列表，然后锁定相关数据库中新增的表。这不涵盖所有情况。因为某些迁移需要在同一事务性迁移中重新创建表。例如：将标准非分区表转换为分区表。案例参考 [此示例](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/184636)。此类迁移会重新创建表但不锁定。但 `Database::MonitorLockedTablesWorker` 的每日 cron 作业负责在 Slack 上发出警报，然后自动锁定这些表的写入。

### 手动锁定表
如果需要手动锁定表，请使用数据库迁移。创建常规迁移并添加锁定表的代码。例如，在 CI 数据库中为 `shards` 表设置写入锁：
```ruby
class EnableWriteLocksOnShards < Gitlab::Database::Migration[2.2]
  def up
    # 在主数据库上，迁移应跳过
    # 我们无法在 DDL 迁移中使用 restrict_gitlab_migration
    return if Gitlab::Database.db_config_name(connection) != 'ci'

    Gitlab::Database::LockWritesManager.new(
      table_name: 'shards',
      connection: connection,
      database_name: :ci,
      with_retries: false
    ).lock_writes
  end

  def down
    # 无操作
  end
end

$ sudo DRY_RUN=true gitlab-rake gitlab:db:truncate_legacy_tables:main
I, [2023-07-14T17:08:06.665151 #92505]  INFO -- : DRY RUN:
I, [2023-07-14T17:08:06.761586 #92505]  INFO -- : Truncating legacy tables for the database main
I, [2023-07-14T17:08:06.761709 #92505]  INFO -- : SELECT set_config('lock_writes.ci_build_needs', 'false', false)
I, [2023-07-14T17:08:06.765272 #92505]  INFO -- : SELECT set_config('lock_writes.ci_build_pending_states', 'false', false)
I, [2023-07-14T17:08:06.768220 #92505]  INFO -- : SELECT set_config('lock_writes.ci_build_report_results', 'false', false)
[...]
I, [2023-07-14T17:08:06.957294 #92505]  INFO -- : TRUNCATE TABLE ci_build_needs, ci_build_pending_states, ci_build_report_results, ci_build_trace_chunks, ci_build_trace_metadata, ci_builds, ci_builds_metadata, ci_builds_runner_session, ci_cost_settings, ci_daily_build_group_report_results, ci_deleted_objects, ci_freeze_periods, ci_group_variables, ci_instance_variables, ci_job_artifact_states, ci_job_artifacts, ci_job_token_project_scope_links, ci_job_variables, ci_minutes_additional_packs, ci_namespace_mirrors, ci_namespace_monthly_usages, ci_partitions, ci_pending_builds, ci_pipeline_artifacts, ci_pipeline_chat_data, ci_pipeline_messages, ci_pipeline_metadata, ci_pipeline_schedule_variables, ci_pipeline_schedules, ci_pipeline_variables, ci_pipelines, ci_pipelines_config, ci_platform_metrics, ci_project_mirrors, ci_project_monthly_usages, ci_refs, ci_resource_groups, ci_resources, ci_runner_machines, ci_runner_namespaces, ci_runner_projects, ci_runner_versions, ci_runners, ci_running_builds, ci_secure_file_states, ci_secure_files, ci_sources_pipelines, ci_sources_projects, ci_stages, ci_subscriptions_projects, ci_trigger_requests, ci_triggers, ci_unit_test_failures, ci_unit_tests, ci_variables, external_pull_requests, p_ci_builds, p_ci_builds_metadata, p_ci_runner_machine_builds, taggings, tags RESTRICT

sudo DRY_RUN=true gitlab-rake gitlab:db:truncate_legacy_tables:main\[10\]

sudo DRY_RUN=true UNTIL_TABLE=ci_unit_test_failures gitlab-rake gitlab:db:truncate_legacy_tables:main