Metadata-Version: 2.5
Name: duckdb-server
Version: 0.33.0
Summary: A DuckDB server for Mosaic
Project-URL: homepage, https://github.com/uwdata/mosaic
Requires-Python: >=3.10
Requires-Dist: duckdb>=1.5.2
Requires-Dist: msgspec
Requires-Dist: platformdirs>=4.11.14
Requires-Dist: pyarrow
Requires-Dist: starlette>=1.7.0
Requires-Dist: uvicorn>=0.54.0
Requires-Dist: zttp>=0.0.34
Description-Content-Type: text/markdown

# Mosaic DuckDB Server

[![PyPi](https://img.shields.io/pypi/v/duckdb-server.svg)](https://pypi.org/project/duckdb-server/)

A Python-based server that runs a local DuckDB instance and supports queries over HTTP, returning data in [Apache Arrow](https://arrow.apache.org/) format.

_Note:_ This package provides a local DuckDB server. To instead use DuckDB-WASM in the browser, use the `wasmConnector` in the [`mosaic-core`](https://github.com/uwdata/mosaic/tree/main/packages/mosaic/mosaic-core) package.

## Installation and usage

We recommend running the server in an isolated environment with [uvx](https://docs.astral.sh/uv/). For example, to directly run the server, use:

```bash
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](https://docs.astral.sh/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 `pnpm dev`. 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"}>):

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

Each endpoint accepts a `query` parameter, which is a JSON object with two required fields [^1]:

### `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](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#create-an-account).

[^1]: Following (#1286) it is expected that the parameters may be simplified to `?type=arrow&sql=select 1`
