익스텐션 로드하기

익스텐션 로드하기 (Load Extensions)

DuckDB-Wasm의 (동적) 익스텐션 로딩은 일반 DuckDB의 익스텐션 로딩을 본떠 만들어졌어요. 다만 플랫폼 차이 때문에 몇 가지 중요한 차이점이 있어요. 코어, 커뮤니티, 외부 익스텐션의 점점 늘어나는 하위 집합이 지원돼요.

출처: 문서

본문

개요 (Overview)

DuckDB-Wasm의 (동적) 익스텐션 로딩은 일반 DuckDB의 익스텐션 로딩을 본떠 만들어졌어요. 다만 플랫폼 차이로 인한 몇 가지 관련 차이점이 있어요. 코어, 커뮤니티, 외부 익스텐션의 점점 늘어나는 하위 집합이 지원돼요.

이 페이지는 익스텐션 형식, INSTALL과 LOAD가 어떻게 동작하는지, 자동 로드, 어떤 익스텐션을 사용할 수 있는지, 서명, 그리고 익스텐션이 어떻게 가져와지고 제공되는지 설명해요.

형식 (Format)

DuckDB의 익스텐션은 dlopen으로 동적으로 로드되는 바이너리예요. 바이너리에 암호학적 서명이 추가돼요.

DuckDB-Wasm의 익스텐션은 Emscripten의 dlopen으로 동적으로 로드되는 일반 Wasm 파일이에요. Wasm 파일에 duckdb_signature라는 WebAssembly custom section으로 암호학적 서명이 추가돼요. 이렇게 하면 파일이 유효한 WebAssembly 파일로 유지돼요.

현재 이 custom section은 마지막에 있어야 하지만, 이 요구 사항은 향후 완화될 수 있어요.

INSTALL과 LOAD

네이티브 DuckDB 임베딩에서 INSTALL 시맨틱은 gzip에서 가져와 압축 해제하고 데이터를 로컬 디스크에 저장하는 것이에요. 네이티브 DuckDB 임베딩에서 LOAD 시맨틱은 (선택적으로) 서명 검사를 수행하고 메인 DuckDB 바이너리와 함께 바이너리를 동적으로 로드하는 것이에요.

DuckDB-Wasm에서 INSTALL은 영구적인 설치를 수행하지 않아요 — 세션 간 저장소가 없기 때문이에요. 대신 익스텐션이 어디서 가져올지(예: INSTALL ⟨name⟩ FROM community)만 기록하고, 실제 가져오기는 LOAD로 미뤄요. LOAD 연산은 (즉석에서 압축 해제하며) 가져오고, 서명 검사를 수행하며, Emscripten의 dlopen 구현으로 동적으로 로드해요.

자동 로드 (Autoloading)

자동 로드(Autoloading), 즉 DuckDB가 익스텐션 기능을 즉시(온 더 플라이) 추가할 수 있는 기능은 DuckDB-Wasm에서 기본으로 활성화돼요.

사용 가능한 익스텐션 (Available Extensions)

점점 늘어나는 익스텐션 하위 집합이 DuckDB-Wasm에서 지원돼요. 코어 익스텐션, 커뮤니티 익스텐션, 외부 익스텐션을 망라해요. 대부분은 DuckDB-Wasm 바이너리에 번들링되지 않고, 자동 로드되거나 명시적으로 로드될 때 즉시 가져와져요. 예를 들어:

-- 코어 익스텐션을 명시적으로 로드
LOAD icu;

-- 지리공간 지원을 위해 spatial 로드
INSTALL spatial;
LOAD spatial;

-- 커뮤니티 익스텐션 설치 후 로드
INSTALL h3 FROM community;
LOAD h3;

-- 저장소에서 외부 익스텐션 설치
INSTALL sqlite_scanner FROM 'https://extensions.duckdb.org';
LOAD sqlite_scanner;

DuckDB-Wasm에서 흔히 사용되는 코어 익스텐션은 다음과 같아요:

WebAssembly는 본질적으로 추가 플랫폼이에요. 일부 익스텐션이 네이티브 기능과 일치하지 못하게 하거나 다르게 동작하게 만드는 플랫폼별 제한이 있을 수 있어요. DuckDB 호스팅 익스텐션에 대한 관련 차이점은 아래에 문서화돼 있어요.

HTTPFS

