배포

배포 (Deploy)

개요

DuckDB-Wasm을 배포한다는 것은 브라우저가 그것들을 fetch하고 인스턴스화할 수 있도록 구성 요소들을 서빙하는 것을 의미해요. 이 페이지는 배포가 서빙해야 할 각 구성 요소, worker와 WebAssembly 변형이 어떻게 관련되는지, 확장이 어떻게 서빙·미러링되는지, 그리고 관련 보안 고려 사항을 설명해 드릴게요.

DuckDB-Wasm 배포는 다음 구성 요소에 접근해야 해요.

출처: 문서

본문

메인 라이브러리 구성 요소

이 구성 요소는 npm @duckdb/duckdb-wasm 패키지에서 TypeScript 또는 CommonJS JavaScript로 배포돼요. 세 가지 방법 중 하나로 배포할 수 있어요.

  • 애플리케이션과 함께 번들링
  • same-origin (하위)도메인에서 서빙하고 런타임에 포함
  • jsDelivr 같은 서드파티 CDN에서 서빙

그대로 서빙할 수는 없어요. 후속 파일 — worker와 WebAssembly 구성 요소 — 의 위치를 알아야 동작하므로 트랜스파일이 필요해요. 정확한 단계는 설정에 따라 달라요. 저장소의 예시들을 참고하세요. 예를 들어 shell.duckdb.org 배포는 셸 코드와 함께 메인 라이브러리를 트랜스파일하며(위 첫 방법), bare-browser 예시는 최소 설정을 보여줘요.

JS Worker 구성 요소

이것은 mvp, eh, coi 세 가지 다른 맛으로 분배되는 JavaScript 파일이며, 그대로 서빙해야 해요. 메인 라이브러리 구성 요소는 실제 위치를 알고 있어야 해요.

세 가지 변형은 세 가지 다른 WebAssembly 기능 집합을 대상으로 해요.

  • mvp는 WebAssembly 1.0 (MVP) 명세를 대상으로 함
  • eh는 성능을 향상시키는 Wasm 레벨 예외 처리가 추가된 WebAssembly를 대상으로 함
  • coi는 예외 처리와 스레딩이 있는 WebAssembly를 대상으로 하며, 병렬 쿼리 실행을 가능하게 함. 배포가 cross-origin isolated여야 함(Cross-Origin Isolation 참고)

세 개를 모두 서빙하고 selectBundle으로 라이브러리가 최적을 기능 감지하게 하거나, 단일 변형을 서빙하고 DuckDB-Wasm 라이브러리에 어떤 것을 쓸지 지시할 수 있어요. 서빙된 아티팩트는 맛에 따라 이름 지어지는데, 예를 들어 duckdb-browser-coi.worker.js예요. coi 맛은 wasm_threads 확장 플랫폼에 해당해요.

Wasm Worker 구성 요소

이것은 WebAssembly로 컴파일되어 브라우저가 인스턴스화하는 DuckDB 엔진 자체예요. JS Worker 구성 요소처럼 같은 세 가지 맛으로 제공되며, 각각 같은 맛의 JS worker와 짝을 이뤄요.

  • mvp — 예: duckdb-mvp.wasm, mvp JS worker가 로드함
  • eh — 예: duckdb-eh.wasm, eh JS worker가 로드함
  • coi — 예: duckdb-coi.wasm, coi JS worker가 로드함

각 JS worker는 자신의 맛의 WebAssembly 모듈을 로드하므로, 배포하는 JS worker에 해당하는 모듈(들)을 서빙해요. 세 JS worker를 모두 서빙하고 selectBundle이 최적을 기능 감지하게 한다면 세 모듈도 모두 서빙해요.

이 파일들을 서빙할 때 다음을 명심하세요.

  • 그대로 서빙해요. 메인 라이브러리 구성 요소와 달리 트랜스파일이나 번들링이 필요 없어요.
  • application/wasm 콘텐츠 타입으로 서빙해 브라우저가 효율적으로 컴파일할 수 있게 해요.
  • 메인 문서에서 도달 가능한 어디든 호스팅해요 — same-origin 또는 임의의 [하위]도메인. 메인 라이브러리 구성 요소는 번들 정의(mainModule 경로)를 통해 각 모듈의 위치를 알게 되므로, 모듈이 JavaScript 옆에 있을 필요는 없어요.

