일괄 백그라운드 마이그레이션용 버전별 스펙 헬퍼 라이브러리는 마이그레이션 스펙의 반복 코드를 줄여 줍니다.

스펙 헬퍼 기능#

일괄 백그라운드 마이그레이션 스펙은 MigrationsHelpers의 table() 메서드로 여러 테이블 헬퍼를 정의해야 하는 경우가 많습니다. 그 결과 코드가 반복됩니다.

# Without helpers - repetitive
RSpec.describe Gitlab::BackgroundMigration::BackfillProjectId do
  let!(:projects) { table(:projects) }
  let!(:issues) { table(:issues) }
  let!(:notes) { table(:notes) }
  let!(:users) { table(:users) }
  # ... more table definitions
end

일괄 백그라운드 마이그레이션 스펙 헬퍼는 지연 평가와 메모이제이션으로 이러한 반복을 없앱니다.

# With helpers - clean and concise
RSpec.describe Gitlab::BackgroundMigration::BackfillProjectId do
  include Gitlab::BackgroundMigration::SpecHelpers::V1

  # Declare the tables you need
  tables :projects, :issues, :notes, :users
end

버전 관리#

헬퍼는 하위 호환성을 보장하기 위해 버전으로 관리합니다. 수정이 필요하면 기존 스펙을 깨뜨리지 않고 새 버전을 만들 수 있습니다.

사용 가능한 버전#

• V1: 테이블 헬퍼를 포함한 최초 버전(현재 버전)

특정 버전 사용#

사용하려는 버전 모듈을 include 합니다.

RSpec.describe Gitlab::BackgroundMigration::SomeMigration do
  include Gitlab::BackgroundMigration::SpecHelpers::V1
end

기능#

명시적 테이블 선언#

테이블에 접근하려면 먼저 tables 메서드로 명시적으로 선언해야 합니다.

RSpec.describe Gitlab::BackgroundMigration::BackfillNamespaceId do
  include Gitlab::BackgroundMigration::SpecHelpers::V1

  # Declare all tables needed in your spec
  tables :issues, :namespaces, :projects

  it 'backfills namespace_id' do
    # Tables are created on first access after declaration
    namespace = namespaces.create!(name: 'test', path: 'test')
    project = projects.create!(namespace_id: namespace.id)
    issue = issues.create!(project_id: project.id)
  end
end

메모이제이션#

테이블 헬퍼는 메모이제이션되므로, 반복해서 접근해도 같은 인스턴스를 반환합니다.

RSpec.describe Gitlab::BackgroundMigration::SomeMigration do
  include Gitlab::BackgroundMigration::SpecHelpers::V1

  tables :users

  it 'uses memoized tables' do
    users_1 = users  # Creates the helper on first access
    users_2 = users  # Returns the same instance

    expect(users_1).to be(users_2)
  end
end

커스텀 구성#

커스텀 옵션으로 테이블을 구성할 수 있습니다.

커스텀 기본 키#

RSpec.describe Gitlab::BackgroundMigration::SomeMigration do
  include Gitlab::BackgroundMigration::SpecHelpers::V1

  tables :custom_table
  configure_table :custom_table, primary_key: :custom_id

  it 'uses custom primary key' do
    record = custom_table.create!(custom_id: 1, name: 'test')
    expect(custom_table.primary_key).to eq('custom_id')
  end
end

커스텀 데이터베이스#

RSpec.describe Gitlab::BackgroundMigration::SomeMigration do
  include Gitlab::BackgroundMigration::SpecHelpers::V1

  tables :ci_builds
  configure_table :ci_builds, database: :ci
end

파티션된 테이블#

RSpec.describe Gitlab::BackgroundMigration::SomeMigration, migration: :gitlab_ci do
  include Gitlab::BackgroundMigration::SpecHelpers::V1

  tables :p_ci_builds
  configure_table :p_ci_builds, partitioned: true, database: :ci

  it 'works with partitioned tables' do
    build = p_ci_builds.create!(partition_id: 100, project_id: 1)
  end
end

마이그레이션 가이드#

기존 스펙 변환#

