InfoGrab DocsInfoGrab Docs

새 분리 데이터베이스 구축

요약

이 페이지를 사용해 GitLab Rails 애플리케이션에 새 분리(decomposed) 데이터베이스를 처음부터 끝까지 추가합니다. 분리가 무엇인지, 그리고 둘 이상의 데이터베이스를 다룰 때 일상적으로 지켜야 할 규칙에 대한 배경은 먼저 다중 데이터베이스를 읽습니다.

이 페이지를 사용해 GitLab Rails 애플리케이션에 새 분리(decomposed) 데이터베이스를 처음부터 끝까지 추가합니다. 기존 sec 데이터베이스를 실제 참조 사례로 사용하므로, 변경 사항을 실제 예시와 비교(diff)해 볼 수 있습니다.

분리가 무엇인지, 그리고 둘 이상의 데이터베이스를 다룰 때 일상적으로 지켜야 할 규칙에 대한 배경은 먼저 다중 데이터베이스를 읽습니다. 이 페이지는 해당 참조 문서의 "데이터베이스를 하나 더 추가하려면 어떻게 해야 하는가"에 대한 짝 문서입니다.

데이터 기반 데이터베이스 레지스트리#

데이터베이스 등록을 주도하는 중앙 목록은 없습니다. Gitlab::Database는 두 디렉터리를 glob 패턴으로 검색해 런타임에 데이터베이스를 찾아냅니다.

  • db/database_connections/*.yaml은 각 물리적 연결을 설명합니다 (lib/gitlab/database.rb의 all_database_connection_files 참조).
  • db/gitlab_schemas/*.yaml은 각 논리적 gitlab_schema를 설명합니다 (같은 파일의 all_gitlab_schema_files 참조).

EE도 ee/db 아래의 같은 두 디렉터리를 glob 패턴으로 검색합니다.

all_database_connections, all_database_names, database_base_models 같은 모든 하위 요소는 이 파일들에서 만들어집니다. has_config?는 예외로, config/database.yml에 구성된 연결을 읽습니다. 데이터베이스를 추가할 때 핵심은, 중앙 목록을 편집하는 것이 아니라 glob 패턴이 찾아내는 YAML 파일을 추가해 데이터베이스를 등록한다는 점입니다. 일부 위치에는 여전히 데이터베이스를 수동으로 나열하며, 하드코딩된 데이터베이스 목록에 데이터베이스 추가에서 이를 다룹니다.

YAML은 구조체(struct)로 파싱됩니다.

시작하기 전에#

새 분리 데이터베이스는 대개 데이터 모델과 롤아웃을 추적하는 분리 에픽과 함께 진행됩니다. 예를 들어 main과 ci는 에픽 6168에서, sec는 에픽 13043에서 분리됐습니다. 시작하기 전에 Database Frameworks 그룹 및 Tenant Scale 그룹과 조율합니다.

단계별 체크리스트#

다음 단계는 foo라는 가상의 데이터베이스와 그에 대응하는 gitlab_foo 스키마를 사용합니다. 이름은 전체에서 사용하는 이름으로 바꿔 적용합니다. 순서가 중요합니다. 스키마와 연결이 먼저 존재해야, 이를 강제하는 spec이 통과할 수 있습니다.

gitlab_schema 정의 추가#

db/gitlab_schemas/gitlab_foo.yaml을 만듭니다.

name: gitlab_foo
description: Schema for the Foo feature tables.
allow_cross_joins:
  - gitlab_shared
  - gitlab_shared_org
  - gitlab_shared_cell_local
allow_cross_transactions:
  - gitlab_internal
  - gitlab_shared
  - gitlab_shared_org
  - gitlab_shared_cell_local
require_sharding_key: true
sharding_root_tables:
  - projects
  - organizations
  - namespaces

데이터베이스가 cell-local 참조 데이터도 보관한다면, db/gitlab_schemas/gitlab_sec_cell_local.yaml을 참고해 db/gitlab_schemas/gitlab_foo_cell_local.yaml 같은 두 번째 스키마를 추가합니다. 또한 lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb의 SCHEMA_MAPPING에 gitlab_foo_cell_local: :gitlab_foo를 추가합니다. 이 매핑이 없으면 gitlab_foo로 제한된 마이그레이션이 gitlab_foo_cell_local 테이블에 쓸 때 DMLAccessDeniedError가 발생합니다.

연결 정의 추가#

db/database_connections/foo.yaml을 만듭니다.

name: foo
description: GitLab database holding Foo feature related tables.
gitlab_schemas:
  - gitlab_internal
  - gitlab_shared
  - gitlab_shared_org
  - gitlab_shared_cell_local
  - gitlab_foo
  - gitlab_foo_cell_local # only if you created it
lock_gitlab_schemas:
  - gitlab_main
  - gitlab_main_cell_setting
  - gitlab_main_user
  - gitlab_main_org
  - gitlab_main_cell_local
  - gitlab_main_jh
  - gitlab_ci
  - gitlab_ci_cell_local
  - gitlab_pm
  - gitlab_sec
  - gitlab_sec_cell_local
klass: FooApplicationRecord
# if the Foo database is not configured, use this database
fallback_database: main
uses_load_balancing: true

주요 필드는 다음과 같습니다.

  • gitlab_schemas: 테이블이 이 데이터베이스에 있는 스키마입니다.
  • lock_gitlab_schemas: 다른 데이터베이스에 속한 스키마입니다. gitlab:db:lock_writes Rake 태스크가 이 데이터베이스에서 해당 테이블을 쓰기 잠금해, 데이터가 어긋나지 않게 합니다.
  • klass: 이 연결을 소유하는 추상 기본 모델입니다 (기본 모델 추가 참조).
  • fallback_database: main: 별도의 foo 연결이 구성되지 않은 경우 Foo 스키마가 main 연결에 매핑되므로, 애플리케이션이 단일 데이터베이스 모드로 실행될 수 있습니다. 모델은 기본 모델의 has_config? 가드를 통해 main에 접근합니다. 이 필드는 dev:copy_db:foo Rake 태스크도 정의합니다.
  • db_dir은 선택 사항이며 기본값은 db입니다. 달리 해야 할 이유가 없다면 공유 db 디렉터리를 재사용합니다 (공유 마이그레이션 관련 주의 사항 참조).

새 파일은 Gitlab::Database.all_database_names에도 foo를 추가합니다. 데이터베이스 API 엔드포인트가 이 목록을 매개변수의 허용 값으로 사용하므로 OpenAPI 문서가 변경됩니다. bin/rake gitlab:openapi:v3:generate를 실행하고 업데이트된 doc/api/openapi/openapi_v3.yaml을 커밋합니다. 그러지 않으면 CI에서 bin/rake gitlab:openapi:v3:check_docs가 실패합니다.

db/database_connections/foo.yaml을 추가하면 관리자용 배치 백그라운드 마이그레이션 및 백그라운드 작업 API 엔드포인트가 foo를 데이터베이스 이름으로 허용합니다. config/database.yml에 foo 항목이 없으면 이 엔드포인트는 foo에 대해 500 오류를 반환합니다. 자세한 내용은 이슈 637961을 참조합니다.

다른 데이터베이스에 새 스키마 등록#

기존 연결마다 새 스키마를 lock_gitlab_schemas에 추가해, 해당 데이터베이스가 쓰면 안 되는 Foo 테이블을 잠그도록 합니다. 다음 파일을 편집합니다.

  • db/database_connections/main.yaml
  • db/database_connections/ci.yaml
  • db/database_connections/sec.yaml

각 lock_gitlab_schemas 목록에 gitlab_foo를 추가합니다. gitlab_foo_cell_local을 만들었다면 이것도 추가합니다.

기본 모델 추가#

app/models/sec_application_record.rb를 참고해 app/models/foo_application_record.rb를 만듭니다.

# frozen_string_literal: true

class FooApplicationRecord < ApplicationRecord
  self.abstract_class = true

  connects_to database: { writing: :foo, reading: :foo } if Gitlab::Database.has_config?(:foo)
end

has_config?(:foo) 가드가 단일 데이터베이스 모드를 안전하게 만듭니다. foo 연결이 구성되지 않았다면 모델은 connects_to를 호출하지 않고 ApplicationRecord를 통해 main을 상속합니다. 같은 패턴을 쓰는 app/models/ci/application_record.rb와 비교해 봅니다.

rspec:coverage job의 언더커버리지 검사는 기본 RSpec job의 커버리지를 사용합니다. 이 job들은 foo를 구성하지 않으므로 connects_to 분기가 실행되지 않습니다. 검사가 해당 분기를 커버되지 않은 것으로 보고해 job이 실패합니다. 하드코딩된 데이터베이스 목록에 추가하는 코드도 같은 방식으로 실패할 수 있습니다. 머지 리퀘스트에 pipeline:skip-undercoverage 레이블을 적용하고 새 파이프라인을 시작합니다. 자세한 내용은 rspec:coverage job의 언더커버리지 검사를 참조합니다.

테스트 테이블 접두사 등록#

lib/gitlab/database/gitlab_schema.rb의 IMPLICIT_GITLAB_SCHEMAS에 테스트 테이블용 암시적 스키마 매핑을 추가합니다.

'_test_gitlab_foo_' => :gitlab_foo,

해시에서는 순서가 중요합니다. 다른 접두사를 포함하는 접두사가 먼저 와야 합니다.

structure.sql 심링크 추가#

db/sec_structure.sql과 db/ci_structure.sql이 심링크인 것과 같은 방식으로, 공유 db/structure.sql에 대한 심링크로 db/foo_structure.sql을 만듭니다.

ln -s structure.sql db/foo_structure.sql

config/database.yml 템플릿에 연결 추가#

config/database.yml은 커밋되지 않습니다. foo용 템플릿을 커밋 대상으로 만듭니다. 예를 들어 config/database.yml.decomposed-foo-postgresql입니다. config/database.yml.decomposed-sec-postgresql을 기반으로 하고, 각 환경의 sec: 블록 옆에 foo: 블록을 추가합니다. 사용자 지정 migrations_paths 또는 schema_migrations_path는 설정하지 않습니다. geo와 embedding만 이를 재정의합니다. 자세한 내용은 공유 마이그레이션과 structure.sql 재사용을 참조합니다.

CI에서는 scripts/utils.sh의 setup_database_yml이 DECOMPOSED_DB 및 SEC_DECOMPOSED_DB 변수에 따라 템플릿을 config/database.yml로 복사합니다. .gitlab-ci.yml의 전역 variables는 둘 다 "true"로 설정합니다. foo에 대해 CI job을 실행하려면 FOO_DECOMPOSED_DB 같은 변수와, foo 템플릿을 복사하는 setup_database_yml의 분기를 추가합니다. 로컬 config/database.yml은 GDK에서 새 데이터베이스 실행을 참조합니다.

새 테이블의 딕셔너리 항목 추가#

각 테이블은 db/docs/<table>.yml의 gitlab_schema 아래에 스키마를 기록합니다. foo에 만드는 테이블의 항목을 생성합니다.

bin/rake gitlab:db:dictionary:generate

이 태스크는 gitlab_schema를 설정하지 않습니다. 새 항목은 이 값 없이 생성되며, 직접 gitlab_schema: gitlab_foo를 추가하기 전까지 UnknownSchemaError가 발생합니다. 이미 있는 항목은 태스크가 classes에 클래스 이름만 추가하므로 테이블의 스키마를 바꾸지 않습니다. 기존 테이블을 이동하려면 기존 테이블 이동을 참조합니다.

하드코딩된 데이터베이스 목록에 데이터베이스 추가#

다음 파일은 레지스트리를 읽지 않고 main, ci, sec를 문자 그대로 지정합니다. 각각에 foo를 추가합니다.

  • lib/tasks/gitlab/db.rake: gitlab:db:migration_testing 태스크를 정의하는 all_databases 배열입니다. spec/tasks/gitlab/db_rake_spec.rb는 구성된 모든 데이터베이스에 대해 이 태스크가 있어야 하므로, 항목이 빠지면 여기서 실패합니다.

  • lib/tasks/gitlab/db/truncate_legacy_tables.rake: sec 태스크를 따라 만드는 gitlab:db:truncate_legacy_tables:foo 태스크입니다.

  • lib/gitlab/database/tables_truncate.rb: 지원되는 데이터베이스 목록입니다. foo가 없으면 foo에 속하지 않는 테이블을 트런케이션할 때 database is not supported가 발생해 물리적 분리가 막힙니다.

  • lib/tasks/gitlab/db/schema_load_fix.rake: 임시 해결책이 적용되는 데이터베이스 목록입니다.

  • spec/support/multiple_databases.rb: spec이 데이터베이스 버전을 메모이즈하는 기본 모델 목록입니다. FooApplicationRecord를 추가합니다.

  • app/workers/loose_foreign_keys/cleanup_worker.rb: 터보 모드 목록입니다. config/feature_flags/ops/loose_foreign_keys_turbo_mode_sec.yml 옆에 loose_foreign_keys_turbo_mode_foo ops 기능 플래그도 추가합니다.

  • lib/gitlab/sidekiq_limits.rb: 데이터베이스별 처리 시간 제한입니다. sec_db_duration_limit_per_worker를 따라 foo 항목을 추가합니다. 그런 다음 lib/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits.rb에서 sec 규칙 옆에 foo_db_duration_limit_per_worker 규칙을 추가하고, 해당 키를 cost_mode_keys에 추가합니다. 규칙이 없으면 기능 플래그가 켜져 있을 때 Sidekiq 리소스 사용량 및 스로틀링 미들웨어가 모든 job에 대해 KeyError를 발생시킵니다. cost_mode_keys 항목이 없으면 제한이 적용되지 않습니다.

  • lib/gitlab/database/retention_policy.rb: ELIGIBLE_SCHEMAS 또는 EXCLUDED_SCHEMAS입니다. gitlab_foo와, 만들었다면 gitlab_foo_cell_local을, 각각을 사용하는 첫 db/docs 항목과 같은 머지 리퀘스트에서 추가합니다. spec/db/retention_policy_definitions_spec.rb는 db/docs의 스키마가 두 목록 어디에도 없으면 실패합니다. EE에서는 목록에 있는 스키마에 테이블이 없을 때도 실패합니다.

  • lib/gitlab/database/health_status/indicators/prometheus_alert_indicator.rb: sec에 자체 Prometheus 쿼리를 제공하거나, 쿼리가 없으면 main 쿼리를 제공하는 특수 케이스입니다. foo 케이스가 없거나 prometheus_alert_db_indicators_settings 애플리케이션 설정에 foo 쿼리가 없으면, 인디케이터는 foo에 대해 알 수 없음 신호를 반환합니다. spec/support/shared_examples/database_health_status_indicators/prometheus_alert_based_shared_examples.rb의 공유 예시는 구성된 모든 데이터베이스를 순회하며 sec만 건너뜁니다. 여기서도 foo를 처리해야 합니다. 그러지 않으면 foo가 자체 연결을 가진 뒤 인디케이터 spec이 NoMethodError로 실패합니다.

  • 배치 백그라운드 마이그레이션 및 백그라운드 작업 워커입니다. 각 데이터베이스가 자체 워커를 실행하므로, sec 워커를 복사해 foo용으로 이름을 바꿉니다.

    • app/workers/database/batched_background_migration/sec_database_worker.rb 및 sec_execution_worker.rb
    • app/workers/database/background_operation/sec_scheduler_worker.rb, sec_orchestrator_worker.rb와 그 _cell_local 변형

    워커는 FOO_DATABASE_NAME 상수를 읽으며, lib/gitlab/database.rb의 SEC_DATABASE_NAME 옆에 이 상수를 추가합니다. sec 항목 옆의 config/schedule.yml에 해당 cron 항목을 추가합니다. Cron job 기본값은 더 이상 config/initializers/1_settings.rb에 없습니다. 그런 다음 bin/rake gitlab:sidekiq:all_queues_yml:generate를 실행합니다. 이 워커가 없으면 foo에 큐잉된 배치 백그라운드 마이그레이션과 백그라운드 작업이 실행되지 않습니다.

    이 워커와 관련해 sec를 문자 그대로 지정하는 곳이 두 군데 더 있습니다.

    • lib/gitlab/sidekiq_middleware/size_limiter/validator.rb의 EXEMPT_WORKER_NAMES에는 Database::BatchedBackgroundMigration::SecDatabaseWorker가 있습니다. Database::BatchedBackgroundMigration::FooDatabaseWorker를 추가합니다.
    • spec/support/shared_examples/workers/batched_background_migration_worker_shared_examples.rb의 case tracking_database에는 foo 분기가 없습니다. 분기를 추가하지 않으면 foo가 자체 연결을 가진 뒤 복사한 워커 spec이 NoMethodError로 실패합니다.

공유 마이그레이션과 structure.sql 재사용#

마이그레이션 레이아웃은 가장 흔히 실수하는 부분입니다.

foo 같은 새 분리 데이터베이스는 공유 db/migrate, db/post_migrate, db/schema_migrations를 재사용합니다. 자체 마이그레이션 디렉터리를 갖지 않습니다. 데이터 정의 언어(DDL)는 구성된 모든 데이터베이스에 대해 실행됩니다. restrict_gitlab_migration에 스키마를 선언한 마이그레이션은 해당 스키마를 보유하지 않은 데이터베이스에서는 완전히 건너뜁니다. 공유 마이그레이션 때문에 db/foo_structure.sql은 단일 공유 db/structure.sql에 대한 심링크입니다.

예외는 geo와 embedding이며, 이들은 자체 ee/db/<name>/migrate 디렉터리를 갖습니다. 이 경로는 lib/gitlab/patch/database_config.rb에서 명시적으로 연결되며, 이 파일은 embedding과 geo에만 사용자 지정 migrations_paths를 추가합니다. 이와 비슷한 것을 만드는 경우가 아니라면 이들의 레이아웃을 따르지 않습니다.

둘 이상의 데이터베이스를 다루는 마이그레이션을 작성하는 규칙은 여러 데이터베이스를 위한 마이그레이션을 참조합니다.

기존 테이블 이동#

사전 요구 사항:

foo_bar를 foo로 이동하려면 다음을 수행합니다.

  1. db/docs/foo_bar.yml에서 gitlab_schema를 gitlab_foo로 변경합니다. foo가 구성되었든 아니든 크로스 데이터베이스 검사가 이 테이블에 즉시 적용됩니다. 데이터베이스 경계를 강제하는 검사를 참조합니다.
  2. 이 테이블을 사용하는 각 모델이 ApplicationRecord 대신 FooApplicationRecord를 상속하도록 변경합니다. 변경하기 전에는 foo가 구성된 후에도 모델이 계속 main 연결을 사용합니다. sec의 경우 데이터베이스의 모든 모델이 SecApplicationRecord를 상속합니다. 예를 들어 ee/app/models/dast/pre_scan_verification.rb가 있습니다.
  3. bin/rake gitlab:db:dictionary:generate를 실행해 항목의 classes를 갱신합니다.
  4. 다음 절에 설명된 대로, 이 테이블을 참조하는 릴리스된 마이그레이션을 업데이트합니다.

릴리스된 마이그레이션이 참조하는 테이블 재배치#

기존 테이블을 새 데이터베이스로 이동하면 두 번째 문제를 물려받습니다. 이미 배포된 마이그레이션이 여전히 테이블의 이전 스키마를 선언하고 있다는 점입니다.

데이터 마이그레이션은 쓸 수 있는 스키마를 선언합니다.

class BackfillFooBarProjectId < Gitlab::Database::Migration[2.2]
  restrict_gitlab_migration gitlab_schema: :gitlab_main_org
end

foo_bar의 db/docs 항목이 gitlab_main_org에서 gitlab_foo로 바뀌면 이 선언은 더 이상 맞지 않습니다. 마이그레이션은 이미 릴리스되었으므로 해당 버전을 거쳐 업그레이드하는 GitLab Self-Managed 인스턴스에서 여전히 실행될 수 있으며, 그때 Gitlab::Database::QueryAnalyzers::RestrictAllowedSchemas::DMLAccessDeniedError가 발생합니다.

테이블의 db/docs 항목을 옮기는 커밋과 같은 커밋에서, 릴리스된 마이그레이션의 어노테이션을 새 스키마로 업데이트합니다. 선례는 커밋 b5b3f96b585a로, Secure 및 Govern 분리에서 딕셔너리 변경과 함께 QueueBackfillSbomOccurrencesVulnerabilitiesProjectId를 :gitlab_main_cell에서 :gitlab_sec로 바꿨습니다.

릴리스된 마이그레이션을 수정하는 것이 이상하게 느껴지므로 그렇지 않은 이유를 분명히 밝혀 둘 가치가 있습니다. restrict_gitlab_migration은 마이그레이션을 작성할 당시 테이블이 어디에 있었는지에 대한 과거 기록이 아닙니다. 마이그레이션이 실행될 때 읽어, 어느 연결이 데이터 조작 언어를 실행할 수 있는지 결정하는 런타임 허용 목록입니다. 값은 테이블이 현재 있는 위치를 나타내야 하며, 그렇지 않으면 마이그레이션이 아예 실행될 수 없습니다. 스키마 이력은 db/structure.sql과 마이그레이션 자체의 DDL에 있으며, 둘 다 이 변경의 영향을 받지 않습니다.

어노테이션은 눈에 보이는 실패입니다. 다른 두 가지는 발견하기 더 어려우므로 의도적으로 확인합니다.

선언만이 아니라 인수로 전달되는 스키마#

일부 마이그레이션은 restrict_gitlab_migration에서 스키마를 선언할 뿐 아니라 queue_batched_background_migration에도 전달합니다.

queue_batched_background_migration(
  MIGRATION,
  :foo_bar,
  :id,
  gitlab_schema: :gitlab_main_org,
  ...
)

오래된 어노테이션은 DMLAccessDeniedError로 요란하게 실패하고, 빨간색 파이프라인이 이를 찾아냅니다. 오래된 인수는 조용히 실패할 수 있습니다. 큐에 들어간 행은 전달한 스키마를 저장하지만, ensure_batched_background_migration_is_finished와 finalize_batched_background_migration은 restrict_gitlab_migration의 스키마로 행을 조회합니다. 두 값이 다르면 어느 쪽도 행을 찾지 못합니다. finalize_batched_background_migration은 Could not find batched background migration을 발생시킵니다. ensure_batched_background_migration_is_finished는 경고를 로그에 남기고 백필이 이미 끝난 것처럼 반환합니다. DBLAB_ENVIRONMENT가 설정된 경우에만 예외를 발생시킵니다. 이동하는 테이블의 마이그레이션에서 모든 gitlab_schema: 인수와 어노테이션을 grep으로 찾아 둘 다 바꿉니다.

스키마가 레이블 없는 위치 인수일 수도 있습니다. 예를 들어 BatchedMigration.for_configuration(:gitlab_main_org, MIGRATION, ...)가 그렇습니다. gitlab_schema:로 grep하면 찾을 수 없습니다. :gitlab_main_org 같은 이전 스키마 심볼 자체를 grep합니다.

마이그레이션 spec도 migration: :gitlab_main_org RSpec 메타데이터와, spec이 만드는 배치 백그라운드 마이그레이션 레코드에 스키마 이름을 사용합니다. 메타데이터와 레코드도 업데이트합니다. spec 헬퍼는 마이그레이션 테스트 기간 밖에 있는 오래된 마이그레이션의 spec을 건너뜁니다. 이를 실행하려면 RUN_ALL_MIGRATION_TESTS=1을 설정합니다.

RUN_ALL_MIGRATION_TESTS=1 bundle exec rspec spec/migrations/<migration>_spec.rb

이전 스키마로 이미 큐에 들어간 백필#

batched_background_migrations는 gitlab_schema 텍스트 칼럼을 저장하며, 이 값은 job을 큐에 넣을 때 적용되던 스키마에서 가져와 기록됩니다. 마이그레이션 소스를 수정해도 기존 행은 다시 쓰이지 않습니다. 따라서 이동하는 테이블에 대해 이미 큐에 들어간 백필은 이전 스키마 문자열을 유지하며, db/docs 변경 후 파인더가 저장된 값을 새 연결의 스키마와 대조해 걸러내므로 더 이상 해당 job을 볼 수 없게 됩니다.

소스를 수정해도 테이블에 이미 있는 데이터는 고칠 수 없습니다. 이전 스키마를 가진 큐 행이 없도록, 이동하는 테이블의 db/docs 항목을 변경하기 전에 진행 중인 백필을 완료 처리합니다. 그럴 수 없다면 행을 데이터 마이그레이션으로 수정하거나, 진행 중인 것이 없는 시점에 맞춰 db/docs 변경 순서를 잡아야 합니다. db/docs 변경을 머지하기 전에 이동하는 테이블 이름으로 필터링한 batched_background_migrations 쿼리로 큐에 남은 것이 없는지 확인합니다.

테이블 이동 시 기타 확인 사항#

테이블을 이동할 때 다음을 확인합니다.

  • 가장 최근 것만이 아니라, 이동하는 테이블을 다루는 릴리스된 모든 마이그레이션과 백그라운드 마이그레이션 클래스를 점검합니다. db/migrate, db/post_migrate, lib/gitlab/background_migration에서 테이블 이름을 grep합니다.

  • 이제 두 데이터베이스에 걸쳐 나뉜 테이블을 다루는 마이그레이션은 단일 restrict_gitlab_migration을 유지할 수 없습니다. 마이그레이션을 분리하거나, 크로스 데이터베이스 부분을 애플리케이션 코드로 옮깁니다. 여러 데이터베이스를 위한 마이그레이션을 참조합니다.

  • config/initializers/postgres_partitioning.rb가 limit_connection_names: %i[main]과 함께 register_tables로 테이블을 등록한다면, 파티션 동기화가 구성된 곳에서는 foo에 도달하고 구성되지 않은 곳에서는 main을 유지하도록 합니다. 예를 들면 다음과 같습니다.

    limit_connection_names: Gitlab::Database.has_config?(:foo) ? %i[foo] : %i[main],
    

    main을 foo로 대체하지 않습니다. 프로덕션에서 파티션 동기화는 목록에 지정된 구성된 연결에서만 실행되므로, foo가 main으로 폴백하는 곳에서는 파티션을 동기화하는 것이 없습니다. 어느 쪽이든 여유 파티션이 소진되면 쓰기가 실패하기 시작합니다. %i[main foo]도 동작하지만, 분리 후에도 main의 사본에 계속 파티션을 만듭니다. register_models로 등록한 테이블은 모델의 연결을 따르므로 변경이 필요 없습니다. 프로덕션 외 환경에서는 파티션 동기화가 다른 연결에도 파티션을 만들기 때문에, 놓친 항목이 GDK와 CI에서는 여전히 정상으로 보입니다.

  • Siphon이 해당 테이블을 복제한다면 db/siphon/tables/<table>.yml의 database:를 foo로 변경합니다. 해당 데이터베이스가 테이블의 gitlab_schema를 보유하지 않으면 spec/db/clickhouse_siphon_tables_spec.rb가 실패합니다.

  • 이동하는 테이블에 대해 defer_on_database_health_signal을 호출하는 워커는 여전히 이전 스키마를 선언합니다. 상태 점검은 이 스키마로 연결을 고르므로, 분리 후에는 이전 데이터베이스를 감시하게 되며 아무것도 실패하지 않습니다. app/workers와 ee/app/workers에서 이전 스키마와 함께 defer_on_database_health_signal을 grep합니다. 이동하는 테이블을 다루는 각 워커의 스키마를 gitlab_foo로 변경합니다. 일부 워커는 테이블을 나열하지 않으므로 테이블 이름만 grep하면 놓칠 수 있습니다. 예시는 이슈 631673을 참조합니다.

GDK에서 새 데이터베이스 실행#

데이터를 이동하기 전에, GDK에서 foo를 켠 상태로 이동하는 테이블의 spec을 실행해야 합니다. 데이터베이스 경계를 강제하는 검사에 설명된 대로, CI 검사가 잘못된 연결의 모든 쿼리를 잡아내지는 못합니다. 허용 목록에 항목이 남아 있는 동안에는 크로스 조인과 오래된 사본에 설명된 대로 평소에는 foo를 꺼 둡니다.

GDK는 다음 파일에 각 데이터베이스를 수동으로 나열합니다.

  • lib/gdk/config.rb
  • support/templates/gitlab/config/database.yml.erb
  • lib/support/bootstrap_rails.rb
  • lib/gdk/command/truncate_legacy_tables.rb
  • lib/gdk/task_helpers/rails_migration.rb

GDK 머지 리퀘스트가 이 파일들에 foo를 추가하기 전까지는 gitlab.rails.databases.foo 설정이 존재하지 않으며 gdk config set으로 foo를 켤 수 없습니다. GDK는 AGENTS.md에 설명된 대로 더 이상 새 기능을 받지 않으므로, 해당 머지 리퀘스트는 GDK 메인테이너가 예외를 승인해야 합니다. GDK가 foo를 지원하기 전까지는 다음 절에 설명된 대로 직접 구성합니다.

GDK는 새 작업을 Caproni로 안내하는데, Caproni는 foo 같은 새 데이터베이스를 설정하지 않습니다. 자세한 내용은 Caproni 이슈 57을 참조합니다.

GDK가 데이터베이스를 지원하기 전#

GDK가 지원하기 전에 foo를 실행하려면 다음을 수행합니다.

  1. sec: 항목을 따라 각 환경마다 gitlab/config/database.yml에 foo: 블록을 추가합니다. 각 블록에서 데이터베이스 이름만 변경합니다. 예를 들어 test 블록에서는 gitlabhq_test_foo를 사용합니다.

  2. GDK는 템플릿에서 gitlab/config/database.yml을 다시 생성하며 직접 편집한 내용을 덮어씁니다. diff를 보여 주고 이전 파일을 백업하지만, 변경 내용은 config/database.yml에서 사라집니다. 변경 내용을 유지하려면 gdk.yml에서 이 파일을 보호합니다.

    gdk:
      protected_config_files:
        - 'gitlab/config/database.yml'
    
  3. gitlab 디렉터리에서 GDK의 bootstrap_sec_db가 sec에 대해 하는 것과 같은 방식으로 데이터베이스를 만들고, 속하지 않는 테이블을 비웁니다.

    bin/rake dev:copy_db:foo
    bin/rake gitlab:db:lock_writes
    bin/rake gitlab:db:truncate_legacy_tables:foo
    bin/rake gitlab:db:unlock_writes
    

    dev:copy_db:foo는 main을 복사합니다. 이 태스크는 연결 정의를 추가하고 config/database.yml에 foo 항목이 있어야 정의됩니다. 트런케이션 태스크는 하드코딩된 데이터베이스 목록의 변경이 필요합니다.

  4. foo에 대해 spec을 실행하려면 테스트 데이터베이스를 준비합니다.

    RAILS_ENV=test bin/rake db:test:prepare
    
  5. 이동하는 각 모델이 새 연결을 사용하는지 확인합니다.

    RAILS_ENV=test bin/rails runner 'puts FooBar.connection_db_config.name'
    

    이 명령은 foo를 출력합니다. main을 출력한다면 모델이 FooApplicationRecord를 상속하지 않았거나, config/database.yml의 test 환경에 foo 항목이 없는 것입니다.

GDK가 데이터베이스를 지원한 후#

protected_config_files에서 gitlab/config/database.yml을 제거합니다. 그런 다음 플래그를 설정하고 GDK를 다시 구성합니다.

gdk config set gitlab.rails.databases.foo.enabled true
gdk reconfigure

대신 단일 데이터베이스 모드로 실행하려면 플래그를 false로 설정하고 gdk reconfigure를 실행합니다. 기존 인스턴스에서 모드를 전환할 때의 주의 사항은 단일 데이터베이스 구성을 참조합니다.

크로스 조인과 오래된 사본#

크로스 데이터베이스 허용 목록에 항목이 남아 있는 동안에는, 이를 제거하는 작업을 하거나 데이터를 이동하기 전 최종 점검을 할 때에만 GDK에서 foo를 켭니다. foo를 켜면 main을 거치는 남은 크로스 조인마다, 허용 목록에 있든 없든 웹 요청, Sidekiq job, spec에서 CrossSchemaAccessError가 발생합니다.

Warning

Rails 콘솔, rails runner, 대부분의 Rake 태스크에서는 크로스 데이터베이스 조인이 정상으로 보이는 결과를 반환할 수 있어 문제가 가려집니다. dev:copy_db는 main을 템플릿으로 새 데이터베이스를 만듭니다. 새 데이터베이스에 속하지 않는 테이블을 트런케이션해도 main에는 foo 테이블의 사본이 남아 있으므로, foo에 대한 쓰기로 둘이 달라지기 전까지는 main을 거치는 조인이 그 사본을 읽습니다. GDK의 웹 요청과 Sidekiq job은 같은 쿼리에서 대신 CrossSchemaAccessError가 발생합니다.

main에 있는 foo 테이블의 사본을 비우려면 gitlab:db:lock_writes Rake 태스크를 실행한 다음 gitlab:db:truncate_legacy_tables:main을 실행합니다. 트런케이션 태스크는 대상 테이블이 쓰기 잠금되기 전에는 실행을 거부합니다. main에서 속하지 않는 모든 테이블을 트런케이션하므로, main에 있는 ci 및 sec 테이블의 사본도 비웁니다.

다른 설치 방법에 데이터베이스 추가#

앞 절의 변경은 GitLab Rails 애플리케이션과 GDK를 바꿉니다. Linux 패키지, GitLab Helm 차트, Instrumentor는 각각 데이터베이스를 별도로 구성합니다. 이 중 하나가 foo를 지원하기 전까지는 이를 사용해 별도의 foo 데이터베이스를 구성할 수 없습니다. 이 경우 foo 스키마는 main 연결을 사용합니다.

각 설치 방법별 작업은 다음과 같습니다.

  • Linux 패키지: files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb의 ALLOWED_DATABASES에 foo를 추가합니다. 이 변경이 없으면 gitlab-ctl reconfigure가 gitlab_rails['databases']['foo']를 무시하고 경고를 로그에 남깁니다. 예시는 sec를 추가한 omnibus-gitlab 머지 리퀘스트 7727을 참조합니다.
  • GitLab Helm 차트: values.yaml의 global.psql.knownDecompositions에 foo를 추가합니다. 차트는 이 목록에 있는 데이터베이스에 대해서만 클라우드 네이티브 GitLab 이미지용 config/database.yml을 생성합니다. 예시는 sec를 추가한 charts/gitlab 머지 리퀘스트 3807을 참조합니다.
  • GitLab Dedicated 및 Cells: 내부 프로비저닝 도구인 Instrumentor에 foo를 추가하도록 GitLab Dedicated 팀에 요청합니다. Instrumentor는 데이터베이스마다 데이터베이스를 만들고, PgBouncer 풀을 추가하고, GitLab Helm 차트 값을 설정합니다. Cells의 경우 Cells Infrastructure 팀에도 문의합니다.
  • GitLab.com 레거시 cell: 분리는 예정된 프로덕션 변경입니다. sec 분리는 프로덕션 변경 요청 19581을 참조합니다.

Docker 설치는 Linux 패키지를 사용하고, GitLab Operator는 GitLab Helm 차트를 사용합니다. 별도의 변경이 필요하지 않습니다.

데이터베이스 경계를 강제하는 검사#

단계를 놓치면 여러 spec이 실패하는데, 이는 의도된 기능입니다. 일관성 없는 데이터베이스가 머지되는 것을 막습니다.

  • 데이터베이스 딕셔너리는 모든 테이블이 알려진 gitlab_schema에 매핑되도록 요구합니다. Gitlab::Database::Dictionary는 매핑되지 않은 테이블에 대해 UnknownSchemaError를 발생시킵니다.
  • spec/db/docs_spec.rb와 spec/db/schema_spec.rb는 딕셔너리와 structure.sql이 일관된지 검증합니다.
  • spec/lib/gitlab/database/gitlab_schema_spec.rb는 스키마 정의와 암시적 테스트 테이블 접두사를 검증합니다.
  • spec/lib/gitlab/database/database_connection_info_spec.rb는 연결 YAML이 파싱되고 기본 클래스를 해석하는지 검증합니다.

앞의 검사는 잘못 연결된 레지스트리를 잡아냅니다. 다른 세 가지는 새 데이터베이스가 구성되지 않았더라도 db/docs 항목에서 테이블의 gitlab_schema를 변경하자마자 실패합니다. 이 검사들은 새 데이터베이스의 연결이 아니라 데이터베이스 딕셔너리에서 각 테이블의 스키마를 읽습니다. !130038에서는 db/docs 항목에서 notification_settings를 gitlab_main에서 gitlab_main_cell(이후 gitlab_main_org로 이름이 바뀜)로 옮기는 것만으로 파이프라인이 실패했습니다.

  • spec/support/database/prevent_cross_joins.rb는 스키마가 allow_cross_joins에 짝지어 있지 않은 테이블을 조인하는 모든 쿼리를 실패시킵니다.
  • lib/gitlab/database/query_analyzers/prevent_cross_database_modification.rb는 스키마가 allow_cross_transactions에 짝지어 있지 않은 테이블을 수정하는 모든 트랜잭션을 실패시킵니다.
  • spec/lib/gitlab/database/no_cross_db_foreign_keys_spec.rb는 스키마가 allow_cross_foreign_keys에 짝지어 있지 않은 테이블 간의 모든 외래 키를 실패시킵니다. 단, 해당 칼럼이 spec의 allowed_cross_database_foreign_keys에 나열된 경우는 제외합니다.

fallback_database는 이를 바꾸지 않습니다. fallback_database는 데이터베이스가 구성되지 않았을 때 새 스키마를 어느 연결이 처리할지 결정합니다. 그 덕분에 GitlabSchemasValidateConnection 같은 연결 기반 분석기는 계속 통과하지만, 이 세 검사는 스키마만 비교합니다.

fallback_database에서 파이프라인이 녹색이라고 해서 이동이 끝난 것은 아닙니다. 세 검사는 gitlab_schema를 둘 이상 건드리는 구문에만 작동하므로, 잘못된 연결에서 실행되는 단일 테이블 쿼리는 놓칩니다. 예를 들어 ApplicationRecord.legacy_bulk_insert('foo_bar', rows)는 main을 통해 삽입합니다. legacy_bulk_insert가 호출 대상 클래스의 연결을 사용하기 때문입니다. 데이터베이스가 하나일 때는 스위트가 통과합니다. 이를 잡아내는 것은 GitlabSchemasValidateConnection뿐이며, foo가 자체 연결을 가진 뒤에야 가능합니다.

호출을 고치려면 대신 모델에서 메서드를 호출합니다. 예를 들어 FooBar.legacy_bulk_insert('foo_bar', rows)입니다. 이동하는 테이블을 지정하는, ApplicationRecord 또는 ApplicationRecord.connection을 통한 모든 쓰기를 검색합니다.

데이터를 이동하기 전에, GDK에서 새 데이터베이스 실행에 설명된 대로 foo를 켠 상태로 이동하는 테이블의 spec을 실행합니다.

기존 크로스 데이터베이스 위반 허용 목록 등록#

기존 위반을 허용 목록에 등록하는 방법은 위반 수에 따라 달라집니다. 수가 적으면 발생 위치마다 허용 목록에 등록하고 이슈와 연결합니다.

수천 건이 있으면 호출 지점마다 표시하는 일은 그 자체로 하나의 프로젝트입니다. 대신 실패하는 spec 파일을 spec/support/database/cross-join-allowlist.yml과 spec/support/database/cross-database-modification-allowlist.yml에 나열합니다. CI 분리는 앞의 것에 418개, 뒤의 것에 1,340개의 spec 파일로 시작해 1년 안에 둘 다 비웠습니다. CI는 목록에 있는 spec 파일에 대해서는 어떤 데이터베이스든 이 검사를 실행하지 않으므로, 해당 파일의 새 위반은 눈에 띄지 않습니다. 목록을 백로그로 취급하고 비워질 때까지 처리합니다. 외래 키에는 파일별 목록이 없으므로 항상 allowed_cross_database_foreign_keys에 넣습니다.

이 허용 목록은 세 가지 스키마 검사만 대상으로 합니다. GitlabSchemasValidateConnection은 이를 읽지 않으므로, 크로스 조인과 오래된 사본에 설명된 대로 새 데이터베이스가 자체 연결을 가진 뒤에는 허용 목록에 등록된 크로스 조인에 대해서도 여전히 예외를 발생시킵니다. 허용 목록이 빌 때까지 CI를 fallback_database에 둡니다.

테이블이 이동해 나오는 스키마(예: gitlab_main_org)를 새 스키마의 allow_cross_joins, allow_cross_transactions, allow_cross_foreign_keys 목록에 추가하거나, 새 스키마를 그 스키마의 목록에 추가하지 않습니다. 둘 중 어느 쪽이든 그 두 스키마만 건드리는 모든 것에 대해 검사를 꺼 버립니다.

크로스 데이터베이스 의존성 제거#

첫 db/docs 변경을 머지하기 전에 작업 순서를 결정합니다. 테이블 수보다 위반 수가 더 중요합니다. 예를 들어 테이블이 한 곳에서만 조인되는 등 위반이 몇 건뿐이라면, 크로스 데이터베이스 의존성을 먼저 제거하고 db/docs 항목은 마지막에 변경합니다. 테이블이 몇 개뿐이어도 위반이 수천 건이라면 db/docs 항목을 먼저 변경합니다. 기존 크로스 데이터베이스 위반 허용 목록 등록에 설명된 파일별 목록에 기존 위반을 등록하고, 목록이 빌 때까지 처리합니다. 결정하기 전에 위반 수를 세려면 초안 머지 리퀘스트에서 db/docs 항목을 변경하고 CI 실패를 확인합니다.

어느 쪽이든 새 데이터베이스로의 데이터 이동은 마지막입니다. 새 경계를 가로질러 조인하는 모든 쿼리, 양쪽에 쓰는 모든 트랜잭션, 그 사이의 모든 외래 키를 제거하기 전에는 테이블이 별도의 데이터베이스에 있을 수 없습니다. db/docs 항목이 바뀌는 즉시 CI가 이를 보고하기 시작합니다.

조인은 main 테이블과 non main 테이블 간의 조인 제거를 참조합니다. 트랜잭션은 크로스 데이터베이스 트랜잭션 제거를 참조합니다.

이동하는 모든 테이블에 대해 가져오기/내보내기(Import/Export)를 확인합니다. 이 쓰기는 모델에 나타나지 않기 때문입니다. 파일 기반 가져오기와 직접 전송은 둘 다 lib/gitlab/import_export/*/import_export.yml에 정의된 관계 트리를 Gitlab::ImportExport::Base::RelationObjectSaver로 저장합니다. 이 클래스는 최상위 관계마다 save! 한 번으로 저장하며, 컬렉션 하위 관계만 트랜잭션 밖으로 옮깁니다. has_one 하위 관계는 자체 컬렉션과 함께 트랜잭션 안에 남습니다. 예를 들어 머지 리퀘스트를 가져오면 merge_requests, merge_request_diffs, merge_request_diff_files가 하나의 트랜잭션에서 기록됩니다. CI는 이를 크로스 데이터베이스 트랜잭션으로 보고하지만, 모델에서 해당 쓰기를 grep해도 아무것도 나오지 않습니다.

