Mosaic DuckDB Server
A Python-based server that runs a local DuckDB instance and support queries over Web Sockets or HTTP, 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.
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.
To set up a local certificate for SSL, use https://github.com/FiloSottile/mkcert.
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.
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.
2 maintainers
Release files for duckdb-server 0.31.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.31.0.tar.gz | 13.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| duckdb_server-0.31.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 13.7 MB
Release files / duckdb_server-0.31.0.tar.gz
| Download URL | duckdb_server-0.31.0.tar.gz |
|---|---|
| Size | 13.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
69b7b4eea190b301ab15273beeb14caf9a9c87e1311f0baa29a8f5af334a6cbf
|
|
BLAKE2b-256 checksum How to use checksums |
418fbd7882fbfdbf8ade0122484139c4be9a1627a95348d74dd2d68bb81b62d3
|
| 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 Aug 25, 2026.
Transparency logRelease files / duckdb_server-0.31.0-py3-none-any.whl
| Download URL | duckdb_server-0.31.0-py3-none-any.whl |
|---|---|
| Size | 6.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
71d16666aada6715cb77a195237deff5fe683ed1ed9b44659c93efda88decc41
|
|
BLAKE2b-256 checksum How to use checksums |
247be2032b9e1a140415871693299f025ad61671c2ce1afba45960aafc89c22c
|
| 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 Aug 25, 2026.
Transparency log