네이티브 HTTPFS 익스텐션은 DuckDB-Wasm에 컴파일되지 않아요 — HTTPS 기능이 브라우저라는 추가 계층을 거쳐야 하기 때문이에요. 이는 네이티브 대비 차이점과 몇 가지 제한을 더해요. 대신 DuckDB-Wasm은 같은 기능의 별도 JavaScript 구현을 제공해요. LOAD httpfs;를 실행하면 이 재구현된 HTTP 스택을 사용하게 되는데, 이는 대부분의 용도에서 네이티브 익스텐션과 상호 교환 가능하지만 브라우저가 부과하는 보안 규칙을 따라야 하므로 모든 사용 사례를 지원하지는 않아요.

특히:

• 요청은 항상 HTTPS로 업그레이드돼요.
• 브라우저의 CORS 정책 때문에 어떤 데이터 요청도 (CORS 헤더로) DuckDB-Wasm 인스턴스를 호스팅하는 사이트가 그 데이터에 접근하는 것을 허용하는 사이트를 대상으로 해야 해요.

CORS에 대한 더 자세한 정보는 MDN 웹사이트가 훌륭한 자료예요. 원격 파일에 대한 쿼리가 네트워크 에러로 실패하면 Troubleshoot을 참고해요.

익스텐션 서명 (Extension Signing)

일반 DuckDB 익스텐션과 마찬가지로, DuckDB-Wasm 익스텐션도 기본적으로 LOAD 시 서명을 확인해 익스텐션이 변조되지 않았는지 검증해요. 익스텐션 서명 검증은 구성 옵션으로 비활성화할 수 있어요.

서명은 바이너리 자체의 속성이므로, DuckDB 익스텐션을 복사하면(예: 다른 위치에서 제공하기 위해) 여전히 유효한 서명을 유지해요(예: 로컬 개발).

DuckDB-Wasm 익스텐션 가져오기 (Fetching DuckDB-Wasm Extensions)

공식 DuckDB 익스텐션은 extensions.duckdb.org에서 제공되며, 이는 default_extension_repository 옵션의 기본값이기도 해요. 익스텐션을 설치할 때 extensions.duckdb.org/$duckdb_version_hash/$duckdb_platform/$name.duckdb_extension.gz 같은 관련 URL이 만들어져요.

DuckDB-Wasm 익스텐션은 로드할 때만 가져와지며, URL은 extensions.duckdb.org/duckdb-wasm/$duckdb_version_hash/$duckdb_platform/$name.duckdb_extension.wasm 형태예요.

폴더 구조에 추가 duckdb-wasm이 더해지고 파일이 .wasm 파일로 제공된다는 점을 참고해요.

DuckDB-Wasm 익스텐션은 Brotli 압축으로 사전 압축되어 제공돼요. 브라우저에서 가져올 때 익스텐션은 투명하게 압축 해제돼요. duckdb-wasm 익스텐션을 수동으로 가져오려면 curl --compressed extensions.duckdb.org/<...>/icu.duckdb_extension.wasm을 사용할 수 있어요.

서드파티 저장소에서 익스텐션 제공하기 (Serving Extensions from a Third-Party Repository)

일반 DuckDB와 마찬가지로 SET custom_extension_repository = 'https://some.url.com'을 사용하면 이후 로드는 https://some.url.com/duckdb-wasm/$duckdb_version_hash/$duckdb_platform/$name.duckdb_extension.wasm에서 시도돼요.

익스텐션에 대한 GET 요청은 브라우저가 연결을 허용하려면 CORS 활성화가 되어야 한다는 점을 참고해요. 로드가 실패하면 Troubleshoot을 참고해요.

도구 (Tooling)

DuckDB-Wasm과 그 익스텐션 모두 최신 패키징된 Emscripten 툴체인으로 컴파일됐어요.

더 알아보기 (Learn more)

• Deploy — 커스텀 엔드포인트에서 익스텐션 제공·미러링.
• Core Extensions — 모든 DuckDB 클라이언트에서 사용 가능한 코어 익스텐션.
• Community Extensions — INSTALL … FROM community로 설치 가능한 서드파티 익스텐션.
• Import Data — Parquet, JSON, Wasm-flavored httpfs 익스텐션으로 파일 읽기.
• Troubleshoot — 커스텀 저장소에서 익스텐션 로드 시 CORS 에러.