데이터베이스에 걸친 외래 키에 설명된 대로, 각 크로스 데이터베이스 외래 키를 느슨한 외래 키로 교체합니다. scripts/decomposition/generate-loose-foreign-key 스크립트는 느슨한 외래 키 정의, 이전 키를 제거하는 마이그레이션, spec 업데이트를 작성합니다.

이 스크립트는 삭제 트리거를 추가하지 않습니다. 부모 테이블이 아직 추적되고 있지 않다면 먼저 레코드 변경 사항 추적을 따릅니다.

참조 구현#

sec 데이터베이스는 가장 최근의 분리 데이터베이스이며, 비교하기에 가장 깔끔한 예시입니다. 커밋 순서는 다음과 같습니다.

에픽:

새 분리 데이터베이스 구축

GitLab v19.6
원문 보기

요약

이 페이지를 사용해 GitLab Rails 애플리케이션에 새 분리(decomposed) 데이터베이스를 처음부터 끝까지 추가합니다. 분리가 무엇인지, 그리고 둘 이상의 데이터베이스를 다룰 때 일상적으로 지켜야 할 규칙에 대한 배경은 먼저 다중 데이터베이스를 읽습니다.

이 페이지를 사용해 GitLab Rails 애플리케이션에 새 분리(decomposed) 데이터베이스를 처음부터 끝까지 추가합니다. 기존 sec 데이터베이스를 실제 참조 사례로 사용하므로, 변경 사항을 실제 예시와 비교(diff)해 볼 수 있습니다.

