Rust 클라이언트

DuckDB Rust 클라이언트인 duckdb-rs는 DuckDB C API 위에 만들어진 인체공학적 래퍼로, rusqlite를 본뜬 인터페이스를 제공해요. 타입 안전 쿼리, Appender로 대량 로드, Apache Arrow 교환, 사용자 정의 함수, Rust로 DuckDB 확장 빌드를 지원한답니다. 함께 살펴볼까요?

출처: 문서

본문

설치: DuckDB Rust 클라이언트를 사용하려면 [Rust 설치 페이지]({% link install/index.html %}?environment=rust)를 방문하세요.

DuckDB Rust 클라이언트의 최신 안정 버전은 {% if site.current_duckdb_rust_version != "" %}{{ site.current_duckdb_rust_version }}{% else %}{{ site.lts_duckdb_rust_version }}{% endif %}이에요.

DuckDB Rust 클라이언트인 duckdb-rs는 DuckDB C API 위에 만들어진 인체공학적 래퍼로, rusqlite를 본뜬 인터페이스를 노출해요. 타입 안전 쿼리, Appender로 대량 로드, Apache Arrow 교환, 사용자 정의 함수, Rust로 DuckDB 확장 빌드를 지원해요. 이 페이지는 설치에 초점을 맞춰요. 이 섹션의 다른 페이지들은 연결과 각 기능을 자세히 다룬답니다.

설치 (Installation)

DuckDB Rust 클라이언트는 crates.io에 게시돼요. 전체 API는 docs.rs에 문서화되어 있어요. cargo로 프로젝트에 추가하고, bundled 피처를 활성화해서 DuckDB를 소스에서 컴파일하고 시스템 라이브러리가 필요 없게 만들 수 있어요:

cargo add duckdb --features bundled

해당하는 Cargo.toml 항목은 버전을 고정해요. DuckDB v1.5.0부터 크레이트 버전은 1.⟨major_minor_patch⟩.x 형태예요. 틸드(~) 요구사항은 번들된 DuckDB 버전을 바꾸지 않으면서 패치 릴리스를 받아요:

[dependencies]
duckdb = { version = "~1.10505.0", features = ["bundled"] }

