다중 데이터베이스 마이그레이션

이 문서는 다중 데이터베이스를 사용하는 분해된 GitLab 애플리케이션을 위한 데이터베이스 마이그레이션 작성 방법을 정확하게 설명합니다. 자세한 정보는 다중 데이터베이스를 참조하세요.

다중 데이터베이스의 설계(지오 데이터베이스 제외)는 모든 분해된 데이터베이스가 동일한 구조(예: 스키마)를 가지지만 데이터는 각 데이터베이스마다 다르다고 가정합니다. 이는 일부 테이블이 각 데이터베이스에 데이터를 포함하지 않는다는 것을 의미합니다.

작업

사용된 구성에 따라 마이그레이션을 다음과 같이 분류할 수 있습니다:

구조 수정 (DDL - 데이터 정의 언어) (예: ALTER TABLE).
데이터 수정 (DML - 데이터 조작 언어) (예: UPDATE).
기타 쿼리 수행 (기타 쿼리) (예: SELECT)는 마이그레이션의 목적상 DML로 처리됩니다.

Gitlab::Database::Migration[2.0]의 사용은 항상 마이그레이션이 단일 목적으로 되어야 함을 의미합니다. 마이그레이션은 응용 프로그램이 모든 분해된 데이터베이스에 걸쳐 정확히 동일한 구조(구조.sql에 설명된 대로)를 필요로 하기 때문에 DDL 및 DML 변경을 혼합할 수 없습니다.

데이터 정의 언어 (DDL)

DDL 마이그레이션은 다음을 포함하는 모든 마이그레이션입니다:

테이블 생성 또는 삭제 (예: create_table).
인덱스 추가 또는 제거 (예: add_index, add_concurrent_index).
외래 키 추가 또는 제거 (예: add_foreign_key, add_concurrent_foreign_key).
기본 값을 포함하거나 포함하지 않는 열 추가 또는 제거 (예: add_column).
트리거 함수 생성 또는 삭제(예: create_trigger_function).
테이블에서 트리거 연결 또는 분리 (예: track_record_deletions, untrack_record_deletions).
비동기 인덱스 준비 또는 비준비 (예: prepare_async_index, unprepare_async_index_by_name).
테이블 잘라내기 (예: truncate_tables! 도우미 메서드 사용).

이러한 DDL 마이그레이션은 다음을 할 수 없습니다:

SQL 문 또는 ActiveRecord 모델을 통해 데이터를 읽거나 수정하지 않습니다.
열 값을 업데이트하지 않습니다 (예: update_column_in_batches).
백그라운드 마이그레이션을 예약하지 않습니다 (예: queue_background_migration_jobs_by_range_at_intervals).
main:(feature 및 feature_gates가 저장된)에 저장되어 있기 때문에 기능 플래그 상태를 읽지 않습니다.
응용 프로그램 설정을 읽지 않습니다(설정은 main:에 저장됨).

GitLab 코드베이스의 대부분의 마이그레이션은 DDL 유형이므로, 이것은 또한 기본 작업 모드이며 마이그레이션 파일에 대한 추가 변경이 필요하지 않습니다.

예: 모든 데이터베이스에 DDL 수행

모든 구성된 데이터베이스에서 실행되는 구조 변경(DDL)으로 처리되는 동시 인덱스를 추가하는 예제 마이그레이션입니다.

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

  INDEX_NAME = 'index_on_merge_request_reviewers_user_id_and_state'

  def up
    add_concurrent_index :merge_request_reviewers, [:user_id, :state], where: 'state = 2', name: INDEX_NAME
  end

  def down
    remove_concurrent_index_by_name :merge_request_reviewers, INDEX_NAME
  end
end

예: 단일 데이터베이스에 저장할 새 테이블 추가

데이터베이스 사전에 테이블 추가: db/docs/에 추가합니다.

table_name: ssh_signatures
description: Description example
introduced_by_url: Merge request link
milestone: Milestone example
feature_categories:
- Feature category example
classes:
- Class example
gitlab_schema: gitlab_main

스키마 마이그레이션에서 테이블 생성:

