문제 해결
문제 해결
이 페이지는 DuckDB Rust 클라이언트를 사용할 때 겪는 흔한 문제들과 그 우회 방법을 모아둔 문서예요. 여기 없는 문제를 만나면 GitHub의 클라이언트 이슈 트래커를 검색해 보세요.
출처: 문서
본문
개요
이 페이지는 흔한 문제와 그 우회 방법을 다룹니다. 여기 다루지 않은 문제에 부딪히면 GitHub의 클라이언트 이슈 트래커에서 검색해 보세요.
시스템 라이브러리 연결
bundled 피처는 크레이트와 함께 제공되는 소스에서 DuckDB를 컴파일하므로 빌드에 다른 것이 필요 없어요. 대부분의 애플리케이션에 가장 간단한 선택이에요. bundled 없이 빌드하면 밑바탕 libduckdb-sys 크레이트가 시스템에 이미 있는 DuckDB 라이브러리에 연결하는데, 이를 pkg-config 또는 (MSVC ABI에서는) Vcpkg로 찾아요. 라이브러리를 찾지 못하면 빌드가 실패합니다. bundled 없이 빌드하는 방법은 세 가지가 있어요.
이미 있는 라이브러리를 가리키기
DUCKDB_LIB_DIR을 라이브러리가 있는 디렉토리로, DUCKDB_INCLUDE_DIR을 duckdb.h가 있다면 그 디렉토리로 설정하세요. 예를 들어 DuckDB 릴리스의 사전 빌드 라이브러리를 사용하는 경우:
wget https://github.com/duckdb/duckdb/releases/download/v1.5.5/libduckdb-osx-universal.zip
unzip libduckdb-osx-universal.zip -d libduckdb
export DUCKDB_LIB_DIR=$PWD/libduckdb
export DUCKDB_INCLUDE_DIR=$DUCKDB_LIB_DIR
export DYLD_FALLBACK_LIBRARY_PATH=$DUCKDB_LIB_DIR # Linux에서는 LD_LIBRARY_PATH
cargo build
Linux에서는 일치하는 libduckdb-linux-amd64.zip 또는 libduckdb-linux-arm64.zip 아카이브를 사용하고 대신 LD_LIBRARY_PATH를 설정하세요.
빌드가 라이브러리를 다운로드하게 하기
DUCKDB_DOWNLOAD_LIB=1을 설정하면 빌드 스크립트가 크레이트의 버전과 일치하는 사전 빌드 DuckDB 라이브러리를 GitHub Releases에서 다운로드해 target/ 아래에 캐시하고 링커 검색 경로에 추가해요. DUCKDB_STATIC은 설정하지 않은 채 두세요. 다운로드된 아카이브에는 동적 라이브러리만 들어 있기 때문이에요.
DUCKDB_DOWNLOAD_LIB=1 cargo build
패키지 매니저 사용
DuckDB가 pkg-config나 Vcpkg로 설치되어 있으면 빌드가 자동으로 찾아요. vcpkg는 기본적으로 정적 라이브러리를 사용하므로, 동적으로 연결하려면 VCPKGRS_DYNAMIC=1을 설정하세요.
ICU 확장이 bundled 빌드에서 제외됨
crates.io가 10 MB 패키지 크기 제한을 두기 때문에, bundled 소스는 ICU 확장을 제외해요. 그 결과 일부 콜레이션과 시간대 인식 날짜/시간 연산이 기본 상태에서 실패합니다. 런타임에 ICU를 설치·로드해 복원하세요.
conn.execute_batch("INSTALL icu; LOAD icu;")?;
또는 크레이트의 icu 피처를 활성화해 ICU를 정적으로 연결할 수 있어요. 그러면 빌드에 포함됩니다.
확장 빌드에서 open_in_memory 패닉
loadable-extension 피처는 클라이언트 애플리케이션이 아니라 DuckDB 확장을 빌드해요. 이 피처를 활성화하면 Connection::open_in_memory() 같은 진입점이 확장 컨텍스트 밖에서 호출되면 패닉합니다. attach할 호스트 DuckDB 인스턴스가 없기 때문이에요.
클라이언트 애플리케이션에서는 loadable-extension을 활성화하지 마세요. 확장을 빌드할 때만 사용하세요. loadable 확장을 빌드·패키징하는 방법은 Write User Defined Functions를 참고해 주세요.
bundled로 크로스 컴파일
bundled 피처로 크로스 컴파일하면 대상의 DuckDB C++ 소스를 컴파일하므로, 그 대상에 대한 작동하는 C++ 크로스 컴파일러가 필요하며 최선 노력 기준으로만 지원돼요. 크로스 컴파일 설정이 어려울 때는 Linking against a System Library에서 설명한 대로 DUCKDB_LIB_DIR로 대상의 사전 빌드 라이브러리에 연결하세요.
더 읽을거리
- Rust 클라이언트 — 설치,
bundled피처, Cargo 피처 플래그 전체 목록 - Connect — 연결 열기 (실패는 종종 빌드나 연결 문제)
- Write User Defined Functions —
loadable-extension피처와 확장을 올바르게 패키징하는 방법
더 알아보기 (Learn more)
- Rust 클라이언트 설치·설정은
clients/rust/overview, 연결은clients/rust/connecting문서를 참고해 주세요.