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 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"}
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.
-
Following (#1286) it is expected that the parameters may be simplified to
?type=arrow&sql=select 1↩
2 maintainers
Metadata
2 maintainers
Release files for duckdb-server 0.33.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| duckdb_server-0.33.0.tar.gz | 13.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| duckdb_server-0.33.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 13.7 MB
Release files / duckdb_server-0.33.0.tar.gz
| Download URL | duckdb_server-0.33.0.tar.gz |
|---|---|
| Size | 13.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
18bb576096c21fd051daa5f7dcaa15d0ffc9ab36c0d31c9e7a69f1464d19dab2
|
|
BLAKE2b-256 checksum How to use checksums |
6b0b1a86998c5d642bd61e66acdbef26cd1de873117674bd25fa80f77494b5eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / duckdb_server-0.33.0-py3-none-any.whl
| Download URL | duckdb_server-0.33.0-py3-none-any.whl |
|---|---|
| Size | 14.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
92c57720d33538d61142bf8f43a2c9ef4f6ba140c7cca9475872c32f175af3bc
|
|
BLAKE2b-256 checksum How to use checksums |
541c403b2660c73fc575cc4954e74c78446628851d2849a3961e3ef47dc6cf35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency log