분리가 무엇인지, 그리고 둘 이상의 데이터베이스를 다룰 때 일상적으로 지켜야 할 규칙에 대한 배경은 먼저 다중 데이터베이스를 읽습니다. 이 페이지는 해당 참조 문서의 "데이터베이스를 하나 더 추가하려면 어떻게 해야 하는가"에 대한 짝 문서입니다.

데이터 기반 데이터베이스 레지스트리#

데이터베이스 등록을 주도하는 중앙 목록은 없습니다. Gitlab::Database는 두 디렉터리를 glob 패턴으로 검색해 런타임에 데이터베이스를 찾아냅니다.

  • db/database_connections/*.yaml은 각 물리적 연결을 설명합니다 (lib/gitlab/database.rb의 all_database_connection_files 참조).
  • db/gitlab_schemas/*.yaml은 각 논리적 gitlab_schema를 설명합니다 (같은 파일의 all_gitlab_schema_files 참조).

EE도 ee/db 아래의 같은 두 디렉터리를 glob 패턴으로 검색합니다.

all_database_connections, all_database_names, database_base_models 같은 모든 하위 요소는 이 파일들에서 만들어집니다. has_config?는 예외로, config/database.yml에 구성된 연결을 읽습니다. 데이터베이스를 추가할 때 핵심은, 중앙 목록을 편집하는 것이 아니라 glob 패턴이 찾아내는 YAML 파일을 추가해 데이터베이스를 등록한다는 점입니다. 일부 위치에는 여전히 데이터베이스를 수동으로 나열하며, 하드코딩된 데이터베이스 목록에 데이터베이스 추가에서 이를 다룹니다.

YAML은 구조체(struct)로 파싱됩니다.

시작하기 전에#

새 분리 데이터베이스는 대개 데이터 모델과 롤아웃을 추적하는 분리 에픽과 함께 진행됩니다. 예를 들어 main과 ci는 에픽 6168에서, sec는 에픽 13043에서 분리됐습니다. 시작하기 전에 Database Frameworks 그룹 및 Tenant Scale 그룹과 조율합니다.

단계별 체크리스트#

다음 단계는 foo라는 가상의 데이터베이스와 그에 대응하는 gitlab_foo 스키마를 사용합니다. 이름은 전체에서 사용하는 이름으로 바꿔 적용합니다. 순서가 중요합니다. 스키마와 연결이 먼저 존재해야, 이를 강제하는 spec이 통과할 수 있습니다.

gitlab_schema 정의 추가#

db/gitlab_schemas/gitlab_foo.yaml을 만듭니다.

name: gitlab_foo
description: Schema for the Foo feature tables.
allow_cross_joins:
  - gitlab_shared
  - gitlab_shared_org
  - gitlab_shared_cell_local
allow_cross_transactions:
  - gitlab_internal
  - gitlab_shared
  - gitlab_shared_org
  - gitlab_shared_cell_local
require_sharding_key: true
sharding_root_tables:
  - projects
  - organizations
  - namespaces

데이터베이스가 cell-local 참조 데이터도 보관한다면, db/gitlab_schemas/gitlab_sec_cell_local.yaml을 참고해 db/gitlab_schemas/gitlab_foo_cell_local.yaml 같은 두 번째 스키마를 추가합니다. 또한 lib/gitlab/database/query_analyzers/restrict_allowed_schemas.rb의 SCHEMA_MAPPING에 gitlab_foo_cell_local: :gitlab_foo를 추가합니다. 이 매핑이 없으면 gitlab_foo로 제한된 마이그레이션이 gitlab_foo_cell_local 테이블에 쓸 때 DMLAccessDeniedError가 발생합니다.

연결 정의 추가#

db/database_connections/foo.yaml을 만듭니다.

name: foo
description: GitLab database holding Foo feature related tables.
gitlab_schemas:
  - gitlab_internal
  - gitlab_shared
  - gitlab_shared_org
  - gitlab_shared_cell_local
  - gitlab_foo
  - gitlab_foo_cell_local # only if you created it
lock_gitlab_schemas:
  - gitlab_main
  - gitlab_main_cell_setting
  - gitlab_main_user
  - gitlab_main_org
  - gitlab_main_cell_local
  - gitlab_main_jh
  - gitlab_ci
  - gitlab_ci_cell_local
  - gitlab_pm
  - gitlab_sec
  - gitlab_sec_cell_local
klass: FooApplicationRecord
# if the Foo database is not configured, use this database
fallback_database: main
uses_load_balancing: true

주요 필드는 다음과 같습니다.

  • gitlab_schemas: 테이블이 이 데이터베이스에 있는 스키마입니다.
  • lock_gitlab_schemas: 다른 데이터베이스에 속한 스키마입니다. gitlab:db:lock_writes Rake 태스크가 이 데이터베이스에서 해당 테이블을 쓰기 잠금해, 데이터가 어긋나지 않게 합니다.
  • klass: 이 연결을 소유하는 추상 기본 모델입니다 (기본 모델 추가 참조).
  • fallback_database: main: 별도의 foo 연결이 구성되지 않은 경우 Foo 스키마가 main 연결에 매핑되므로, 애플리케이션이 단일 데이터베이스 모드로 실행될 수 있습니다. 모델은 기본 모델의 has_config? 가드를 통해 main에 접근합니다. 이 필드는 dev:copy_db:foo Rake 태스크도 정의합니다.
  • db_dir은 선택 사항이며 기본값은 db입니다. 달리 해야 할 이유가 없다면 공유 db 디렉터리를 재사용합니다 (공유 마이그레이션 관련 주의 사항 참조).

새 파일은 Gitlab::Database.all_database_names에도 foo를 추가합니다. 데이터베이스 API 엔드포인트가 이 목록을 매개변수의 허용 값으로 사용하므로 OpenAPI 문서가 변경됩니다. bin/rake gitlab:openapi:v3:generate를 실행하고 업데이트된 doc/api/openapi/openapi_v3.yaml을 커밋합니다. 그러지 않으면 CI에서 bin/rake gitlab:openapi:v3:check_docs가 실패합니다.

db/database_connections/foo.yaml을 추가하면 관리자용 배치 백그라운드 마이그레이션 및 백그라운드 작업 API 엔드포인트가 foo를 데이터베이스 이름으로 허용합니다. config/database.yml에 foo 항목이 없으면 이 엔드포인트는 foo에 대해 500 오류를 반환합니다. 자세한 내용은 이슈 637961을 참조합니다.

다른 데이터베이스에 새 스키마 등록#

기존 연결마다 새 스키마를 lock_gitlab_schemas에 추가해, 해당 데이터베이스가 쓰면 안 되는 Foo 테이블을 잠그도록 합니다. 다음 파일을 편집합니다.

  • db/database_connections/main.yaml
  • db/database_connections/ci.yaml
  • db/database_connections/sec.yaml

각 lock_gitlab_schemas 목록에 gitlab_foo를 추가합니다. gitlab_foo_cell_local을 만들었다면 이것도 추가합니다.

기본 모델 추가#

app/models/sec_application_record.rb를 참고해 app/models/foo_application_record.rb를 만듭니다.

# frozen_string_literal: true

class FooApplicationRecord < ApplicationRecord
  self.abstract_class = true

  connects_to database: { writing: :foo, reading: :foo } if Gitlab::Database.has_config?(:foo)
end

has_config?(:foo) 가드가 단일 데이터베이스 모드를 안전하게 만듭니다. foo 연결이 구성되지 않았다면 모델은 connects_to를 호출하지 않고 ApplicationRecord를 통해 main을 상속합니다. 같은 패턴을 쓰는 app/models/ci/application_record.rb와 비교해 봅니다.

rspec:coverage job의 언더커버리지 검사는 기본 RSpec job의 커버리지를 사용합니다. 이 job들은 foo를 구성하지 않으므로 connects_to 분기가 실행되지 않습니다. 검사가 해당 분기를 커버되지 않은 것으로 보고해 job이 실패합니다. 하드코딩된 데이터베이스 목록에 추가하는 코드도 같은 방식으로 실패할 수 있습니다. 머지 리퀘스트에 pipeline:skip-undercoverage 레이블을 적용하고 새 파이프라인을 시작합니다. 자세한 내용은 rspec:coverage job의 언더커버리지 검사를 참조합니다.

테스트 테이블 접두사 등록#

lib/gitlab/database/gitlab_schema.rb의 IMPLICIT_GITLAB_SCHEMAS에 테스트 테이블용 암시적 스키마 매핑을 추가합니다.

'_test_gitlab_foo_' => :gitlab_foo,

해시에서는 순서가 중요합니다. 다른 접두사를 포함하는 접두사가 먼저 와야 합니다.

structure.sql 심링크 추가#

db/sec_structure.sql과 db/ci_structure.sql이 심링크인 것과 같은 방식으로, 공유 db/structure.sql에 대한 심링크로 db/foo_structure.sql을 만듭니다.

ln -s structure.sql db/foo_structure.sql

config/database.yml 템플릿에 연결 추가#

config/database.yml은 커밋되지 않습니다. foo용 템플릿을 커밋 대상으로 만듭니다. 예를 들어 config/database.yml.decomposed-foo-postgresql입니다. config/database.yml.decomposed-sec-postgresql을 기반으로 하고, 각 환경의 sec: 블록 옆에 foo: 블록을 추가합니다. 사용자 지정 migrations_paths 또는 schema_migrations_path는 설정하지 않습니다. geo와 embedding만 이를 재정의합니다. 자세한 내용은 공유 마이그레이션과 structure.sql 재사용을 참조합니다.

CI에서는 scripts/utils.sh의 setup_database_yml이 DECOMPOSED_DB 및 SEC_DECOMPOSED_DB 변수에 따라 템플릿을 config/database.yml로 복사합니다. .gitlab-ci.yml의 전역 variables는 둘 다 "true"로 설정합니다. foo에 대해 CI job을 실행하려면 FOO_DECOMPOSED_DB 같은 변수와, foo 템플릿을 복사하는 setup_database_yml의 분기를 추가합니다. 로컬 config/database.yml은 GDK에서 새 데이터베이스 실행을 참조합니다.

새 테이블의 딕셔너리 항목 추가#

각 테이블은 db/docs/<table>.yml의 gitlab_schema 아래에 스키마를 기록합니다. foo에 만드는 테이블의 항목을 생성합니다.

bin/rake gitlab:db:dictionary:generate

이 태스크는 gitlab_schema를 설정하지 않습니다. 새 항목은 이 값 없이 생성되며, 직접 gitlab_schema: gitlab_foo를 추가하기 전까지 UnknownSchemaError가 발생합니다. 이미 있는 항목은 태스크가 classes에 클래스 이름만 추가하므로 테이블의 스키마를 바꾸지 않습니다. 기존 테이블을 이동하려면 기존 테이블 이동을 참조합니다.

하드코딩된 데이터베이스 목록에 데이터베이스 추가#

다음 파일은 레지스트리를 읽지 않고 main, ci, sec를 문자 그대로 지정합니다. 각각에 foo를 추가합니다.

  • lib/tasks/gitlab/db.rake: gitlab:db:migration_testing 태스크를 정의하는 all_databases 배열입니다. spec/tasks/gitlab/db_rake_spec.rb는 구성된 모든 데이터베이스에 대해 이 태스크가 있어야 하므로, 항목이 빠지면 여기서 실패합니다.

  • lib/tasks/gitlab/db/truncate_legacy_tables.rake: sec 태스크를 따라 만드는 gitlab:db:truncate_legacy_tables:foo 태스크입니다.

  • lib/gitlab/database/tables_truncate.rb: 지원되는 데이터베이스 목록입니다. foo가 없으면 foo에 속하지 않는 테이블을 트런케이션할 때 database is not supported가 발생해 물리적 분리가 막힙니다.

  • lib/tasks/gitlab/db/schema_load_fix.rake: 임시 해결책이 적용되는 데이터베이스 목록입니다.

  • spec/support/multiple_databases.rb: spec이 데이터베이스 버전을 메모이즈하는 기본 모델 목록입니다. FooApplicationRecord를 추가합니다.

  • app/workers/loose_foreign_keys/cleanup_worker.rb: 터보 모드 목록입니다. config/feature_flags/ops/loose_foreign_keys_turbo_mode_sec.yml 옆에 loose_foreign_keys_turbo_mode_foo ops 기능 플래그도 추가합니다.

  • lib/gitlab/sidekiq_limits.rb: 데이터베이스별 처리 시간 제한입니다. sec_db_duration_limit_per_worker를 따라 foo 항목을 추가합니다. 그런 다음 lib/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits.rb에서 sec 규칙 옆에 foo_db_duration_limit_per_worker 규칙을 추가하고, 해당 키를 cost_mode_keys에 추가합니다. 규칙이 없으면 기능 플래그가 켜져 있을 때 Sidekiq 리소스 사용량 및 스로틀링 미들웨어가 모든 job에 대해 KeyError를 발생시킵니다. cost_mode_keys 항목이 없으면 제한이 적용되지 않습니다.

  • lib/gitlab/database/retention_policy.rb: ELIGIBLE_SCHEMAS 또는 EXCLUDED_SCHEMAS입니다. gitlab_foo와, 만들었다면 gitlab_foo_cell_local을, 각각을 사용하는 첫 db/docs 항목과 같은 머지 리퀘스트에서 추가합니다. spec/db/retention_policy_definitions_spec.rb는 db/docs의 스키마가 두 목록 어디에도 없으면 실패합니다. EE에서는 목록에 있는 스키마에 테이블이 없을 때도 실패합니다.

  • lib/gitlab/database/health_status/indicators/prometheus_alert_indicator.rb: sec에 자체 Prometheus 쿼리를 제공하거나, 쿼리가 없으면 main 쿼리를 제공하는 특수 케이스입니다. foo 케이스가 없거나 prometheus_alert_db_indicators_settings 애플리케이션 설정에 foo 쿼리가 없으면, 인디케이터는 foo에 대해 알 수 없음 신호를 반환합니다. spec/support/shared_examples/database_health_status_indicators/prometheus_alert_based_shared_examples.rb의 공유 예시는 구성된 모든 데이터베이스를 순회하며 sec만 건너뜁니다. 여기서도 foo를 처리해야 합니다. 그러지 않으면 foo가 자체 연결을 가진 뒤 인디케이터 spec이 NoMethodError로 실패합니다.

  • 배치 백그라운드 마이그레이션 및 백그라운드 작업 워커입니다. 각 데이터베이스가 자체 워커를 실행하므로, sec 워커를 복사해 foo용으로 이름을 바꿉니다.

    • app/workers/database/batched_background_migration/sec_database_worker.rb 및 sec_execution_worker.rb
    • app/workers/database/background_operation/sec_scheduler_worker.rb, sec_orchestrator_worker.rb와 그 _cell_local 변형

    워커는 FOO_DATABASE_NAME 상수를 읽으며, lib/gitlab/database.rb의 SEC_DATABASE_NAME 옆에 이 상수를 추가합니다. sec 항목 옆의 config/schedule.yml에 해당 cron 항목을 추가합니다. Cron job 기본값은 더 이상 config/initializers/1_settings.rb에 없습니다. 그런 다음 bin/rake gitlab:sidekiq:all_queues_yml:generate를 실행합니다. 이 워커가 없으면 foo에 큐잉된 배치 백그라운드 마이그레이션과 백그라운드 작업이 실행되지 않습니다.

    이 워커와 관련해 sec를 문자 그대로 지정하는 곳이 두 군데 더 있습니다.

    • lib/gitlab/sidekiq_middleware/size_limiter/validator.rb의 EXEMPT_WORKER_NAMES에는 Database::BatchedBackgroundMigration::SecDatabaseWorker가 있습니다. Database::BatchedBackgroundMigration::FooDatabaseWorker를 추가합니다.
    • spec/support/shared_examples/workers/batched_background_migration_worker_shared_examples.rb의 case tracking_database에는 foo 분기가 없습니다. 분기를 추가하지 않으면 foo가 자체 연결을 가진 뒤 복사한 워커 spec이 NoMethodError로 실패합니다.

공유 마이그레이션과 structure.sql 재사용#

마이그레이션 레이아웃은 가장 흔히 실수하는 부분입니다.

foo 같은 새 분리 데이터베이스는 공유 db/migrate, db/post_migrate, db/schema_migrations를 재사용합니다. 자체 마이그레이션 디렉터리를 갖지 않습니다. 데이터 정의 언어(DDL)는 구성된 모든 데이터베이스에 대해 실행됩니다. restrict_gitlab_migration에 스키마를 선언한 마이그레이션은 해당 스키마를 보유하지 않은 데이터베이스에서는 완전히 건너뜁니다. 공유 마이그레이션 때문에 db/foo_structure.sql은 단일 공유 db/structure.sql에 대한 심링크입니다.

예외는 geo와 embedding이며, 이들은 자체 ee/db/<name>/migrate 디렉터리를 갖습니다. 이 경로는 lib/gitlab/patch/database_config.rb에서 명시적으로 연결되며, 이 파일은 embedding과 geo에만 사용자 지정 migrations_paths를 추가합니다. 이와 비슷한 것을 만드는 경우가 아니라면 이들의 레이아웃을 따르지 않습니다.

둘 이상의 데이터베이스를 다루는 마이그레이션을 작성하는 규칙은 여러 데이터베이스를 위한 마이그레이션을 참조합니다.

기존 테이블 이동#

사전 요구 사항:

foo_bar를 foo로 이동하려면 다음을 수행합니다.

  1. db/docs/foo_bar.yml에서 gitlab_schema를 gitlab_foo로 변경합니다. foo가 구성되었든 아니든 크로스 데이터베이스 검사가 이 테이블에 즉시 적용됩니다. 데이터베이스 경계를 강제하는 검사를 참조합니다.
  2. 이 테이블을 사용하는 각 모델이 ApplicationRecord 대신 FooApplicationRecord를 상속하도록 변경합니다. 변경하기 전에는 foo가 구성된 후에도 모델이 계속 main 연결을 사용합니다. sec의 경우 데이터베이스의 모든 모델이 SecApplicationRecord를 상속합니다. 예를 들어 ee/app/models/dast/pre_scan_verification.rb가 있습니다.
  3. bin/rake gitlab:db:dictionary:generate를 실행해 항목의 classes를 갱신합니다.
  4. 다음 절에 설명된 대로, 이 테이블을 참조하는 릴리스된 마이그레이션을 업데이트합니다.

릴리스된 마이그레이션이 참조하는 테이블 재배치#

기존 테이블을 새 데이터베이스로 이동하면 두 번째 문제를 물려받습니다. 이미 배포된 마이그레이션이 여전히 테이블의 이전 스키마를 선언하고 있다는 점입니다.

데이터 마이그레이션은 쓸 수 있는 스키마를 선언합니다.

class BackfillFooBarProjectId < Gitlab::Database::Migration[2.2]
  restrict_gitlab_migration gitlab_schema: :gitlab_main_org
end

foo_bar의 db/docs 항목이 gitlab_main_org에서 gitlab_foo로 바뀌면 이 선언은 더 이상 맞지 않습니다. 마이그레이션은 이미 릴리스되었으므로 해당 버전을 거쳐 업그레이드하는 GitLab Self-Managed 인스턴스에서 여전히 실행될 수 있으며, 그때 Gitlab::Database::QueryAnalyzers::RestrictAllowedSchemas::DMLAccessDeniedError가 발생합니다.

테이블의 db/docs 항목을 옮기는 커밋과 같은 커밋에서, 릴리스된 마이그레이션의 어노테이션을 새 스키마로 업데이트합니다. 선례는 커밋 b5b3f96b585a로, Secure 및 Govern 분리에서 딕셔너리 변경과 함께 QueueBackfillSbomOccurrencesVulnerabilitiesProjectId를 :gitlab_main_cell에서 :gitlab_sec로 바꿨습니다.

릴리스된 마이그레이션을 수정하는 것이 이상하게 느껴지므로 그렇지 않은 이유를 분명히 밝혀 둘 가치가 있습니다. restrict_gitlab_migration은 마이그레이션을 작성할 당시 테이블이 어디에 있었는지에 대한 과거 기록이 아닙니다. 마이그레이션이 실행될 때 읽어, 어느 연결이 데이터 조작 언어를 실행할 수 있는지 결정하는 런타임 허용 목록입니다. 값은 테이블이 현재 있는 위치를 나타내야 하며, 그렇지 않으면 마이그레이션이 아예 실행될 수 없습니다. 스키마 이력은 db/structure.sql과 마이그레이션 자체의 DDL에 있으며, 둘 다 이 변경의 영향을 받지 않습니다.

어노테이션은 눈에 보이는 실패입니다. 다른 두 가지는 발견하기 더 어려우므로 의도적으로 확인합니다.

선언만이 아니라 인수로 전달되는 스키마#

일부 마이그레이션은 restrict_gitlab_migration에서 스키마를 선언할 뿐 아니라 queue_batched_background_migration에도 전달합니다.

queue_batched_background_migration(
  MIGRATION,
  :foo_bar,
  :id,
  gitlab_schema: :gitlab_main_org,
  ...
)

오래된 어노테이션은 DMLAccessDeniedError로 요란하게 실패하고, 빨간색 파이프라인이 이를 찾아냅니다. 오래된 인수는 조용히 실패할 수 있습니다. 큐에 들어간 행은 전달한 스키마를 저장하지만, ensure_batched_background_migration_is_finished와 finalize_batched_background_migration은 restrict_gitlab_migration의 스키마로 행을 조회합니다. 두 값이 다르면 어느 쪽도 행을 찾지 못합니다. finalize_batched_background_migration은 Could not find batched background migration을 발생시킵니다. ensure_batched_background_migration_is_finished는 경고를 로그에 남기고 백필이 이미 끝난 것처럼 반환합니다. DBLAB_ENVIRONMENT가 설정된 경우에만 예외를 발생시킵니다. 이동하는 테이블의 마이그레이션에서 모든 gitlab_schema: 인수와 어노테이션을 grep으로 찾아 둘 다 바꿉니다.

스키마가 레이블 없는 위치 인수일 수도 있습니다. 예를 들어 BatchedMigration.for_configuration(:gitlab_main_org, MIGRATION, ...)가 그렇습니다. gitlab_schema:로 grep하면 찾을 수 없습니다. :gitlab_main_org 같은 이전 스키마 심볼 자체를 grep합니다.

마이그레이션 spec도 migration: :gitlab_main_org RSpec 메타데이터와, spec이 만드는 배치 백그라운드 마이그레이션 레코드에 스키마 이름을 사용합니다. 메타데이터와 레코드도 업데이트합니다. spec 헬퍼는 마이그레이션 테스트 기간 밖에 있는 오래된 마이그레이션의 spec을 건너뜁니다. 이를 실행하려면 RUN_ALL_MIGRATION_TESTS=1을 설정합니다.

RUN_ALL_MIGRATION_TESTS=1 bundle exec rspec spec/migrations/<migration>_spec.rb

이전 스키마로 이미 큐에 들어간 백필#

batched_background_migrations는 gitlab_schema 텍스트 칼럼을 저장하며, 이 값은 job을 큐에 넣을 때 적용되던 스키마에서 가져와 기록됩니다. 마이그레이션 소스를 수정해도 기존 행은 다시 쓰이지 않습니다. 따라서 이동하는 테이블에 대해 이미 큐에 들어간 백필은 이전 스키마 문자열을 유지하며, db/docs 변경 후 파인더가 저장된 값을 새 연결의 스키마와 대조해 걸러내므로 더 이상 해당 job을 볼 수 없게 됩니다.

소스를 수정해도 테이블에 이미 있는 데이터는 고칠 수 없습니다. 이전 스키마를 가진 큐 행이 없도록, 이동하는 테이블의 db/docs 항목을 변경하기 전에 진행 중인 백필을 완료 처리합니다. 그럴 수 없다면 행을 데이터 마이그레이션으로 수정하거나, 진행 중인 것이 없는 시점에 맞춰 db/docs 변경 순서를 잡아야 합니다. db/docs 변경을 머지하기 전에 이동하는 테이블 이름으로 필터링한 batched_background_migrations 쿼리로 큐에 남은 것이 없는지 확인합니다.

테이블 이동 시 기타 확인 사항#

테이블을 이동할 때 다음을 확인합니다.

  • 가장 최근 것만이 아니라, 이동하는 테이블을 다루는 릴리스된 모든 마이그레이션과 백그라운드 마이그레이션 클래스를 점검합니다. db/migrate, db/post_migrate, lib/gitlab/background_migration에서 테이블 이름을 grep합니다.

  • 이제 두 데이터베이스에 걸쳐 나뉜 테이블을 다루는 마이그레이션은 단일 restrict_gitlab_migration을 유지할 수 없습니다. 마이그레이션을 분리하거나, 크로스 데이터베이스 부분을 애플리케이션 코드로 옮깁니다. 여러 데이터베이스를 위한 마이그레이션을 참조합니다.

  • config/initializers/postgres_partitioning.rb가 limit_connection_names: %i[main]과 함께 register_tables로 테이블을 등록한다면, 파티션 동기화가 구성된 곳에서는 foo에 도달하고 구성되지 않은 곳에서는 main을 유지하도록 합니다. 예를 들면 다음과 같습니다.

    limit_connection_names: Gitlab::Database.has_config?(:foo) ? %i[foo] : %i[main],
    

    main을 foo로 대체하지 않습니다. 프로덕션에서 파티션 동기화는 목록에 지정된 구성된 연결에서만 실행되므로, foo가 main으로 폴백하는 곳에서는 파티션을 동기화하는 것이 없습니다. 어느 쪽이든 여유 파티션이 소진되면 쓰기가 실패하기 시작합니다. %i[main foo]도 동작하지만, 분리 후에도 main의 사본에 계속 파티션을 만듭니다. register_models로 등록한 테이블은 모델의 연결을 따르므로 변경이 필요 없습니다. 프로덕션 외 환경에서는 파티션 동기화가 다른 연결에도 파티션을 만들기 때문에, 놓친 항목이 GDK와 CI에서는 여전히 정상으로 보입니다.

  • Siphon이 해당 테이블을 복제한다면 db/siphon/tables/<table>.yml의 database:를 foo로 변경합니다. 해당 데이터베이스가 테이블의 gitlab_schema를 보유하지 않으면 spec/db/clickhouse_siphon_tables_spec.rb가 실패합니다.

  • 이동하는 테이블에 대해 defer_on_database_health_signal을 호출하는 워커는 여전히 이전 스키마를 선언합니다. 상태 점검은 이 스키마로 연결을 고르므로, 분리 후에는 이전 데이터베이스를 감시하게 되며 아무것도 실패하지 않습니다. app/workers와 ee/app/workers에서 이전 스키마와 함께 defer_on_database_health_signal을 grep합니다. 이동하는 테이블을 다루는 각 워커의 스키마를 gitlab_foo로 변경합니다. 일부 워커는 테이블을 나열하지 않으므로 테이블 이름만 grep하면 놓칠 수 있습니다. 예시는 이슈 631673을 참조합니다.

GDK에서 새 데이터베이스 실행#

데이터를 이동하기 전에, GDK에서 foo를 켠 상태로 이동하는 테이블의 spec을 실행해야 합니다. 데이터베이스 경계를 강제하는 검사에 설명된 대로, CI 검사가 잘못된 연결의 모든 쿼리를 잡아내지는 못합니다. 허용 목록에 항목이 남아 있는 동안에는 크로스 조인과 오래된 사본에 설명된 대로 평소에는 foo를 꺼 둡니다.

GDK는 다음 파일에 각 데이터베이스를 수동으로 나열합니다.

  • lib/gdk/config.rb
  • support/templates/gitlab/config/database.yml.erb
  • lib/support/bootstrap_rails.rb
  • lib/gdk/command/truncate_legacy_tables.rb
  • lib/gdk/task_helpers/rails_migration.rb

GDK 머지 리퀘스트가 이 파일들에 foo를 추가하기 전까지는 gitlab.rails.databases.foo 설정이 존재하지 않으며 gdk config set으로 foo를 켤 수 없습니다. GDK는 AGENTS.md에 설명된 대로 더 이상 새 기능을 받지 않으므로, 해당 머지 리퀘스트는 GDK 메인테이너가 예외를 승인해야 합니다. GDK가 foo를 지원하기 전까지는 다음 절에 설명된 대로 직접 구성합니다.

GDK는 새 작업을 Caproni로 안내하는데, Caproni는 foo 같은 새 데이터베이스를 설정하지 않습니다. 자세한 내용은 Caproni 이슈 57을 참조합니다.

GDK가 데이터베이스를 지원하기 전#

GDK가 지원하기 전에 foo를 실행하려면 다음을 수행합니다.

  1. sec: 항목을 따라 각 환경마다 gitlab/config/database.yml에 foo: 블록을 추가합니다. 각 블록에서 데이터베이스 이름만 변경합니다. 예를 들어 test 블록에서는 gitlabhq_test_foo를 사용합니다.

  2. GDK는 템플릿에서 gitlab/config/database.yml을 다시 생성하며 직접 편집한 내용을 덮어씁니다. diff를 보여 주고 이전 파일을 백업하지만, 변경 내용은 config/database.yml에서 사라집니다. 변경 내용을 유지하려면 gdk.yml에서 이 파일을 보호합니다.

    gdk:
      protected_config_files:
        - 'gitlab/config/database.yml'
    
  3. gitlab 디렉터리에서 GDK의 bootstrap_sec_db가 sec에 대해 하는 것과 같은 방식으로 데이터베이스를 만들고, 속하지 않는 테이블을 비웁니다.

    bin/rake dev:copy_db:foo
    bin/rake gitlab:db:lock_writes
    bin/rake gitlab:db:truncate_legacy_tables:foo
    bin/rake gitlab:db:unlock_writes
    

    dev:copy_db:foo는 main을 복사합니다. 이 태스크는 연결 정의를 추가하고 config/database.yml에 foo 항목이 있어야 정의됩니다. 트런케이션 태스크는 하드코딩된 데이터베이스 목록의 변경이 필요합니다.

  4. foo에 대해 spec을 실행하려면 테스트 데이터베이스를 준비합니다.

    RAILS_ENV=test bin/rake db:test:prepare
    
  5. 이동하는 각 모델이 새 연결을 사용하는지 확인합니다.

    RAILS_ENV=test bin/rails runner 'puts FooBar.connection_db_config.name'
    

    이 명령은 foo를 출력합니다. main을 출력한다면 모델이 FooApplicationRecord를 상속하지 않았거나, config/database.yml의 test 환경에 foo 항목이 없는 것입니다.

GDK가 데이터베이스를 지원한 후#

protected_config_files에서 gitlab/config/database.yml을 제거합니다. 그런 다음 플래그를 설정하고 GDK를 다시 구성합니다.

gdk config set gitlab.rails.databases.foo.enabled true
gdk reconfigure

대신 단일 데이터베이스 모드로 실행하려면 플래그를 false로 설정하고 gdk reconfigure를 실행합니다. 기존 인스턴스에서 모드를 전환할 때의 주의 사항은 단일 데이터베이스 구성을 참조합니다.

크로스 조인과 오래된 사본#

크로스 데이터베이스 허용 목록에 항목이 남아 있는 동안에는, 이를 제거하는 작업을 하거나 데이터를 이동하기 전 최종 점검을 할 때에만 GDK에서 foo를 켭니다. foo를 켜면 main을 거치는 남은 크로스 조인마다, 허용 목록에 있든 없든 웹 요청, Sidekiq job, spec에서 CrossSchemaAccessError가 발생합니다.

Warning

Rails 콘솔, rails runner, 대부분의 Rake 태스크에서는 크로스 데이터베이스 조인이 정상으로 보이는 결과를 반환할 수 있어 문제가 가려집니다. dev:copy_db는 main을 템플릿으로 새 데이터베이스를 만듭니다. 새 데이터베이스에 속하지 않는 테이블을 트런케이션해도 main에는 foo 테이블의 사본이 남아 있으므로, foo에 대한 쓰기로 둘이 달라지기 전까지는 main을 거치는 조인이 그 사본을 읽습니다. GDK의 웹 요청과 Sidekiq job은 같은 쿼리에서 대신 CrossSchemaAccessError가 발생합니다.

main에 있는 foo 테이블의 사본을 비우려면 gitlab:db:lock_writes Rake 태스크를 실행한 다음 gitlab:db:truncate_legacy_tables:main을 실행합니다. 트런케이션 태스크는 대상 테이블이 쓰기 잠금되기 전에는 실행을 거부합니다. main에서 속하지 않는 모든 테이블을 트런케이션하므로, main에 있는 ci 및 sec 테이블의 사본도 비웁니다.

다른 설치 방법에 데이터베이스 추가#

앞 절의 변경은 GitLab Rails 애플리케이션과 GDK를 바꿉니다. Linux 패키지, GitLab Helm 차트, Instrumentor는 각각 데이터베이스를 별도로 구성합니다. 이 중 하나가 foo를 지원하기 전까지는 이를 사용해 별도의 foo 데이터베이스를 구성할 수 없습니다. 이 경우 foo 스키마는 main 연결을 사용합니다.

각 설치 방법별 작업은 다음과 같습니다.

  • Linux 패키지: files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb의 ALLOWED_DATABASES에 foo를 추가합니다. 이 변경이 없으면 gitlab-ctl reconfigure가 gitlab_rails['databases']['foo']를 무시하고 경고를 로그에 남깁니다. 예시는 sec를 추가한 omnibus-gitlab 머지 리퀘스트 7727을 참조합니다.
  • GitLab Helm 차트: values.yaml의 global.psql.knownDecompositions에 foo를 추가합니다. 차트는 이 목록에 있는 데이터베이스에 대해서만 클라우드 네이티브 GitLab 이미지용 config/database.yml을 생성합니다. 예시는 sec를 추가한 charts/gitlab 머지 리퀘스트 3807을 참조합니다.
  • GitLab Dedicated 및 Cells: 내부 프로비저닝 도구인 Instrumentor에 foo를 추가하도록 GitLab Dedicated 팀에 요청합니다. Instrumentor는 데이터베이스마다 데이터베이스를 만들고, PgBouncer 풀을 추가하고, GitLab Helm 차트 값을 설정합니다. Cells의 경우 Cells Infrastructure 팀에도 문의합니다.
  • GitLab.com 레거시 cell: 분리는 예정된 프로덕션 변경입니다. sec 분리는 프로덕션 변경 요청 19581을 참조합니다.

Docker 설치는 Linux 패키지를 사용하고, GitLab Operator는 GitLab Helm 차트를 사용합니다. 별도의 변경이 필요하지 않습니다.

데이터베이스 경계를 강제하는 검사#

단계를 놓치면 여러 spec이 실패하는데, 이는 의도된 기능입니다. 일관성 없는 데이터베이스가 머지되는 것을 막습니다.

  • 데이터베이스 딕셔너리는 모든 테이블이 알려진 gitlab_schema에 매핑되도록 요구합니다. Gitlab::Database::Dictionary는 매핑되지 않은 테이블에 대해 UnknownSchemaError를 발생시킵니다.
  • spec/db/docs_spec.rb와 spec/db/schema_spec.rb는 딕셔너리와 structure.sql이 일관된지 검증합니다.
  • spec/lib/gitlab/database/gitlab_schema_spec.rb는 스키마 정의와 암시적 테스트 테이블 접두사를 검증합니다.
  • spec/lib/gitlab/database/database_connection_info_spec.rb는 연결 YAML이 파싱되고 기본 클래스를 해석하는지 검증합니다.

앞의 검사는 잘못 연결된 레지스트리를 잡아냅니다. 다른 세 가지는 새 데이터베이스가 구성되지 않았더라도 db/docs 항목에서 테이블의 gitlab_schema를 변경하자마자 실패합니다. 이 검사들은 새 데이터베이스의 연결이 아니라 데이터베이스 딕셔너리에서 각 테이블의 스키마를 읽습니다. !130038에서는 db/docs 항목에서 notification_settings를 gitlab_main에서 gitlab_main_cell(이후 gitlab_main_org로 이름이 바뀜)로 옮기는 것만으로 파이프라인이 실패했습니다.

  • spec/support/database/prevent_cross_joins.rb는 스키마가 allow_cross_joins에 짝지어 있지 않은 테이블을 조인하는 모든 쿼리를 실패시킵니다.
  • lib/gitlab/database/query_analyzers/prevent_cross_database_modification.rb는 스키마가 allow_cross_transactions에 짝지어 있지 않은 테이블을 수정하는 모든 트랜잭션을 실패시킵니다.
  • spec/lib/gitlab/database/no_cross_db_foreign_keys_spec.rb는 스키마가 allow_cross_foreign_keys에 짝지어 있지 않은 테이블 간의 모든 외래 키를 실패시킵니다. 단, 해당 칼럼이 spec의 allowed_cross_database_foreign_keys에 나열된 경우는 제외합니다.

fallback_database는 이를 바꾸지 않습니다. fallback_database는 데이터베이스가 구성되지 않았을 때 새 스키마를 어느 연결이 처리할지 결정합니다. 그 덕분에 GitlabSchemasValidateConnection 같은 연결 기반 분석기는 계속 통과하지만, 이 세 검사는 스키마만 비교합니다.

fallback_database에서 파이프라인이 녹색이라고 해서 이동이 끝난 것은 아닙니다. 세 검사는 gitlab_schema를 둘 이상 건드리는 구문에만 작동하므로, 잘못된 연결에서 실행되는 단일 테이블 쿼리는 놓칩니다. 예를 들어 ApplicationRecord.legacy_bulk_insert('foo_bar', rows)는 main을 통해 삽입합니다. legacy_bulk_insert가 호출 대상 클래스의 연결을 사용하기 때문입니다. 데이터베이스가 하나일 때는 스위트가 통과합니다. 이를 잡아내는 것은 GitlabSchemasValidateConnection뿐이며, foo가 자체 연결을 가진 뒤에야 가능합니다.

호출을 고치려면 대신 모델에서 메서드를 호출합니다. 예를 들어 FooBar.legacy_bulk_insert('foo_bar', rows)입니다. 이동하는 테이블을 지정하는, ApplicationRecord 또는 ApplicationRecord.connection을 통한 모든 쓰기를 검색합니다.

데이터를 이동하기 전에, GDK에서 새 데이터베이스 실행에 설명된 대로 foo를 켠 상태로 이동하는 테이블의 spec을 실행합니다.

기존 크로스 데이터베이스 위반 허용 목록 등록#

기존 위반을 허용 목록에 등록하는 방법은 위반 수에 따라 달라집니다. 수가 적으면 발생 위치마다 허용 목록에 등록하고 이슈와 연결합니다.

수천 건이 있으면 호출 지점마다 표시하는 일은 그 자체로 하나의 프로젝트입니다. 대신 실패하는 spec 파일을 spec/support/database/cross-join-allowlist.yml과 spec/support/database/cross-database-modification-allowlist.yml에 나열합니다. CI 분리는 앞의 것에 418개, 뒤의 것에 1,340개의 spec 파일로 시작해 1년 안에 둘 다 비웠습니다. CI는 목록에 있는 spec 파일에 대해서는 어떤 데이터베이스든 이 검사를 실행하지 않으므로, 해당 파일의 새 위반은 눈에 띄지 않습니다. 목록을 백로그로 취급하고 비워질 때까지 처리합니다. 외래 키에는 파일별 목록이 없으므로 항상 allowed_cross_database_foreign_keys에 넣습니다.

이 허용 목록은 세 가지 스키마 검사만 대상으로 합니다. GitlabSchemasValidateConnection은 이를 읽지 않으므로, 크로스 조인과 오래된 사본에 설명된 대로 새 데이터베이스가 자체 연결을 가진 뒤에는 허용 목록에 등록된 크로스 조인에 대해서도 여전히 예외를 발생시킵니다. 허용 목록이 빌 때까지 CI를 fallback_database에 둡니다.

테이블이 이동해 나오는 스키마(예: gitlab_main_org)를 새 스키마의 allow_cross_joins, allow_cross_transactions, allow_cross_foreign_keys 목록에 추가하거나, 새 스키마를 그 스키마의 목록에 추가하지 않습니다. 둘 중 어느 쪽이든 그 두 스키마만 건드리는 모든 것에 대해 검사를 꺼 버립니다.

크로스 데이터베이스 의존성 제거#

첫 db/docs 변경을 머지하기 전에 작업 순서를 결정합니다. 테이블 수보다 위반 수가 더 중요합니다. 예를 들어 테이블이 한 곳에서만 조인되는 등 위반이 몇 건뿐이라면, 크로스 데이터베이스 의존성을 먼저 제거하고 db/docs 항목은 마지막에 변경합니다. 테이블이 몇 개뿐이어도 위반이 수천 건이라면 db/docs 항목을 먼저 변경합니다. 기존 크로스 데이터베이스 위반 허용 목록 등록에 설명된 파일별 목록에 기존 위반을 등록하고, 목록이 빌 때까지 처리합니다. 결정하기 전에 위반 수를 세려면 초안 머지 리퀘스트에서 db/docs 항목을 변경하고 CI 실패를 확인합니다.

어느 쪽이든 새 데이터베이스로의 데이터 이동은 마지막입니다. 새 경계를 가로질러 조인하는 모든 쿼리, 양쪽에 쓰는 모든 트랜잭션, 그 사이의 모든 외래 키를 제거하기 전에는 테이블이 별도의 데이터베이스에 있을 수 없습니다. db/docs 항목이 바뀌는 즉시 CI가 이를 보고하기 시작합니다.

조인은 main 테이블과 non main 테이블 간의 조인 제거를 참조합니다. 트랜잭션은 크로스 데이터베이스 트랜잭션 제거를 참조합니다.

이동하는 모든 테이블에 대해 가져오기/내보내기(Import/Export)를 확인합니다. 이 쓰기는 모델에 나타나지 않기 때문입니다. 파일 기반 가져오기와 직접 전송은 둘 다 lib/gitlab/import_export/*/import_export.yml에 정의된 관계 트리를 Gitlab::ImportExport::Base::RelationObjectSaver로 저장합니다. 이 클래스는 최상위 관계마다 save! 한 번으로 저장하며, 컬렉션 하위 관계만 트랜잭션 밖으로 옮깁니다. has_one 하위 관계는 자체 컬렉션과 함께 트랜잭션 안에 남습니다. 예를 들어 머지 리퀘스트를 가져오면 merge_requests, merge_request_diffs, merge_request_diff_files가 하나의 트랜잭션에서 기록됩니다. CI는 이를 크로스 데이터베이스 트랜잭션으로 보고하지만, 모델에서 해당 쓰기를 grep해도 아무것도 나오지 않습니다.

데이터베이스에 걸친 외래 키에 설명된 대로, 각 크로스 데이터베이스 외래 키를 느슨한 외래 키로 교체합니다. scripts/decomposition/generate-loose-foreign-key 스크립트는 느슨한 외래 키 정의, 이전 키를 제거하는 마이그레이션, spec 업데이트를 작성합니다.

이 스크립트는 삭제 트리거를 추가하지 않습니다. 부모 테이블이 아직 추적되고 있지 않다면 먼저 레코드 변경 사항 추적을 따릅니다.

참조 구현#

sec 데이터베이스는 가장 최근의 분리 데이터베이스이며, 비교하기에 가장 깔끔한 예시입니다. 커밋 순서는 다음과 같습니다.

에픽: