DuckDB-Wasm 문제 해결

DuckDB-Wasm 문제 해결 (Troubleshoot)

DuckDB-Wasm을 쓰다 보면 원격 파일 조회나 익스텐션 로드, 메모리, 스레딩 같은 데서 문제가 생기기 쉬워요. 이 페이지에 흔한 문제와 해결 방법을 모아 두었어요. 여기 없는 문제를 만나면 GitHub의 duckdb-wasm 이슈 트래커를 검색해 보세요.

출처: 문서

본문

원격 파일 조회 시 네트워크 오류 (Network Error When Querying Remote Files)

DuckDB-Wasm이 원격 파일을 읽을 때(Wasm용 httpfs 익스텐션 또는 registerFileURL 경유), 요청은 브라우저가 보내기 때문에 브라우저의 CORS 정책을 따르고, 모든 요청이 HTTPS로 승격돼요.

데이터를 호스팅하는 서버는 DuckDB-Wasm 인스턴스를 호스팅하는 오리진이 그 데이터를 읽을 수 있도록 CORS 헤더로 허용해야 해요. 서버가 필요한 헤더를 보내지 않으면 쿼리가 다음과 같은 네트워크 오류로 실패해요:

Failed to execute 'send' on 'XMLHttpRequest'

예를 들어 Amazon S3의 파일을 조회할 때는 버킷의 CORS 정책이 GET과 HEAD 요청을 허용하도록 설정해요:

[
    {
        "AllowedHeaders": ["*"],
        "AllowedMethods": ["GET", "HEAD"],
        "AllowedOrigins": ["*"],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3000
    }
]

이 배열은 서버 쪽 버킷 설정(Amazon S3의 경우 버킷의 CORS 정책)이지, DuckDB-Wasm에 전달하는 값이 아니에요. CORS를 적용하는 건 DuckDB-Wasm이 아니라 브라우저이므로, 이에 해당하는 db/연결 옵션이나 DuckDBGlobalFileInfo 필드는 없어요. 데이터가 호스팅되는 곳에 적용한 뒤 평소처럼 파일을 읽으면 돼요.

CORS 외에도 원격 파일 읽기에는 몇 가지 알려진 제한이 있어요:

모든 요청이 HTTPS로 승격되기 때문에 http:// URL이 잘못 다시 쓰여질 수 있고(예: https://http//…), 이러면 로컬이나 non-TLS 엔드포인트에 대한 읽기가 깨져요 (duckdb-wasm 이슈 #2118 참조).
DuckDB는 HTTP range 요청으로 파일의 일부만 읽어요. Firefox에서는 range 요청이 실패할 수 있고(이슈 #1932), 일부 S3 pre-signed URL에서는 제대로 감지되지 않아(이슈 #2228) 파일 전체를 다운로드해야 하거나 읽기가 실패해요.
HTTP를 통한 DuckDB 네이티브 형식 파일의 캐시 읽기는 손상될 수 있어요 (이슈 #1957).
HTTP 인증 헤더는 지원되지 않아서, 인증이 필요한 엔드포인트는 직접 읽을 수 없어요 (이슈 #1967).

커스텀 저장소에서 익스텐션 로드 실패

DuckDB-Wasm은 익스텐션이 로드될 때마다 네트워크로 익스텐션을 가져와요. 커스텀 저장소에서 SET custom_extension_repository = '⟨https://some.url.com⟩'로 익스텐션을 서빙한다면, 익스텐션 파일에 대한 GET 요청이 브라우저가 연결을 허용하도록 앞서 설명한 원격 데이터 파일과 마찬가지로 CORS가 활성화되어야 해요.

익스텐션은 어디에서 서빙되든 서명이 유지되므로, 익스텐션을 다른 위치로 복사해도 서명은 유효해요.

메모리 부족 (Out of Memory)

WebAssembly 클라이언트는 사용 가능한 메모리가 제한적이에요: WebAssembly는 사용 가능한 메모리를 4GB로 제한하고, 브라우저는 더 엄격한 제한을 두기도 해요. 따라서 큰 데이터셋에 대한 쿼리는 네이티브 DuckDB라면 괜찮을 곳에서 메모리 부족이 날 수 있어요. 제한 안에 머물려면:

큰 결과는 query()로 한 번에 전부 materialize 하는 대신 send()로 스트리밍해요.
필요한 열과 행만 읽어요. DuckDB는 Parquet 파일을 느리게(lazily) 읽기 때문에, projection·filter·LIMIT 절을 쓰면 전체 row group이 메모리에 로드되지 않고 건너뛸 수 있어요.

WebAssembly 클라이언트의 다른 제약은 Limitations를 참고해요.

스레딩 사용 불가 (Threading Is Not Available)

기본적으로 WebAssembly 클라이언트는 단일 스레드를 사용해요. 멀티스레딩은 coi 번들로 가능하지만 아직 실험적이에요.

스레드 번들은 SharedArrayBuffer에 의존하는데, 브라우저는 cross-origin isolated인 페이지만 이걸 노출해요. 최상위 문서가 Cross-Origin-Embedder-Policy와 Cross-Origin-Opener-Policy 헤더로 서빙되지 않으면 DuckDB-Wasm은 단일 스레드 mvp 또는 eh 번들로 폴백해요.

필요한 헤더는 Cross-Origin Isolation, coi 번들의 선택과 설정 방법은 Threading을 참고해요.

더 읽어보기 (Further Reading)

DuckDB Wasm 클라이언트 — 설치, 기본 사용법, 그리고 위 여러 문제의 배경이 되는 제한 사항.
데이터 가져오기 (Import Data) — 위 CORS 규칙의 적용을 받는 원격 파일 등록과 읽기.
익스텐션 로드 (Load Extensions) — httpfs CORS 동작을 포함해 익스텐션을 가져오고, 서명하고, 서빙하는 방법.
배포 (Deploy) — 컴포넌트 서빙과 스레딩을 위한 cross-origin isolation 설정.

DuckDB-Wasm 문제 해결