DuckDB 고급 활용
시니어 DBA와 데이터 엔지니어를 위한 DuckDB 기반 로컬·파일 레이크 분석 설계와 운영 핸드북
최근 수정된 챕터
같은 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 기반 분석 운영에 편입하는 기준과 한계를 정리합니다.
2.0 전환에서 먼저 확인할 것
- 저장 파일: 2.0이 기본 포맷으로 새로 만드는 파일은 이전 엔진에서 열 수 없습니다. 기존 파일은 2.0으로 열어도 저장 버전을 유지합니다.
- SQL·Python: lambda, 정규식, 0 나누기,
MERGE, NULL 추론과 Python 3.11+ 요구를 점검합니다. - 실행 경로: Quack은 서버를 통한 다중 클라이언트 경로입니다. 여러 프로세스가 같은 파일을 직접 쓰는 방식과 혼동하지 않습니다.
2.0 발표 · 마이그레이션 가이드 · 업데이트 내역.
DuckDB는 "작은 SQLite 대체재"가 아니라 프로세스 안에 들어오는 분석용 OLAP 엔진입니다. 서버를 띄우지 않고도 CSV, JSON, Parquet, S3, Arrow, Pandas, Polars, Iceberg, Delta, DuckLake를 SQL로 다룹니다. 분석 워크로드 대부분은 로컬 파일과 오브젝트 스토리지를 데이터베이스처럼 쓸 수 있습니다.
이 핸드북은 시니어 DBA, 데이터 엔지니어, Analytics Engineer가 DuckDB를 분석에 본격적으로 쓸 때 필요한 판단 기준과 운영 습관을 정리합니다. 초급 설치 튜토리얼은 건너뛰고, 어떤 데이터를 바로 스캔하고 어떤 데이터는 DuckDB 테이블로 적재할지, Parquet row group과 파티션을 어떻게 설계할지, 메모리와 임시 디렉터리를 어떻게 잡을지에 집중합니다.
기준선
2026-10-26 기준 최신 안정판은 10월 21일 출시된 DuckDB 2.0.0 LTS입니다. 1.5는 2027년 3월까지 지원이 연장됐으며, 1.4 LTS는 2026년 11월 17일 지원이 끝납니다. 새 저장 포맷과 SQL 동작 변경을 shadow workload에서 검증한 뒤 전환합니다.
2.0 기능별 읽기 경로
| 필요한 작업 | 해당 장 |
|---|---|
| SQL·Python 호환성과 rollback | 버전 기준, Python |
| 변경 행 감사와 증분 집계 | 트리거와 materialization |
| 변경 CTE·변수·중첩 스키마 | Friendly SQL |
| 벡터 top-k 검색과 재현 가능한 샘플 | 분석 SQL |
| 비동기 I/O와 메모리 예산 | 프로파일링, 메모리 |
| DuckLake 1.1·Delta·Iceberg | Lakehouse |
| 자체 서명 확장과 서버 접근 | 보안, 연결 모델 |
대상 독자
| 독자 | 이미 알고 있다고 보는 것 | 이 책에서 얻을 것 |
|---|---|---|
| 시니어 DBA | SQL, 실행 계획, 인덱스, 동시성, 백업/복구 개념 | DuckDB를 OLTP DB가 아니라 분석 실행 엔진으로 운영하는 기준 |
| 데이터 엔지니어 | Parquet, S3, 배치 파이프라인, 데이터 레이크 | 파일 레이크를 DuckDB로 탐색·검증·마트화하는 패턴 |
| Analytics Engineer | dbt, marts, BI, Python notebook | 로컬 재현 가능한 분석 SQL과 템플릿 |
| 플랫폼 리드 | 리소스 제한, 보안, 배포, 관측 | embedded DB를 공유 환경에서 안전하게 쓰는 guardrail |
운영 모델
설계 원칙
- DuckDB는 분석용 실행 엔진이다: OLTP·다중 테넌트 권한 서버로 가정하지 않습니다. 2.0의 Quack 서버 연결과 embedded 파일 직접 접근은 동시성 경계가 다릅니다.
- 파일을 먼저 읽고, 반복·조인-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가 빛나는 분석 워크로드와 피해야 할 운영 시나리오를 구분합니다.
버전·설치·런타임 기준
2.0 LTS와 1.5 전환 경로, 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 2.0.0 announcement
- Release Calendar
- Python API
- Reading and Writing Parquet Files
- Tuning Workloads
- S3 API Support
- Concurrency
- Securing DuckDB