기존 스펙이 헬퍼를 사용하도록 변환하는 방법은 다음과 같습니다.

전환 전:

RSpec.describe Gitlab::BackgroundMigration::BackfillProjectId,
  feature_category: :code_review_workflow do

  let!(:projects) { table(:projects) }
  let!(:merge_requests) { table(:merge_requests) }
  let!(:approval_rules) { table(:approval_merge_request_rules) }

  it 'backfills project_id' do
    project = projects.create!(name: 'test')
    mr = merge_requests.create!(target_project_id: project.id)
    rule = approval_rules.create!(merge_request_id: mr.id)

    # test logic
  end
end

전환 후:

RSpec.describe Gitlab::BackgroundMigration::BackfillProjectId,
  feature_category: :code_review_workflow do

  include Gitlab::BackgroundMigration::SpecHelpers::V1

  tables :approval_merge_request_rules, :merge_requests, :projects

  it 'backfills project_id' do
    project = projects.create!(name: 'test')
    mr = merge_requests.create!(target_project_id: project.id)
    rule = approval_merge_request_rules.create!(merge_request_id: mr.id)

    # test logic
  end
end

사용 시기#

다음과 같은 경우에 헬퍼를 사용합니다.

• 새 일괄 백그라운드 마이그레이션 스펙을 작성할 때
• 여러 테이블 헬퍼가 필요할 때
• 반복 코드를 줄이려고 할 때

다음과 같은 경우에는 수동 정의를 고려합니다.

• 특정한 테이블 구성이 필요할 때
• 복잡한 커스텀 테이블 설정을 다룰 때
• 스펙이 테이블을 한두 개만 사용할 때

모범 사례#

• 테이블은 항상 명시적으로 선언합니다. 스펙에 필요한 모든 테이블을 tables 메서드로 선언합니다. 테이블은 자동으로 제공되지 않으며, 사용하기 전에 선언해야 합니다.
• 테이블은 알파벳순으로 선언합니다. 스펙 전반의 일관성과 가독성이 좋아집니다.
• 최신 버전을 사용합니다. 특별한 이유가 없다면 새 스펙에는 V1(또는 사용 가능한 최신 버전)을 사용합니다.
• 선언한 뒤에 구성합니다. 항상 tables로 테이블을 먼저 선언한 다음, 필요하면 configure_table로 구성합니다.
• 방식을 섞지 않습니다. 하나의 스펙 안에서 스펙 헬퍼와 수동 let! 정의를 함께 쓰지 않습니다.
• 구성은 최소한으로 유지합니다. 커스텀 옵션(기본 키, 데이터베이스, 파티셔닝)이 필요할 때만 테이블을 구성합니다.

문제 해결#

테이블을 찾을 수 없음#

"table not found" 오류가 발생하면 다음을 확인합니다.

1. 클래스 수준에서 tables :table_name으로 테이블을 선언했는지 확인합니다.
2. 스펙에 지정한 스키마 버전에 해당 테이블이 있는지 확인합니다.
3. 올바른 데이터베이스(:main, :ci 등)를 사용하고 있는지 확인합니다.
4. 마이그레이션 메타데이터가 올바르게 설정되었는지 확인합니다.

기본 키 문제#

기본 키 오류가 발생하면 다음을 수행합니다.

1. 해당 테이블이 커스텀 기본 키를 사용하는지 확인합니다.
2. configure_table :table_name, primary_key: :custom_id와 같이 명시적으로 구성합니다.

파티션된 테이블 문제#

파티션된 테이블에서는 다음을 수행합니다.

1. 스펙에 올바른 마이그레이션 유형을 표시했는지 확인합니다. migration: :gitlab_ci
2. 테이블을 파티션된 것으로 구성합니다. configure_table :p_ci_builds, partitioned: true
3. 필요하면 데이터베이스를 지정합니다. database: :ci

향후 버전#

새 버전이 릴리스되면 이 문서에 다음 내용이 추가됩니다.

• 이전 버전에서의 마이그레이션 가이드
• 각 버전의 새 기능
• 지원 중단 안내