The Quack server speaks plain HTTP only and binds to localhost by default. See Security for the rationale behind these configurations. For any deployment beyond local-only, the recommended pattern is the same as for any other HTTP-based database / application server: put a proven HTTP reverse proxy in front of it, and let the proxy terminate TLS.

The Quack client cooperates with this: for non-local URIs it assumes HTTPS by default, so a properly fronted server “just works” from the client side too.

This guide walks through three setups, in order of likely usefulness:

1. A local TLS test setup with Caddy, so you can exercise the full HTTPS path on your machine.
2. nginx + Let's Encrypt in production.
3. Caddy + Let's Encrypt in production.

The two production setups are interchangeable. Pick whichever fits your operational stack.

Local Test Setup with Caddy

You can exercise the full HTTPS path on your own machine using Caddy. Caddy issues itself a certificate for localhost from a local CA and installs the CA root into your system trust store, so DuckDB's HTTPS client trusts the cert without any extra config.

1. Run Caddy

Save this Caddyfile:

localhost:8443 {
    reverse_proxy 127.0.0.1:9494 {
        flush_interval -1
    }

    request_body {
        max_size 256MB
    }
}

Then start Caddy:

brew install caddy # macOS, for other platforms see https://caddyserver.com/docs/install
caddy run --config Caddyfile

The first run will prompt for elevation to install Caddy's local CA into your system trust store. After that, certs issued by Caddy for localhost are trusted system-wide.

2. Start Quack and Connect Through the Proxy

In one DuckDB session, start the server (this prints an authentication token):

CALL quack_serve('quack:localhost');

In the client session, connect through Caddy on :8443. Local URIs default to plain HTTP, so you have to force SSL on explicitly:

ATTACH 'quack:localhost:8443' AS quack (
    TOKEN 'authentication_token-from-quack_serve',
    DISABLE_SSL false
);

FROM quack.query('SELECT 42');

If the round-trip succeeds, your traffic just went out as TLS to Caddy, got terminated, and was forwarded as plain HTTP to Quack on :9494.

Nginx + Let's Encrypt

We expect this to be the most common choice. A minimal site for a Quack server listening on the loopback interface looks as follows:

# /etc/nginx/sites-enabled/quack.example.com
server {
    listen 443 ssl http2;
    server_name quack.example.com;

    ssl_certificate     /etc/letsencrypt/live/quack.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/quack.example.com/privkey.pem;

    # Quack RPC bodies can be large: PREPARE carries SQL, APPEND carries
    # inserted DataChunks. The 1 MiB nginx default will fail mid-INSERT.
    client_max_body_size 256M;

    # Long-running queries can sit on the wire between FETCHes for
    # minutes. Raise the timeouts above nginx's default 60s.
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;

    location / {
        proxy_pass http://127.0.0.1:9494;

        # Keep-alive against upstream. Quack relies on persistent
        # connections to keep server-side `quack_connection_id` state alive.
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        # Quack streams results via repeated FETCH responses; buffering
        # through nginx defeats the streaming and inflates memory.
        proxy_buffering off;
    }
}

On the Quack side, start the server bound to localhost (the default):

CALL quack_serve('quack:localhost');

Issue the certificate with certbot --nginx -d quack.example.com. Clients connect over HTTPS automatically:

ATTACH 'quack:quack.example.com' AS quack;   -- HTTPS auto-selected

Caddy + Let's Encrypt

Caddy auto-provisions certificates from Let's Encrypt and needs almost no configuration. A complete public-facing Quack proxy:

# /etc/caddy/Caddyfile
quack.example.com {
    reverse_proxy 127.0.0.1:9494 {
        # Equivalent of nginx `proxy_buffering off`. Required so Quack's
        # streamed FETCH responses pass through immediately instead of
        # being buffered in Caddy.
        flush_interval -1
    }

    # Equivalent of nginx `client_max_body_size`. PREPARE / APPEND bodies
    # can be much larger than the default request body cap.
    request_body {
        max_size 256MB
    }
}

Caddy handles certificate issuance and renewal automatically. No certbot step is required.

On the Quack side, start the server bound to localhost (the default):

CALL quack_serve('quack:localhost');

Clients connect over HTTPS automatically:

ATTACH 'quack:quack.example.com' AS quack;   -- HTTPS auto-selected