duckdb-server is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install duckdb-server

It will make the duckdb-server command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall duckdb-server uninstalls.

Adding `duckdb_server` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add duckdb-server

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

duckdb-server = "0.2.0"

The duckdb_server library will be automatically available globally. Read the duckdb_server library documentation.

Back to the crate overview.

Readme

DuckDB Server

A Rust-based server that runs a local DuckDB instance and support queries over Web Sockets or HTTP/HTTPS, returning data in either Apache Arrow or JSON format.

Note: This package provides a local DuckDB server. To instead use DuckDB-WASM in the browser, use the wasmConnector in the mosaic-core package.

Usage

Install the server with Cargo or Cargo B(inary)Install.

cargo install duckdb-server
# or
cargo binstall duckdb-server

Then run the server with

duckdb-server

You can disable or customize logging with the RUST_LOG environment variable.

env RUST_LOG="" duckdb-server

The server can reuse existing sockets with listenfd.

systemfd --no-pid -s http::3000 -- duckdb-server

To use HTTPS and HTTP/2, you need localhost.pem and localhost-key.pem in the current directory or at the env variable CARGO_MANIFEST_DIR.

Create certificates for localhost with mkcert

mkcert localhost

API

The server supports queries via HTTP GET and POST, and WebSockets. The GET endpoint is useful for debugging. For example, you can query it with this url.

Each endpoint takes a JSON object with a command in the type. The server supports the following commands.

`exec`

Executes the SQL query in the sql field.

`arrow`

Executes the SQL query in the sql field and returns the result in Apache Arrow format.

`json`

Executes the SQL query in the sql field and returns the result in JSON format.

`create-bundle`

Caches the results of the SQL queries in the queries field and the required datasets.

`load-bundle`

Loads the bundled results.

Developers

Build

Build the release binary with

cargo build --release

Develop

To run the server and restart it when the code changes, install cargo-watch and systemfd with

cargo install cargo-watch systemfd

Then run the server with

systemfd --no-pid -s https::3000 -- cargo watch -x run

Or just use (but this won't restart when the code changes)

cargo run

Before sending a pull request, run the tests with

cargo test
cargo clippy
cargo fmt

Run the benchmarks with

cargo bench

Update Dependencies

Update the lockfile with cargo update and look for outdated dependencies with cargo-outdated cargo outdated -d 1.

Publishing

Bump the version in Cargo.toml and then run cargo publish.

Installing the command-line executable

Adding duckdb_server library as a dependency

Adding `duckdb_server` library as a dependency