본문으로 바로가기
리옵트 핸드북
리옵트 핸드북
DuckDB 고급 활용

시작과 기준선

포지셔닝과 적합한 워크로드버전·설치·런타임 기준연결·스토리지 모델실행 가능한 예제 번들

파일·레이크 분석

CSV·JSON 수집Parquet 레이크 모델링다중 파일·스키마 진화파티션 쓰기와 오브젝트 스토리지Lakehouse 포맷

분석 SQL·연동

Friendly SQL과 매크로시계열·분석 SQL중첩·반정형 데이터Python·Arrow·Polars·BIdbt·MotherDuck·Ibis 생태계Materialization·Index·통계

성능·운영

성능 프로파일링벤치마크·프로파일링 실습메모리·spill·실패 모드동시성·보안·운영보안 Hardening 체크리스트

부록

템플릿참고 자료검증 리포트업데이트 내역
핸드북›DuckDB 고급 활용

DuckDB 고급 활용

시니어 DBA와 데이터 엔지니어를 위한 DuckDB 기반 로컬·파일 레이크 분석 설계와 운영 핸드북

최근 수정된 챕터

  • Python·Arrow·Polars·BI2026.07.01

    Python API, Arrow zero-copy, Pandas/Polars replacement scan, BI 연결을 실무 분석 흐름으로 정리합니다.

  • 동시성·보안·운영2026.06.20

    DuckDB의 단일 프로세스 write 모델, read-only 공유, extension 보안, untrusted SQL 방어 기준을 정리합니다.

  • 연결·스토리지 모델2026.06.20

    in-memory, file-backed database, ATTACH, read-only 연결, WAL, checkpoint를 운영 관점으로 정리합니다.

  • CSV·JSON 수집2026.06.20

    CSV 자동 추론, 명시 스키마, JSON 추출과 반정형 데이터 수집의 실전 기준을 정리합니다.

  • dbt·MotherDuck·Ibis 생태계2026.06.20

    dbt-duckdb, MotherDuck, Ibis를 DuckDB 기반 분석 운영에 편입하는 기준과 한계를 정리합니다.

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 라인의 수명과 차이도 함께 살피도록 정리했습니다.

대상 독자

독자이미 알고 있다고 보는 것이 책에서 얻을 것
시니어 DBASQL, 실행 계획, 인덱스, 동시성, 백업/복구 개념DuckDB를 OLTP DB가 아니라 분석 실행 엔진으로 운영하는 기준
데이터 엔지니어Parquet, S3, 배치 파이프라인, 데이터 레이크파일 레이크를 DuckDB로 탐색·검증·마트화하는 패턴
Analytics Engineerdbt, marts, BI, Python notebook로컬 재현 가능한 분석 SQL과 템플릿
플랫폼 리드리소스 제한, 보안, 배포, 관측embedded DB를 공유 환경에서 안전하게 쓰는 guardrail

운영 모델

설계 원칙

  1. DuckDB는 분석용 실행 엔진이다: 장기 OLTP 서버, 멀티 프로세스 쓰기 DB, 권한 관리 서버처럼 다루지 않습니다.
  2. 파일을 먼저 읽고, 반복·조인-heavy 데이터만 적재한다: Parquet는 직접 스캔이 강하지만 반복 조인과 통계가 필요하면 DuckDB 테이블이 유리합니다.
  3. Parquet row group과 파티션이 성능 설계의 중심이다: 필터 pushdown, 병렬성, 작은 파일 문제를 함께 봅니다.
  4. 메모리 한도만 믿지 않는다: blocking operator, temp directory, threads, preserve_insertion_order를 같이 관리합니다.
  5. 확장은 기능이자 공급망이다: httpfs, parquet, json 같은 핵심 확장과 community/unsigned 확장의 보안 수준을 분리합니다.
  6. 분석 코드는 재현 가능해야 한다: 세션 설정, 입력 파일 목록, 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

참고 자료

  • DuckDB Documentation
  • Core Extensions
  • Tuning Workloads

함께 보면 좋은 핸드북

Vercel 엔터프라이즈 AI 플랫폼

AI SDK, AI Gateway, Workflow, Sandbox, Queues를 중심으로 엔터프라이즈급 AI 제품을 설계·운영하는 완전판 가이드

엔터프라이즈 Eve 에이전트 개발

Vercel Eve 0.11.4 코드베이스를 기준으로 파일시스템 우선 에이전트의 핵심 기술, 보안 경계, 고급 운영 패턴을 정리한 실전 가이드

GA4 고급 애널리틱스 설계

Google Analytics 4 공식 문서 기반으로 계정·속성·스트림·이벤트·BigQuery 분석 체계를 설계하는 실무 핸드북

포지셔닝과 적합한 워크로드

DuckDB를 서버형 DB, 파일 포맷, 데이터프레임 도구와 비교해 언제 써야 하는지 정리합니다.

On this page

대상 독자운영 모델설계 원칙목차Part 1. 시작과 기준선Part 2. 파일·레이크 분석Part 3. 분석 SQL·연동Part 4. 성능·운영Part 5. 부록이 책이 일부러 다루지 않는 것먼저 읽을 공식 문서참고 자료