class CreateSshSignatures < Gitlab::Database::Migration[2.1]
  def change
    create_table :ssh_signatures do |t|
      t.timestamps_with_timezone null: false
      t.bigint :project_id, null: false, index: true
      t.bigint :key_id, null: false, index: true
      t.integer :verification_status, default: 0, null: false, limit: 2
      t.binary :commit_sha, null: false, index: { unique: true }
    end
  end
end

데이터 조작 언어 (DML)

DML 마이그레이션은 다음을 포함하는 모든 마이그레이션입니다:

SQL 문을 통한 데이터 읽기(예: SELECT * FROM projects WHERE id=1).
ActiveRecord 모델을 통한 데이터 읽기(예: User < MigrationRecord).
ActiveRecord 모델을 통한 데이터 생성, 업데이트 또는 삭제(예: User.create!(...)).
SQL 문을 통한 데이터 생성, 업데이트 또는 삭제(예: DELETE FROM projects WHERE id=1).
일괄 업데이트에서 열 업데이트(예: update_column_in_batches(:projects, :archived, true)).
백그라운드 마이그레이션 예약(예: queue_background_migration_jobs_by_range_at_intervals).
응용 프로그램 설정 액세스 (예: main: 데이터베이스에 실행될 경우 ApplicationSetting.last).
main: 데이터베이스를 위해 기능 플래그 읽고 수정합니다.

DML 마이그레이션은 다음을 할 수 없습니다:

DDL에 대한 어떠한 변경도 수행하지 않습니다. 이로 인해 structure.sql을 모든 분해된 데이터베이스에 일관되게 유지하는 규칙이 깨집니다.
다른 데이터베이스에서 데이터를 읽지 않습니다.

DML 마이그레이션 유형을 나타내기 위해 마이그레이션은 restrict_gitlab_migration gitlab_schema: 구문을 마이그레이션 클래스에서 사용해야 합니다. 이렇게 하면 주어진 마이그레이션이 DML로 표시되고 액세스가 제한됩니다.

예: 주어진 `gitlab_schema`를 포함하는 데이터베이스의 컨텍스트에서만 DML 수행

gitlab_main 스키마를 포함하는 데이터베이스에 대해서만 실행되는 projects의 archived 열을 업데이트하는 예제 마이그레이션입니다.

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

  restrict_gitlab_migration gitlab_schema: :gitlab_main

  def up
    update_column_in_batches(:projects, :archived, true) do |table, query|
      query.where(table[:archived].eq(false)) # rubocop:disable CodeReuse/ActiveRecord
    end
  end

  def down
    # no-op
  end
end

예시: `ActiveRecord` 클래스 사용 예

ActiveRecord 클래스를 사용하여 데이터 조작을 수행하는 마이그레이션은 MigrationRecord 클래스를 사용해야 합니다. 이 클래스는 주어진 마이그레이션 컨텍스트에서 올바른 연결을 제공하는 것이 보장됩니다.

MigrationRecord == ActiveRecord::Base 밑에, db:migrate가 실행되면, ActiveRecord::Base.establish_connection :ci의 활성 연결을 전환합니다. ActiveRecord::Base를 사용하는 것을 피하기 위해, MigrationRecord가 필요합니다.

이는 DML 마이그레이션이 다른 데이터베이스에서 데이터를 읽는 것을 금지함을 의미합니다. 예를 들어, ci: 컨텍스트에서 마이그레이션을 실행하고 main:에서 feature 플래그를 읽는 것은 다른 데이터베이스에 대한 확립된 연결이 없으므로 금지됩니다.

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

  restrict_gitlab_migration gitlab_schema: :gitlab_main

  class Project < MigrationRecord
  end

  def up
    Project.where(archived: false).each_batch of |batch|
      batch.update_all(archived: true)
    end
  end

  def down
  end
end

`gitlab_shared`의 특수 목적

gitlab_schema에 설명된대로, gitlab_shared 테이블에는 모든 데이터베이스를 통해 데이터를 포함할 수 있습니다. 이는 이러한 마이그레이션이 모든 데이터베이스에서 실행되어야 하며 구조 (DDL)를 수정하거나 데이터 (DML)를 수정할 수 있음을 의미합니다.

