HTTP Server

What you can do with one query

Turn a DuckDB process into an HTTP query API in one statement:

INSTALL httpserver FROM community;
LOAD httpserver;

SELECT httpserve_start('localhost', 9999, 'user:pass');
-- 'HTTP server started on localhost:9999'

Now any HTTP client can POST SQL and read JSON back:

curl -X POST -d "SELECT version()" \
  "http://user:pass@localhost:9999/?default_format=JSONCompact"

httpserve_start spawns an in-process listener thread; httpserve_stop tears it down. There are no other functions — the entire extension is two SQL calls and a small set of HTTP endpoints.

Architecture

httpserve_start starts an HTTP listener thread inside the DuckDB process. Requests are dispatched to the same DuckDB connection that called the function — so any extension you’ve LOADed, any database you’ve ATTACHed, and any secret you’ve CREATEd is visible to HTTP clients. There is one global server per DuckDB process.

The endpoint surface is intentionally small:

Endpoint	Methods	Purpose
/	GET, POST	Execute a SQL query, or serve the embedded quackplay UI to a browser.
/ping	GET	Liveness check.

There is no /metrics, no /health JSON, and no OpenAPI document — anything beyond send SQL, read JSON lives outside this extension.

The response format vocabulary mirrors the ClickHouse HTTP interface:

• ?default_format=JSONEachRow — newline-delimited rows (JSONEachRow).
• ?default_format=JSONCompact — single document with meta, data, rows, and statistics keys (JSONCompact).

Three environment variables tune the runtime: DUCKDB_HTTPSERVER_FOREGROUND=1 runs the server on the main thread (so the SQL caller blocks), DUCKDB_HTTPSERVER_DEBUG=1 enables stdout request logging, and DUCKDB_HTTPSERVER_SYSLOG=1 routes logs to syslog.

Authentication

The third argument to httpserve_start selects the auth mode:

auth argument	Mode
'' (empty)	No auth. Bind to localhost only and run on a trusted network.
'user:pass' (one colon)	HTTP Basic auth.
any other value	Shared key sent by clients in the X-API-Key header.

Both auth modes are single-credential — there is one user/pass or one key per server. Multi-tenant or per-user access control belongs at a reverse proxy. The credential is checked in constant time but travels in plaintext over HTTP, so TLS in front is non-negotiable for anything beyond a loopback bind.

To rotate a credential without restarting DuckDB, call httpserve_stop and then httpserve_start again with the new value.

Scoping the served database

The HTTP endpoint inherits the DuckDB connection’s surface in full. The most reliable way to make that surface safe is at the DuckDB level, not the HTTP level:

# Read-only — INSERT / UPDATE / COPY TO / ATTACH all fail at SQL parse time.
duckdb -readonly mydata.duckdb -c "
  INSTALL httpserver FROM community;
  LOAD httpserver;
  SELECT httpserve_start('0.0.0.0', 9999, 'shared-api-key');
  CALL pg_sleep(86400);
"

See the DuckDB CLI docs and the securing DuckDB page for the full lockdown vocabulary — read-only mode, restricting extension installation, and disabling filesystem functions.

Calling the server from another DuckDB

Any DuckDB can hit the endpoint as an HTTP source. Configure an extra_http_headers secret for the API key, then use read_json_auto, or pair with the chsql community extension’s duck_flock macro to fan a single SQL statement out across multiple DuckDB endpoints:

CREATE SECRET extra_http_headers (
  TYPE HTTP,
  EXTRA_HTTP_HEADERS MAP { 'X-API-Key': 'supersecretkey' }
);

-- Fan-out across three DuckDB nodes; results are unioned.
SELECT * FROM duck_flock(
  'SELECT version()',
  ['http://node-a:9999', 'http://node-b:9999', 'http://node-c:9999']
);

This is the closest pattern to “distributed DuckDB” that exists today — small, no consensus layer, no shared catalog, but adequate for read-side federation across curated slices.

Compared to alternatives

• The DuckDB CLI over SSH — works for one operator and trivial to set up, but doesn’t help when several services need to query the same DuckDB. The HTTP server replaces “SSH and run a query” with “POST a query.”
• Hand-rolled FastAPI / Express service — more flexible (per-user auth, request validation, custom response shapes) but adds another runtime to deploy. This extension is the right fit when the SQL is the API.
• Airport over Arrow Flight — the right tool when both ends are inside a data system and you want columnar Arrow on the wire. Use httpserver when the client is a generic HTTP consumer (a browser, a Lambda, a curl in a cron job).
• ADBC Scanner or Airport outbound — for querying something else from DuckDB. httpserver is the inverse direction: making this DuckDB queryable.

Cookbook

Recipes — start the server, query it from curl, query it from another DuckDB, run quackplay — live in the Cookbook section below.