메모리 부족

메모리 부족 (Out-of-Memory) 문제 해결 (oom)

DuckDB로 작업하다 보면 가끔 메모리(OOM, Out-of-Memory) 오류를 만날 때가 있어요. 이 페이지에서는 그런 상황에서 시도해 볼 수 있는 설정 옵션과 스키마·인덱스 측면의 팁을 정리해 드릴게요. 대부분은 한두 줄의 SET 문으로 해결할 수 있죠.

출처: DuckDB 공식 문서 — oom

설정 옵션 (Configuration Options)

DuckDB에서 메모리 부족 문제를 겪고 있다면, 다음 설정 옵션들을 하나씩 조정해 보세요.

SET threads = ... 명령으로 스레드 수를 줄이세요.
메모리 한도(memory limit)를 기본값인 80%보다 낮게 설정하면 메모리 부족 오류를 막는 데 도움이 돼요. 다소 역설적으로 들리지만, DuckDB의 일부 연산은 데이터베이스의 버퍼 매니저(buffer manager)를 우회하므로 메모리 한도보다 더 많은 메모리를 예약할 수 있기 때문이에요. 이 상황이 발생하면(예: 운영체제나 OOM 리퍼(reaper) 프로세스에 의해 DuckDB가 종료되는 경우) SET memory_limit = '...' 문을 사용해 총 시스템 메모리의 50~60% 정도로 메모리 한도를 설정하세요.
쿼리가 파일에서 많은 양의 데이터를 읽거나 많은 양의 데이터를 쓴다면 preserve_insertion_order 옵션을 false로 설정해 보세요: SET preserve_insertion_order = false.

요약하면, 다음 설정들을 시도해 보는 거예요:

SET threads = ⟨lower_than_the_number_of_available_threads⟩;
SET memory_limit = ⟨lower_than_80%_of_system_memory⟩;
SET preserve_insertion_order = false;

스키마와 인덱스 (Schema and Indexes)

메모리가 제한된 환경에서 실행한다면, 더 작은 데이터 타입(예: TINYINT)을 사용하면 쿼리를 완료하는 데 필요한 메모리와 디스크 공간을 줄일 수 있어요. DuckDB의 비트패킹 압축(bitpacking compression) 덕분에 더 큰 데이터 타입에 저장된 작은 값은 디스크에서 더 큰 공간을 차지하지 않지만, 처리 중에는 더 많은 메모리를 차지해요. 그래서 컬럼을 만들 때 가능한 한 가장 제한적인 타입을 사용하는 것이 메모리 소비를 줄이는 데 필요해요.

인덱스는 메모리 소비를 크게 늘릴 수 있어요. 게다가 인덱스는 현재 버퍼 매니저로 관리되지 않습니다. 가능하면 인덱스 사용을 피하세요. 작업 부하가 큰 테이블의 인덱싱을 요구한다면, 이를 수용하도록 메모리 한도를 낮추는 것을 고려해 보세요.

메모리 부족