익스텐션 배포

익스텐션 배포 (Extension Distribution)

DuckDB 익스텐션 바이너리가 어떤 플랫폼에 배포되는지, 서명(signing)이 어떻게 동작하는지, 커스텀 저장소를 어떻게 만드는지 정리한 페이지예요. 익스텐션을 직접 배포하거나 특정 환경에서 설치할 때 유용해요.

출처: 문서

본문

플랫폼 (Platforms)

익스텐션 바이너리는 여러 플랫폼(아래 참고)에 배포돼요. 특정 익스텐션의 패키지가 없는 플랫폼에서는 사용자가 소스에서 빌드하고 결과 바이너리를 수동으로 설치할 수 있어요.

모든 공식 익스텐션은 다음 플랫폼에 배포돼요.

플랫폼 이름	운영체제	아키텍처	CPU 타입
`linux_amd64`	Linux	x86_64 (AMD64)
`linux_arm64`	Linux	AArch64 (ARM64)	AWS Graviton, Snapdragon 등.
`osx_amd64`	macOS	x86_64 (AMD64)	Intel
`osx_arm64`	macOS	AArch64 (ARM64)	Apple Silicon M1, M2 등.
`windows_amd64`	Windows	x86_64 (AMD64)	Intel, AMD 등.
`windows_arm64`	Windows	AArch64 (ARM64)	Copilot+ PC with Qualcomm CPU

일부 익스텐션은 다음 플랫폼에도 배포돼요:

windows_amd64_mingw
wasm_eh와 wasm_mvp (DuckDB-Wasm의 익스텐션 참고)

위 목록 밖의 플랫폼(예: linux_arm64_android)에는 익스텐션을 공식 배포하지 않아요.

익스텐션 서명 (Extensions Signing)

서명된 익스텐션 (Signed Extensions)

익스텐션은 암호화 키로 서명할 수 있어요. 기본적으로 DuckDB는 내장 공개 키를 사용해 익스텐션을 로드하기 전에 그 무결성을 검증해요. 모든 코어와 커뮤니티 익스텐션은 DuckDB 팀이 서명해요.

익스텐션을 서명하면 배포가 단순해져요. 그래서 HTTPS 없이 HTTP로 배포할 수 있는데, HTTPS 자체는 익스텐션(httpfs)을 통해 지원돼요.

서명되지 않은 익스텐션 (Unsigned Extensions)

경고 (Warning) 신뢰할 수 있는 출처에서만 서명되지 않은 익스텐션을 로드하세요. HTTP로 서명되지 않은 익스텐션을 로드하는 것은 피하세요. DuckDB를 안전하게 설정하는 방법에 대한 지침은 Securing DuckDB 페이지를 참고하세요.

자신의 익스텐션이나 서드파티 익스텐션을 로드하려면 allow_unsigned_extensions 플래그를 활성화해야 해요. CLI 클라이언트에서 서명되지 않은 익스텐션을 로드하려면 시작 시 -unsigned 플래그를 넘겨요:

duckdb -unsigned

이제 서명 여부와 무관하게 어떤 익스텐션이든 로드할 수 있어요:

LOAD './some/local/ext.duckdb_extension';

클라이언트 API에서는 allow_unsigned_extensions 데이터베이스 구성 옵션을 설정해야 해요. 각 Client API 문서를 참고하세요. 예를 들어 Python 클라이언트의 경우 Python API 문서의 Loading and Installing Extensions 섹션을 참고해요.

바이너리 호환성 (Binary Compatibility)

바이너리 호환성 문제를 피하기 위해 DuckDB가 배포하는 바이너리 익스텐션은 특정 DuckDB 버전과 플랫폼 양쪽에 묶여 있어요. 이는 DuckDB가 자신과 로드 가능한 익스텐션 간의 바이너리 호환성을 자동으로 감지할 수 있음을 의미해요. 다른 버전이나 플랫폼용으로 컴파일된 익스텐션을 로드하려 하면 DuckDB가 에러를 던지고 익스텐션 로드를 거부해요.

커스텀 저장소 만들기 (Creating a Custom Repository)

커스텀 DuckDB 익스텐션 저장소를 만들 수 있어요. DuckDB 저장소는 특정 구조로 익스텐션 파일을 제공하는 HTTP, HTTPS, S3 또는 로컬 파일 기반 디렉토리예요. 이 구조는 "S3에서 익스텐션 직접 다운로드" 섹션에 설명되어 있고, 로컬 경로와 원격 서버 모두 동일해요. 예를 들어:

base_repository_path_or_url
└── v1.0.0
    └── osx_arm64
        ├── autocomplete.duckdb_extension
        ├── httpfs.duckdb_extension
        ├── icu.duckdb_extension
        ├── inet.duckdb_extension
        ├── json.duckdb_extension
        ├── parquet.duckdb_extension
        ├── tpcds.duckdb_extension
        ├── tpcds.duckdb_extension
        └── tpch.duckdb_extension

저장소를 설정하는 데 필요한 모든 코드와 스크립트는 extension-template 저장소에서 볼 수 있어요.

커스텀 저장소에서 익스텐션을 설치할 때 DuckDB는 gzipped 버전과 non-gzipped 버전 둘 다 검색해요. 예를 들어:

INSTALL icu FROM '⟨custom_repository⟩';

이 문을 실행하면 먼저 저장소 디렉토리 구조에서 icu.duckdb_extension.gz를 찾고, 그다음 icu.duckdb_extension을 찾아요.

커스텀 저장소가 HTTPS나 S3로 제공된다면 httpfs 익스텐션이 필요해요. DuckDB는 HTTPS나 S3로 설치를 시도할 때 httpfs 익스텐션을 자동 로드하려고 해요.

더 알아보기 (Learn more)

고급 설치 방법 — 소스 빌드·수동 설치.
확장 개요 — 익스텐션 설치·로드·자동 로드.