bundled 피처가 시작하기에 가장 간단한 방법이에요. 이것 없이는 libduckdb-sys 크레이트가 컴파일하는 대신 시스템 DuckDB 라이브러리에 링크해요. 이 내용은 [Troubleshoot]({% link docs/current/clients/rust/troubleshoot.md %}#linking-against-a-system-library)에서 다뤄요.

crates.io에 릴리스되기 전에 최신 바인딩을 추적하려면 git의 main 브랜치나 특정 커밋에 의존하세요. 번들된 DuckDB 버전은 그 커밋이 벤더링한 버전이에요:

[dependencies]
# 최신 개발 버전
duckdb = { git = "https://github.com/duckdb/duckdb-rs", branch = "main", features = ["bundled"] }

# 특정 커밋
duckdb = { git = "https://github.com/duckdb/duckdb-rs", rev = "abc123def", features = ["bundled"] }

DuckDB 1.4 Andium에 머무는 LTS 릴리스 라인은 v1.4-andium 브랜치를 사용하세요.

팁 Rust 클라이언트는 파일 포맷 리더, Arrow와 Polars 통합, 연결 풀링, 함수와 확장 인터페이스를 켜는 많은 Cargo feature flags를 제공해요. 빌드 시간과 바이너리 크기를 줄이기 위해 프로젝트가 사용하는 피처만 활성화하세요.

기본 API 사용법 (Basic API Usage)

DuckDB를 사용하려면 먼저 인메모리 데이터베이스에 Connection::open_in_memory(), 데이터베이스 파일에 Connection::open(path)으로 Connection을 초기화해요. 쿼리는 execute()와 execute_batch()로 보내고, 결과는 문을 준비한 뒤 query_map()으로 각 행을 Rust 값에 매핑해서 읽어요:

use duckdb::{params, Connection, Result};

#[derive(Debug)]
struct Person {
    id: i32,
    name: String,
    data: Option<Vec<u8>>,
}

fn main() -> Result<()> {
    let conn = Connection::open_in_memory()?;

    conn.execute_batch(
        r"CREATE SEQUENCE seq;
          CREATE TABLE person (
              id   INTEGER PRIMARY KEY DEFAULT NEXTVAL('seq'),
              name TEXT NOT NULL,
              data BLOB
          );",
    )?;

    let me = Person {
        id: 0,
        name: "Steven".to_string(),
        data: None,
    };
    conn.execute(
        "INSERT INTO person (name, data) VALUES (?, ?)",
        params![me.name, me.data],
    )?;

    let mut stmt = conn.prepare("SELECT id, name, data FROM person")?;
    let person_iter = stmt.query_map([], |row| {
        Ok(Person {
            id: row.get(0)?,
            name: row.get(1)?,
            data: row.get(2)?,
        })
    })?;

    for person in person_iter {
        println!("Found person {:?}", person.unwrap());
    }
    Ok(())
}

이 예시는 크레이트의 basic 예시를 각색한 거예요. [Run Queries]({% link docs/current/clients/rust/querying.md %})에서 쿼리 보내기와 결과 읽기를 자세히 다뤄요.

Feature Flags

이 크레이트는 모듈식이라 대부분의 통합이 기본적으로 꺼져 있는 Cargo 피처 뒤에 게이트되어 있어요. 의존성 선언에서 예를 들어 features = ["bundled", "vtab", "appender-arrow"]처럼 활성화하세요. 다음은 크레이트의 Cargo 피처 전체 집합을 용도별로 묶은 거예요.

DuckDB 빌드 (Building DuckDB)

Feature	활성화하는 것
`bundled`	번들된 소스에서 `cc` 크레이트로 DuckDB를 컴파일해서 시스템 라이브러리가 필요 없게 해요.
`bundled-cmake`	실험적. 번들된 소스를 `cc` 대신 DuckDB의 업스트림 CMake 빌드로 컴파일하며, 아래 번들 확장에 필요해요. crates.io가 아닌 git 체크아웃에서만 가능해요. `bundled`와 `parquet`를 내포해요.
`buildtime_bindgen`	빌드 시점에 `bindgen`으로 C API 바인딩을 재생성해서, 제공되는 사전 생성 바인딩 대신 사용해요.

파일 포맷 (File Formats)

둘 다 bundled를 내포해요.

Feature	활성화하는 것
`json`	[JSON]({% link docs/current/data/json/overview.md %}) 읽기/쓰기, 정적 링크.
`parquet`	[Parquet]({% link docs/current/data/parquet/overview.md %}) 읽기/쓰기, 정적 링크.

번들 확장 (Bundled Extensions)

각각 일치하는 번들 확장을 정적으로 링크해요. 모두 bundled-cmake를 내포하므로 git 체크아웃이 필요해요.

Feature	활성화하는 것
`autocomplete`	autocomplete 확장.
`icu`	로케일 인식 및 시간대 인식 연산을 위한 [ICU 확장]({% link docs/current/core_extensions/icu.md %}), 일반 `bundled` 빌드는 이를 생략해요.
`tpch`	TPC-H 벤치마크 확장.
`tpcds`	TPC-DS 벤치마크 확장.

테이블 및 스칼라 함수 (Table and Scalar Functions)

Feature	활성화하는 것
`vtab`	[테이블 함수]({% link docs/current/clients/rust/functions.md %}#table-functions)를 위한 기본 지원.
`vtab-arrow`	테이블 함수를 위한 Apache Arrow 통합, Arrow `RecordBatch`와 DuckDB 데이터 청크 사이를 변환해요. `vtab`를 내포해요.
`vscalar`	[스칼라 함수]({% link docs/current/clients/rust/functions.md %}#scalar-functions). `vtab-arrow`를 내포해요.
`vscalar-arrow`	Arrow 최적화 스칼라 함수, `vscalar`와 함께 사용하도록 설계되었어요.
`appender-arrow`	[Appender]({% link docs/current/clients/rust/data_import.md %}#appender)를 통해 Arrow `RecordBatch`를 추가해요. `vtab-arrow`를 내포해요.
`loadable-extension`	실험적. 클라이언트 애플리케이션 대신 로드 가능한 DuckDB 확장을 빌드해요. [Building a Loadable Extension]({% link docs/current/clients/rust/functions.md %}#building-a-loadable-extension)을 참고하세요.

에코시스템 통합 (Ecosystem Integrations)

Feature	활성화하는 것
`polars`	쿼리 결과를 Polars 데이터 프레임으로 교환해요. [Handle Results]({% link docs/current/clients/rust/result_handling.md %}#polars-data-frames) 참고.
`r2d2`	`r2d2` 크레이트를 통한 연결 풀. [Connect]({% link docs/current/clients/rust/connecting.md %}#connection-pooling) 참고.
`chrono`	`chrono` 날짜/시간 타입을 위한 `ToSql`과 `FromSql` 변환.
`rust_decimal`	`rust_decimal::Decimal`을 위한 `ToSql`과 `FromSql` 변환.
`serde_json`	`serde_json::Value`를 위한 `ToSql`과 `FromSql` 변환.
`url`	`url::Url`을 위한 `ToSql`과 `FromSql` 변환.
`uuid`	`uuid::Uuid`를 위한 `ToSql`과 `FromSql` 변환.

포괄(Umbrella) 피처

Feature	활성화하는 것
`vtab-full`	`vtab-arrow`와 `appender-arrow`, 그리고 더 이상 사용되지 않는 `vtab-excel`.
`extensions-full`	`json`, `parquet`, `vtab-full`.
`modern-full`	`chrono`, `serde_json`, `url`, `r2d2`, `uuid`, `polars`, `rust_decimal`.

더 이상 사용되지 않는 피처 (Deprecated Features)

Feature	활성화하는 것
`vtab-excel`	피처 호환성을 위해 유지된 no-op.
`vtab-loadable`	`loadable-extension`으로 대체됨.

더 읽을거리 (Further Reading)

[Connect]({% link docs/current/clients/rust/connecting.md %}) — 인메모리 및 파일 기반 데이터베이스 열기, Config 옵션, 연결 풀링, 스레드 안전성.
[Run Queries]({% link docs/current/clients/rust/querying.md %}) — execute(), 준비된 문, 파라미터 바인딩, 행을 Rust 타입으로 매핑.
[Import Data]({% link docs/current/clients/rust/data_import.md %}) — Appender로 대량 로드하고 Parquet, CSV, JSON 파일에서 직접 읽기.
[Handle Results]({% link docs/current/clients/rust/result_handling.md %}) — Apache Arrow와 Polars 결과 교환.
[Write User Defined Functions]({% link docs/current/clients/rust/functions.md %}) — 사용자 정의 스칼라 및 테이블 함수, 로드 가능한 확장.
[Profile and Monitor]({% link docs/current/clients/rust/profiling.md %}) — 쿼리 프로파일링과 장시간 쿼리 중단.
[Troubleshoot]({% link docs/current/clients/rust/troubleshoot.md %}) — 링킹, ICU 확장, 확장-대-클라이언트 빌드 이슈.
[Clients Overview]({% link docs/current/clients/overview.md %}) — DuckDB가 Rust와 함께 제공하는 다른 클라이언트 API.

Rust 클라이언트