따라서 gitlab_shared에 액세스하는 마이그레이션에는 restrict_gitlab_migration gitlab_schema:을 사용할 필요가 없으며, 제한 없는 마이그레이션은 모든 데이터베이스에서 실행되고 각 데이터베이스에서 데이터를 수정할 수 있습니다. restrict_gitlab_migration gitlab_schema:가 지정된 경우 DML 마이그레이션은 주어진 gitlab_schema를 포함하는 데이터베이스 컨텍스트 내에서만 실행됩니다.

예시: 모든 데이터베이스에서 `gitlab_shared` DML 마이그레이션 실행

lib/gitlab/database/gitlab_schemas.yml에 gitlab_shared로 표시된 loose_foreign_keys_deleted_records 테이블을 업데이트하는 예시 마이그레이션입니다.

이 마이그레이션은 구성된 모든 데이터베이스에서 실행됩니다.

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

  def up
    execute("DELETE FROM loose_foreign_keys_deleted_records")
  end

  def down
    # no-op
  end
end

예시: 주어진 `gitlab_schema`가 포함된 데이터베이스에서만 `gitlab_shared` DML 실행

db/docs/loose_foreign_keys_deleted_records.yml에 gitlab_shared로 표시된 loose_foreign_keys_deleted_records 테이블을 업데이트하는 예시 마이그레이션입니다.

이 마이그레이션은 gitlab_ci에서 제한을 구성했기 때문에 gitlab_ci 데이터베이스 컨텍스트에서만 실행됩니다.

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

  restrict_gitlab_migration gitlab_schema: :gitlab_ci

  def up
    execute("DELETE FROM loose_foreign_keys_deleted_records WHERE fully_qualified_table_name='ci_builds'")
  end

  def down
    # no-op
  end
end

마이그레이션 건너뛰기 동작

건너뛰는 유일한 마이그레이션이 DML 변경을 수행하는 마이그레이션입니다. DDL 마이그레이션은 항상 무조건적으로 실행됩니다.

구현된 솔루션은 database_tasks:를 사용하여 주요 데이터베이스를 공유하는 추가 데이터베이스 설정 (config/database.yml)을 나타내도록 합니다. database_tasks: false로 표시된 데이터베이스 설정은 해당 데이터베이스 설정에 대해 db:migrate를 실행하지 않도록 예외가 됩니다.

데이터베이스 설정이 데이터베이스를 공유하지 않는 경우 (모든이 database_tasks: true를 가지는 경우), 각 마이그레이션은 모든 데이터베이스 설정에 대해 실행됩니다.

DDL 마이그레이션은 모든 데이터베이스에 대해 모든 구조 변경을 적용합니다.
DML 마이그레이션은 주어진 gitlab_schema:를 포함하는 데이터베이스 컨텍스트 내에서만 실행됩니다.
DML 마이그레이션이 실행할 수 없는 경우 건너뛰어집니다. 여전히 schema_migrations에서 실행으로 표시됩니다. db:migrate를 실행하는 동안 건너뛰어진 마이그레이션은 'gitlab_main, gitlab_shared'의 외부에 있는 'gitlab_ci'를 수정하기 때문에 현재 마이그레이션이 건너뜁니다 출력합니다.

database_tasks: false가 구성된 경우 마이그레이션을 잃지 않도록 하기 위해 전용 Rake 작업이 사용됩니다 gitlab:db:validate_config. gitlab:db:validate_config은 각 기본 데이터베이스 설정의 데이터베이스 식별자를 확인하여 database_tasks:의 정확성을 확인합니다. 데이터베이스가 공유하고 있는 경우에는 database_tasks: false를 설정해야 합니다. gitlab:db:validate_config는 항상 db:migrate 이전에 실행됩니다.

에러

남용이나 restrict_gitlab_migration의 부재에 따라 다양한 예외가 발생하여 마이그레이션이 완료되지 못할 수 있습니다.

예외 1: DDL 모드에서 DML select를 실행하는 마이그레이션

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

  # Missing:
  # restrict_gitlab_migration gitlab_schema: :gitlab_main

  def up
    update_column_in_batches(:projects, :archived, true) do |table, query|
      query.where(table[:archived].eq(false)) # rubocop:disable CodeReuse/ActiveRecord
    end
  end

  def down
    # no-op
  end
end

DDL(구조) 모드에서 Select/DML 쿼리 (SELECT/UPDATE/DELETE)가 허용되지 않습니다.
'projects' (gitlab_main)를 수정하는중 'SELECT * FROM projects...