DuckDB 확장

DuckDB-Wasm용 DuckDB 확장은 네이티브 경우와 유사하게, 기본 확장 엔드포인트 https://extensions.duckdb.org에서 서명된 채 서빙돼요. duckdb-wasm을 배포한다면 관련 확장을 다른 엔드포인트에서 미러링하는 것을 고려할 수 있는데, 내부 네트워크에서 밀폐된(air-tight) 배포를 가능하게 할 수 있어요.

SET custom_extension_repository = '⟨https://some.endpoint.org/path/to/repository⟩';

기본 확장 저장소를 공개 https://extensions.duckdb.org에서 지정된 것으로 바꿔요. 확장은 여전히 서명되므로, 원래 저장소와 비슷한 구조로 확장을 다운로드·서빙하는 것이 최선의 경로예요. [Custom Repository 만들기]({% link docs/current/extensions/extension_distribution.md %}#creating-a-custom-repository)에 대한 추가 노트를 참고하세요.

커뮤니티 확장은 https://community-extensions.duckdb.org에서 서빙되며 다른 키로 서명되므로, 다음과 같은 일방향 SQL 문으로 비활성화할 수 있어요.

SET allow_community_extensions = false;

이러면 핵심 duckdb 확장만 로드하게 돼요. 실패는 INSTALL 시점이 아니라 LOAD 시점이라는 점을 주의하세요.

확장에 대한 일반 정보는 [Extension Distribution 페이지]({% link docs/current/extensions/extension_distribution.md %})를 참고하세요.

Cross-Origin Isolation

coi 번들은 여러 스레드를 실행하는데, 이는 SharedArrayBuffer에 의존해요. 브라우저는 cross-origin isolated 페이지에만 SharedArrayBuffer를 노출해요. 스레드 번들을 서빙하려면 최상위 문서가 다음 HTTP 헤더로 전달되어야 해요.

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

이 헤더들은 문서를 다른 cross-origin 문서로부터 격리하고, 그것이 내장하는 모든 cross-origin 리소스가 명시적으로 옵트인하도록 요구해요. 많은 서드파티 엔드포인트가 이 정책 아래에 내장되기 위해 필요한 헤더를 아직 보내지 않으므로, 대부분의 배포는 격리되지 않은 페이지에서 실행되며 DuckDB-Wasm은 단일 스레드 mvp나 eh 번들로 폴백해요.

이 헤더가 왜 필요한지, 어떻게 SharedArrayBuffer를 잠금 해제하는지에 대한 더 많은 배경은 다음 리소스를 참고하세요.

보안 고려 사항

Warning 자신의 데이터에 접근할 수 있게 DuckDB-Wasm을 배포하는 것은, SQL에 접근할 수 있는 사람은 누구나 DuckDB-Wasm이 접근할 수 있는 데이터에 접근할 수 있다는 뜻이에요. 또한 DuckDB-Wasm은 기본 설정에서 원격 엔드포인트에 접근할 수 있으므로, 샌드박스 안에서도 외부 세계에 보이는 영향을 줄 수 있어요.

더 알아보기 (Learn more)

  • [Instantiate]({% link docs/current/clients/wasm/instantiation.md %}) — 여기서 서빙한 라이브러리, worker, WebAssembly 구성 요소가 런타임에 어떻게 연결되는지.
  • [Load Extensions]({% link docs/current/clients/wasm/extensions.md %}) — 확장이 커스텀 저장소에서 어떻게 fetch·서명·서빙되는지.
  • [Extension Distribution]({% link docs/current/extensions/extension_distribution.md %}) — 확장 저장소와 커스텀 저장소 만들기에 대한 일반 정보.
  • [DuckDB Wasm Client]({% link docs/current/clients/wasm/overview.md %}) — 이 페이지가 기반으로 하는 계층적 API와 예제 배포.
  • [Troubleshoot]({% link docs/current/clients/wasm/troubleshoot.md %}) — 스레딩을 위한 cross-origin isolation과 기타 배포 관련 문제.