Skip to content
DuckDB Extensions All extensions HTTP Server

Server functions in the HTTP Server DuckDB extension

Function category

Server

2 functions

Start and stop the embedded HTTP query listener. The third argument to `httpserve_start` selects the auth mode — empty (no auth), `user:pass` (HTTP Basic), or any other value (shared key in `X-API-Key`).

httpserve_start

Scalar function Server
Signature
httpserve_start( host: VARCHAR, port: INTEGER, auth: VARCHAR ) → VARCHAR
Arguments (Positional)
Argument host Type VARCHAR Mode Positional Description Interface to bind on. Use 'localhost' (or '127.0.0.1') to keep the server reachable only from the same machine. Use '0.0.0.0' to listen on all interfaces — only do this behind a firewall or reverse proxy.
Argument port Type INTEGER Mode Positional Description TCP port to listen on. Any unused port; 9999 is conventional in the upstream examples.
Argument auth Type VARCHAR Mode Positional Description Authentication selector. Empty string disables auth (development only). A value containing ':' is parsed as user:password and enables HTTP Basic auth. Any other value is treated as a single shared key the client must send in the X-API-Key header. There is one credential per server — no per-user accounts.
Returns

Confirmation string of the form 'HTTP server started on <host>:<port>'.

Description

Start the embedded HTTP query server. The listener runs in a background thread inside the DuckDB process and dispatches requests to the calling connection — extensions you've LOADed and databases you've ATTACHed are visible to HTTP clients.

There is one global server per DuckDB process: calling httpserve_start again replaces the running listener. Set DUCKDB_HTTPSERVER_FOREGROUND=1 before starting DuckDB to run the server on the main thread (the SQL caller will block); set DUCKDB_HTTPSERVER_DEBUG=1 for stdout request logging or DUCKDB_HTTPSERVER_SYSLOG=1 to route logs to syslog.

The served endpoints are:

  • / — GET and POST for SQL queries. Pass SQL in the request body, or as ?query= / ?q=. Add ?default_format=JSONEachRow or ?default_format=JSONCompact to choose the response shape (see ClickHouse formats — the names are borrowed from there).
  • /ping — GET health check.
  • The browser UI (quackplay) is served from / when accessed with a browser-style request.
1 HTTP Basic auth on localhost 
SELECT httpserve_start('localhost', 9999, 'user:pass');
-- 'HTTP server started on localhost:9999'

-- From the shell:
--   curl -X POST -d "SELECT version()" http://user:pass@localhost:9999/
2 Single shared key (X-API-Key header) 
SELECT httpserve_start('localhost', 9999, 'supersecretkey');

-- From the shell:
--   curl -X POST --header 'X-API-Key: supersecretkey' \
--        -d 'SELECT 42' http://localhost:9999/?default_format=JSONCompact
3 No auth — only behind a private network 
SELECT httpserve_start('127.0.0.1', 9999, '');
4 Bind on all interfaces — read-only DuckDB, behind a TLS-terminating proxy 
-- Launched as: duckdb -readonly mydata.duckdb
SELECT httpserve_start('0.0.0.0', 9999, 'shared-api-key');
Related functions

httpserve_stop

Scalar function Server
Signature
httpserve_stop() → VARCHAR
Returns

Confirmation string indicating the listener has been stopped.

Description

Stop the running HTTP server thread cleanly. Pair with httpserve_start when you want to rebind on a different port or rotate the auth credential without restarting DuckDB.

If the DuckDB process exits, the server thread is torn down with it — calling httpserve_stop is not strictly required for shutdown, only for in-process restarts.

1 Graceful stop 
SELECT httpserve_stop();
2 Rotate credential without restarting DuckDB 
SELECT httpserve_stop();
SELECT httpserve_start('localhost', 9999, 'rotated-key');
Related functions