현재 마이그레이션이 restrict_gitlab_migration을 사용하지 않습니다. 이 부재는 마이그레이션이 DDL 모드에서 실행되고 있음을 나타내지만 실행된 페이로드가 ‘projects’에서 데이터를 읽어오는 것으로 보입니다.

해결책은 restrict_gitlab_migration gitlab_schema: :gitlab_main을 추가하는 것입니다.

예외 2: DML 모드에서 실행 중인 마이그레이션이 구조를 변경함

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

  # restrict_gitlab_migration가 정의되어 있으면 DML을 나타내므로 제거해야 함
  restrict_gitlab_migration gitlab_schema: :gitlab_main

  INDEX_NAME = 'index_on_merge_request_reviewers_user_id_and_state'

  def up
    add_concurrent_index :merge_request_reviewers, [:user_id, :state], where: 'state = 2', name: INDEX_NAME
  end

  def down
    remove_concurrent_index_by_name :merge_request_reviewers, INDEX_NAME
  end
end

DDL 쿼리(구조)는 선택/데이터 조작 (SELECT/UPDATE/DELETE) 모드에서 허용되지 않습니다. 
'merge_request_reviewers'을/를 수정 중이며 'CREATE INDEX...

현재 마이그레이션은 restrict_gitlab_migration을 사용합니다. 이것은 DML 모드를 나타내지만, 실행된 페이로드는 구조 변경(DDL)을 하는 것으로 보입니다.

해결책은 restrict_gitlab_migration gitlab_schema: :gitlab_main을 제거하는 것입니다.

예외 3: DML 모드에서 다른 스키마의 테이블에서 데이터에 접근하는 마이그레이션

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

  # `projects`를 수정하기 때문에 `gitlab_main`을 사용해야 함
  restrict_gitlab_migration gitlab_schema: :gitlab_ci

  def up
    update_column_in_batches(:projects, :archived, true) do |table, query|
      query.where(table[:archived].eq(false)) # rubocop:disable CodeReuse/ActiveRecord
    end
  end

  def down
    # no-op
  end
end

선택/DML 쿼리(SELECT/UPDATE/DELETE)는 'gitlab_ci'에 있는 'projects'에 접근하지만 허용된 스키마 목록 : 'gitlab_ci'의 밖에 있습니다.

현재 마이그레이션은 마이그레이션을 gitlab_ci로 제한하지만 gitlab_main의 데이터를 수정하는 것으로 보입니다.

해결책은 restrict_gitlab_migration gitlab_schema: :gitlab_ci로 변경하는 것입니다.

예외 4: DDL 및 DML 모드 혼합

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

  # 이 마이그레이션은 구조와 데이터를 동시에 수정할 수 없으므로 명세에 관계없이 잘못되었습니다
  restrict_gitlab_migration gitlab_schema: :gitlab_ci

  def up
    add_concurrent_index :merge_request_reviewers, [:user_id, :state], where: 'state = 2', name: 'index_on_merge_request_reviewers'
    update_column_in_batches(:projects, :archived, true) do |table, query|
      query.where(table[:archived].eq(false)) # rubocop:disable CodeReuse/ActiveRecord
    end
  end

  def down
    # no-op
  end
end

작업의 순서에 따라 DDL 및 DML를 혼합하는 마이그레이션이 발생하는 경우 하나의 이전 예외가 발생합니다.

다중 데이터베이스 마이그레이션에 대한 예정 변경 사항

restrict_gitlab_migration를 사용하여 gitlab_schema:을 사용하는 것은 맥락에 따라 마이그레이션을 선택적으로 실행하기 위한 이 기능의 첫 번째 반복으로 간주됩니다. 추가적으로 DML 전용 마이그레이션에 추가 제한 사항을 추가하는 것이 가능합니다 (구조 일관성은 앞으로 더욱 그대로 유지될 가능성이 있으므로) 실행 시간을 제한합니다.

잠재적인 확장은 특정 환경에서 DML 마이그레이션을 실행할 수 있게 제한하는 것입니다:

restrict_gitlab_migration gitlab_schema: :gitlab_main, gitlab_env: :gitlab_com

배경 마이그레이션

다음을 사용할 때:

