DuckDB 고급 활용
시니어 DBA와 데이터 엔지니어를 위한 DuckDB 기반 로컬·파일 레이크 분석 설계와 운영 핸드북
최근 수정된 챕터
DuckDB의 단일 프로세스 write 모델, read-only 공유, extension 보안, untrusted SQL 방어 기준을 정리합니다.
in-memory, file-backed database, ATTACH, read-only 연결, WAL, checkpoint를 운영 관점으로 정리합니다.
CSV 자동 추론, 명시 스키마, JSON 추출과 반정형 데이터 수집의 실전 기준을 정리합니다.
dbt-duckdb, MotherDuck, Ibis를 DuckDB 기반 분석 운영에 편입하는 기준과 한계를 정리합니다.
DuckDB의 Friendly SQL, table macro, PIVOT/UNPIVOT을 분석 코드 품질로 연결합니다.
DuckDB는 "작은 SQLite 대체재"가 아니라 프로세스 안에 들어오는 분석용 OLAP 엔진입니다. 서버를 띄우지 않고도 CSV, JSON, Parquet, S3, Arrow, Pandas, Polars, Iceberg, Delta, DuckLake를 SQL로 다룹니다. 분석 워크로드 대부분은 로컬 파일과 오브젝트 스토리지를 데이터베이스처럼 쓸 수 있습니다.
이 핸드북은 시니어 DBA, 데이터 엔지니어, Analytics Engineer가 DuckDB를 분석에 본격적으로 쓸 때 필요한 판단 기준과 운영 습관을 정리합니다. 초급 설치 튜토리얼은 건너뛰고, 어떤 데이터를 바로 스캔하고 어떤 데이터는 DuckDB 테이블로 적재할지, Parquet row group과 파티션을 어떻게 설계할지, 메모리와 임시 디렉터리를 어떻게 잡을지에 집중합니다.
기준선
기준일은 2026-05-14입니다. DuckDB current 문서의 1.5 라인과 Python client 1.5.2를 기본으로 삼되, 운영 안정성이 중요한 환경이라면 1.4 LTS 라인의 수명과 차이도 함께 살피도록 정리했습니다.
대상 독자
| 독자 | 이미 알고 있다고 보는 것 | 이 책에서 얻을 것 |
|---|---|---|
| 시니어 DBA | SQL, 실행 계획, 인덱스, 동시성, 백업/복구 개념 | DuckDB를 OLTP DB가 아니라 분석 실행 엔진으로 운영하는 기준 |
| 데이터 엔지니어 | Parquet, S3, 배치 파이프라인, 데이터 레이크 | 파일 레이크를 DuckDB로 탐색·검증·마트화하는 패턴 |
| Analytics Engineer | dbt, marts, BI, Python notebook | 로컬 재현 가능한 분석 SQL과 템플릿 |
| 플랫폼 리드 | 리소스 제한, 보안, 배포, 관측 | embedded DB를 공유 환경에서 안전하게 쓰는 guardrail |
운영 모델
설계 원칙
- DuckDB는 분석용 실행 엔진이다: 장기 OLTP 서버, 멀티 프로세스 쓰기 DB, 권한 관리 서버처럼 다루지 않습니다.
- 파일을 먼저 읽고, 반복·조인-heavy 데이터만 적재한다: Parquet는 직접 스캔이 강하지만 반복 조인과 통계가 필요하면 DuckDB 테이블이 유리합니다.
- Parquet row group과 파티션이 성능 설계의 중심이다: 필터 pushdown, 병렬성, 작은 파일 문제를 함께 봅니다.
- 메모리 한도만 믿지 않는다: blocking operator, temp directory,
threads,preserve_insertion_order를 같이 관리합니다. - 확장은 기능이자 공급망이다:
httpfs,parquet,json같은 핵심 확장과 community/unsigned 확장의 보안 수준을 분리합니다. - 분석 코드는 재현 가능해야 한다: 세션 설정, 입력 파일 목록, DuckDB 버전, extension 버전을 함께 남깁니다.
목차
Part 1. 시작과 기준선
포지셔닝과 적합한 워크로드
DuckDB가 빛나는 분석 워크로드와 피해야 할 운영 시나리오를 구분합니다.
버전·설치·런타임 기준
current 1.5, 1.4 LTS, CLI, Python, extension 버전을 운영 기준선으로 고정합니다.
연결·스토리지 모델
in-memory, file-backed DB, ATTACH, read-only 연결, WAL, checkpoint를 정리합니다.
실행 가능한 예제 번들
작은 CSV/JSON 샘플과 SQL 스크립트로 수집, Parquet 변환, profiling을 직접 실행합니다.
Part 2. 파일·레이크 분석
CSV·JSON 수집
자동 추론과 명시 스키마, 불량 파일, JSON 추출을 분석 파이프라인으로 바꿉니다.
Parquet 레이크 모델링
Parquet 직접 스캔, metadata, row group, compression, materialization 기준을 다룹니다.
다중 파일·스키마 진화
glob, filename, union_by_name, 스키마 계약과 drift 감지 패턴을 정리합니다.
파티션 쓰기와 오브젝트 스토리지
Hive partitioning, S3 secrets, multipart write, 작은 파일 문제를 운영 관점으로 봅니다.
Lakehouse 포맷
Iceberg, Delta, DuckLake를 DuckDB에서 읽고 쓰는 범위와 안정성 기준을 잡습니다.
Part 3. 분석 SQL·연동
Friendly SQL과 매크로
GROUP BY ALL, SELECT * EXCLUDE, PIVOT, table macro로 분석 SQL을 압축합니다.
시계열·분석 SQL
ASOF JOIN, window, QUALIFY, sampling, 분석용 join 패턴을 정리합니다.
중첩·반정형 데이터
JSON, STRUCT, LIST, VARIANT 기준으로 semi-structured 데이터를 분석 모델로 바꿉니다.
Python·Arrow·Polars·BI
notebook, Arrow zero-copy, Pandas/Polars replacement scan, BI 연결 습관을 다룹니다.
dbt·MotherDuck·Ibis 생태계
dbt-duckdb, MotherDuck, Ibis를 DuckDB 운영 모델에 어디까지 편입할지 판단합니다.
Materialization·Index·통계
CTAS, persistent table, zonemap, ART index, ANALYZE를 성능 판단으로 연결합니다.
Part 4. 성능·운영
성능 프로파일링
EXPLAIN, EXPLAIN ANALYZE, profiling output으로 병목을 읽는 방법입니다.
벤치마크·프로파일링 실습
파일 레이아웃과 세션 설정을 바꿔 같은 쿼리의 plan과 실행 시간을 비교합니다.
메모리·spill·실패 모드
larger-than-memory, temp directory, OOM, blocking operator, thread 제한을 다룹니다.
동시성·보안·운영
단일 프로세스 write 모델, read-only 공유, extension 보안, untrusted SQL 방어입니다.
보안 Hardening 체크리스트
로컬 노트북, CI 배치, 내부 분석 서비스별 허용/금지 설정을 표준화합니다.
Part 5. 부록
템플릿
DuckDB 세션 설정, S3 secret, Parquet 점검, OOM 대응, 파티션 설계 템플릿입니다.
참고 자료
공식 문서와 릴리스 근거를 주제별로 묶었습니다.
검증 리포트
문서 구조, 근거, 버전 기준, 검증 명령 결과를 추적합니다.
업데이트 내역
DuckDB 릴리스와 extension 변화를 추적하는 변경 로그입니다.
이 책이 일부러 다루지 않는 것
- SQL 입문 문법 전체
- 대규모 중앙 warehouse를 DuckDB만으로 대체하는 아키텍처
- 무제한 동시 사용자용 DB 서버 운영
- DuckDB 내부 개발이나 C++ extension 구현
- 특정 클라우드 비용 계산의 세부 견적
먼저 읽을 공식 문서
- DuckDB 1.5.0 announcement
- Release Calendar
- Python API
- Reading and Writing Parquet Files
- Tuning Workloads
- S3 API Support
- Concurrency
- Securing DuckDB