Appearance

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 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 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 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 });