Mosaic DuckDB Server

A Python-based server that runs a local DuckDB instance and supports queries over HTTP, returning data in Apache Arrow 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.

Installation and usage

We recommend running the server in an isolated environment with uvx. For example, to directly run the server, use:

uvx duckdb-server

Alternatively, you can install the server with pip install duckdb-server. Then you can start the server with duckdb-server.

Developer Setup

We use uv to manage our development setup.

Start the server with uv run duckdb-server. The server will not restart when the code changes.

Start the server in development with uv run duckdb-server --reload. The server restarts when you change the code.

Run uv run ruff check --fix and uv run ruff format to lint the code.

To run the tests, use uv run pytest.

API

The server supports queries via HTTP GET and POST. The GET endpoint is useful for debugging.

For example, you can query it with this url:

https://localhost:3000/?query={"type":"arrow","sql":"select 1"}

Each endpoint accepts a query parameter, which is a JSON object with two required fields ¹:

type

A command type, discriminates between:

• arrow: Execute a single statement and return the result in Apache Arrow format.
• exec: Execute a one or more ";"-separated statements for their side effects.

sql

SQL query to execute.

Publishing

Run the build with uv build. Then publish with uvx twine upload --skip-existing ../../dist/*. We publish using tokens so when asked, set the username to __token__ and then use your token as the password. Alternatively, create a .pypirc file.