---
url: /mosaic/api/duckdb/data-server.md
---
# Data Server

The data server provides network access to a server-side DuckDB instance from Node.js.

::: warning
Due to persistent quality issues involving the DuckDB Node.js client and Arrow extension, we recommend using Mosaic's Python-based [`duckdb-server`](/server/) package instead. However, we retain this JavaScript-based server for both backwards compatibility and potential future use as quality issues improve.
:::

## dataServer

`dataServer(db, options)`

Launch a new data server instance.
The *db* argument should be a [`DuckDB`](./duckdb) instance.

The following *options* are supported:

* *port*: The port number (default `3000`) on which to listen for query requests.
* *rest*: Boolean flag (default `true`) indicating if HTTP REST connections should be enabled.

For HTTPS/HTTP/2, install native mkcert on `PATH`, then run `pnpm mkcert` from the repository root. The server checks for a complete `localhost.pem` / `localhost-key.pem` pair in its working directory, then the shared OS user configuration directory under `mosaic/https`. A selected invalid pair fails startup; without a pair, the server uses plaintext HTTP. HTTPS also supports HTTP/1.1 clients. See the [server guide](https://github.com/uwdata/mosaic/blob/main/packages/server/README.md) for platform paths, mounts, and renewal.

Once launched, the data server will accept HTTP POST requests containing JSON content that consists of a single object with the following properties:

* *type*: The type of query (required). The type `"exec"` indicates that the provided query should be run with no return value. The `"arrow"` type indicates that the result table should be returned as Arrow IPC bytes.
* *sql*: The SQL query string to issue to DuckDB.

A request without a *type* is rejected with HTTP status 400.

### Examples

Launch a data server in Node.js:

```js
import { DuckDB, dataServer } from "@uwdata/mosaic-duckdb";
dataServer(new DuckDB(), { rest: true });
```