‘track_jobs’가 ‘true’로 설정된 배경 마이그레이션 또는
배치 배경 마이그레이션

마이그레이션은 작업 테이블에 쓰여야 합니다. 배경 마이그레이션에서 사용되는 모든 작업 테이블은 gitlab_shared로 표시됩니다. 모든 데이터베이스의 테이블을 마이그레이션할 때 이러한 마이그레이션을 사용할 수 있습니다.

그러나 일괄 배치를 예약할 때는 반복하는 테이블에 따라 restrict_gitlab_migration을 설정해야 합니다. 예를 들어 모든 projects를 업데이트하는 경우에는 restrict_gitlab_migration gitlab_schema: :gitlab_main으로 설정합니다. 그러나 모든 ci_pipelines을 업데이트하는 경우에는 restrict_gitlab_migration gitlab_schema: :gitlab_ci로 설정해야 합니다.

모든 DML 마이그레이션과 마찬가지로 restrict_gitlab_migration이나 gitlab_shared의 외부 데이터베이스를 쿼리할 수 없습니다. 다른 데이터베이스를 쿼리해야 하는 경우 마이그레이션을 분리합니다.

실제 마이그레이션 로직(대기 단계가 아닌)은 배경 마이그레이션의 Sidekiq 워커에서 실행되므로 일반적인 Sidekiq 워커처럼 어떤 데이터베이스의 테이블에서도 DML 쿼리를 실행할 수 있습니다.

다중 데이터베이스 마이그레이션

작업

데이터 정의 언어 (DDL)

예: 모든 데이터베이스에 DDL 수행

예: 단일 데이터베이스에 저장할 새 테이블 추가

데이터 조작 언어 (DML)

예: 주어진 `gitlab_schema`를 포함하는 데이터베이스의 컨텍스트에서만 DML 수행

예시: `ActiveRecord` 클래스 사용 예

`gitlab_shared`의 특수 목적

예시: 모든 데이터베이스에서 `gitlab_shared` DML 마이그레이션 실행

예시: 주어진 `gitlab_schema`가 포함된 데이터베이스에서만 `gitlab_shared` DML 실행

마이그레이션 건너뛰기 동작

에러

예외 1: DDL 모드에서 DML select를 실행하는 마이그레이션

예외 2: DML 모드에서 실행 중인 마이그레이션이 구조를 변경함

예외 3: DML 모드에서 다른 스키마의 테이블에서 데이터에 접근하는 마이그레이션

예외 4: DDL 및 DML 모드 혼합

다중 데이터베이스 마이그레이션에 대한 예정 변경 사항

배경 마이그레이션

도움말

기능 사용 가능성과 제품 평가판

도움받기

다중 데이터베이스 마이그레이션

작업

데이터 정의 언어 (DDL)

예: 모든 데이터베이스에 DDL 수행

예: 단일 데이터베이스에 저장할 새 테이블 추가

데이터 조작 언어 (DML)

예: 주어진 gitlab_schema를 포함하는 데이터베이스의 컨텍스트에서만 DML 수행

예시: ActiveRecord 클래스 사용 예

gitlab_shared의 특수 목적

예시: 모든 데이터베이스에서 gitlab_shared DML 마이그레이션 실행

예시: 주어진 gitlab_schema가 포함된 데이터베이스에서만 gitlab_shared DML 실행

마이그레이션 건너뛰기 동작

에러

예외 1: DDL 모드에서 DML select를 실행하는 마이그레이션

예외 2: DML 모드에서 실행 중인 마이그레이션이 구조를 변경함

예외 3: DML 모드에서 다른 스키마의 테이블에서 데이터에 접근하는 마이그레이션

예외 4: DDL 및 DML 모드 혼합

다중 데이터베이스 마이그레이션에 대한 예정 변경 사항

배경 마이그레이션

도움말

기능 사용 가능성과 제품 평가판

도움받기

예: 주어진 `gitlab_schema`를 포함하는 데이터베이스의 컨텍스트에서만 DML 수행

예시: `ActiveRecord` 클래스 사용 예

`gitlab_shared`의 특수 목적

예시: 모든 데이터베이스에서 `gitlab_shared` DML 마이그레이션 실행

예시: 주어진 `gitlab_schema`가 포함된 데이터베이스에서만 `gitlab_shared` DML 실행