대량의 레코드를 한 번에 저장해야 할 때가 있습니다. 컬렉션을 순회하면서 각 레코드를 개별적으로 저장하는 방식은 비효율적입니다. Rails 6에서 도입된 insert_all은 행 수준(즉, Hash 객체 사용)에서 동작합니다. GitLab은 이를 바탕으로 ActiveRecord 객체를 안전하고 간단하게 대량 삽입할 수 있는 API 세트를 추가했습니다.

대량 삽입을 위한 ApplicationRecord 준비#

모델 클래스가 대량 삽입 API를 활용하려면 먼저 BulkInsertSafe concern을 포함해야 합니다:

class MyModel < ApplicationRecord
  # 다른 include 구문
  # ...
  include BulkInsertSafe # 마지막에 포함

  # ...
end

BulkInsertSafe concern은 두 가지 기능을 합니다:

• 모델 클래스에 대해 대량 삽입과 관련하여 안전하게 사용할 수 없는 ActiveRecord API를 사용하는지 검사합니다(자세한 내용은 아래 참조).

• 한 번에 많은 레코드를 삽입할 수 있는 새로운 클래스 메서드 bulk_insert!와 bulk_upsert!를 추가합니다.

bulk_insert! 및 bulk_upsert!로 레코드 삽입하기#

대상 클래스가 BulkInsertSafe의 검사를 통과하면, 다음과 같이 ActiveRecord 모델 객체 배열을 삽입할 수 있습니다:

records = [MyModel.new, ...]

MyModel.bulk_insert!(records)

bulk_insert! 호출은 항상 새 레코드 삽입을 시도합니다. 반면, 이미 존재하지 않는 레코드는 삽입하면서 기존 레코드는 새로운 값으로 대체하고 싶다면 bulk_upsert!를 사용할 수 있습니다:

records = [MyModel.new, existing_model, ...]

MyModel.bulk_upsert!(records, unique_by: [:name])

이 예에서 unique_by는 레코드가 고유한 것으로 간주되는 칼럼을 지정하며, 삽입 이전에 해당 레코드가 존재했던 경우 업데이트됩니다. 예를 들어, existing_model에 name 속성이 있고 같은 name 값을 가진 레코드가 이미 존재한다면, 해당 필드는 existing_model의 값으로 업데이트됩니다.

unique_by 파라미터는 Symbol로도 전달할 수 있으며, 이 경우 칼럼이 고유한 것으로 간주되는 데이터베이스 인덱스를 지정합니다:

MyModel.bulk_insert!(records, unique_by: :index_on_name)

레코드 유효성 검사#

bulk_insert! 메서드는 records를 트랜잭션 방식으로 삽입하는 것을 보장하며, 삽입 전에 각 레코드에 대해 유효성 검사를 실행합니다. 유효성 검사에 실패하는 레코드가 있으면 오류가 발생하고 트랜잭션이 롤백됩니다. :validate 옵션을 통해 유효성 검사를 비활성화할 수 있습니다:

MyModel.bulk_insert!(records, validate: false)

배치 크기 설정#

records 수가 특정 임계값을 초과하는 경우, 삽입은 여러 배치로 나뉘어 실행됩니다. 기본 배치 크기는 BulkInsertSafe::DEFAULT_BATCH_SIZE에 정의되어 있습니다. 기본 임계값이 500이라고 가정하면, 950개의 레코드를 삽입하면 두 개의 배치(크기 500과 450)가 순차적으로 기록됩니다. :batch_size 옵션으로 기본 배치 크기를 재정의할 수 있습니다:

MyModel.bulk_insert!(records, batch_size: 100)

동일한 950개의 레코드를 기준으로 하면, 이 경우 10개의 배치가 기록됩니다. 이는 발생하는 INSERT 구문의 수에도 영향을 주므로, 코드 성능에 미치는 영향을 반드시 측정해야 합니다. 데이터베이스가 처리해야 하는 INSERT 구문의 수와 각 INSERT의 크기 및 비용 사이에는 트레이드오프가 있습니다.

중복 레코드 처리#

이 파라미터는 bulk_insert!에만 적용됩니다. 기존 레코드를 업데이트하려는 경우 대신 bulk_upsert!를 사용하세요.

삽입하려는 레코드 중 일부가 이미 존재하여 기본 키 충돌이 발생할 수 있습니다. 이 문제를 해결하는 두 가지 방법이 있습니다: 오류를 발생시켜 빠르게 실패하거나 중복 레코드를 건너뛰는 것입니다. bulk_insert!의 기본 동작은 빠르게 실패하고 ActiveRecord::RecordNotUnique 오류를 발생시키는 것입니다.

이 동작이 바람직하지 않다면 skip_duplicates 플래그를 사용하여 중복 레코드를 건너뛸 수 있습니다:

MyModel.bulk_insert!(records, skip_duplicates: true)

안전한 대량 삽입을 위한 요건#

ActiveRecord의 퍼시스턴스 API의 대부분은 콜백 개념을 중심으로 구축되어 있습니다. 이러한 콜백 중 많은 것들이 save나 create와 같은 모델 라이프사이클 이벤트에 응답하여 실행됩니다. 이러한 콜백은 저장되거나 생성되는 모든 인스턴스에 대해 호출되어야 하므로 대량 삽입에는 사용할 수 없습니다. 레코드가 대량으로 삽입될 때는 이 이벤트들이 실행되지 않으므로 콜백 사용을 방지합니다.

어떤 콜백이 명시적으로 허용되는지에 대한 세부 사항은 BulkInsertSafe에 정의되어 있습니다. 세부 사항은 모듈 소스 코드를 참조하세요. 클래스가 명시적으로 안전하다고 지정되지 않은 콜백을 사용하면서 include BulkInsertSafe를 포함하면 애플리케이션이 오류와 함께 실패합니다.

BulkInsertSafe와 InsertAll 비교#

내부적으로 BulkInsertSafe는 InsertAll을 기반으로 하며, 언제 전자를 선택해야 할지 궁금할 수 있습니다. 결정을 돕기 위해 이 클래스들의 주요 차이점을 아래 표에 정리했습니다.

요약하자면, BulkInsertSafe는 대량 삽입을 ActiveRecord 객체와 삽입이 일반적으로 동작하는 방식에 더 가깝게 만듭니다. 하지만 단순히 원시 데이터를 대량으로 삽입하기만 하면 된다면 insert_all이 더 효율적입니다.

has_many 연관 관계를 대량 삽입하기#

일반적인 사용 사례는 관계의 소유자 측을 통해 연관된 관계의 컬렉션을 저장하는 것입니다. 여기서 소유된 관계는 has_many 클래스 메서드를 통해 소유자와 연결됩니다:

owner = OwnerModel.new(owned_relations: array_of_owned_relations)
# `owned_relations`의 각 레코드를 하나씩 저장합니다
owner.save!

이 방식은 owned_relations의 모든 레코드에 대해 개별 INSERT와 트랜잭션을 발생시키므로, array_of_owned_relations가 크면 비효율적입니다. 이를 해결하기 위해 BulkInsertableAssociations concern을 사용하여 소유자가 대량 삽입에 안전한 연관 관계를 정의한다고 선언할 수 있습니다:

class OwnerModel < ApplicationRecord
  # 다른 include 구문
  # ...
  include BulkInsertableAssociations # 마지막에 포함

  has_many :my_models
end

여기서 my_models는 대량 삽입이 이루어지려면 (앞서 설명한 대로) BulkInsertSafe로 선언되어야 합니다. 이제 아직 저장되지 않은 레코드를 다음과 같이 삽입할 수 있습니다:

BulkInsertableAssociations.with_bulk_insert do
  owner = OwnerModel.new(my_models: array_of_my_model_instances)
  # 단일 대량 삽입으로 `my_models`를 저장합니다 (여러 배치로 나뉠 수 있음)
  owner.save!
end

이 블록 내에서 BulkInsertSafe가 아닌 관계도 여전히 저장할 수 있습니다. 이 경우 블록 외부에서 save를 호출한 것처럼 처리됩니다.

알려진 제한 사항#

이 API들을 사용하는 데는 몇 가지 제한 사항이 있습니다:

• BulkInsertableAssociations:

현재 has_many 관계와만 호환됩니다.

• has_many through: ... 관계는 아직 지원하지 않습니다.

또한, 입력 데이터는 최대 약 1000개 레코드로 제한하거나 대량 삽입 호출 전에 이미 배치로 나눠져 있어야 합니다. INSERT 구문은 단일 트랜잭션으로 실행되므로, 대량의 레코드에 대해서는 데이터베이스 안정성에 부정적인 영향을 미칠 수 있습니다.