This page lists every function, setting, and log type exposed by the quack extension. For a tour of the protocol, start with the Overview.
Function Reference
Server Management
| Function | Description |
|---|---|
quack_serve(uri, token := 'token_value', allow_other_hostname := false, disable_ssl := false) |
Start a server on uri. Localhost-only by default. Pass token to set the server's authentication token explicitly (minimum 4 characters), otherwise one is generated. Returns listen URI, URL, and the auth token. |
quack_stop(uri) |
Stop the server listening on uri. |
quack_identify(name, provider, hostname, region, meta) |
Set this node's whoami identity fields. Any subset can be supplied. |
whoami() |
Table macro returning identity + runtime info for the current node. |
Client Queries
| Function | Description |
|---|---|
quack_query(uri, query, token := 'token_value', disable_ssl := false) |
Run query on remote uri, stream result back. Pass token to override any matching quack secret on the client side. |
quack_query_by_name(catalog, query) |
Run query against an already-attached Quack catalog (used by catalog.query()). |
Utility
| Function | Description |
|---|---|
quack_uri_parser(uri, ssl) |
Parse a Quack URI into a STRUCT(host, port, ipv6, ssl, url) entry |
quack_check_token(sid, client_token, server_token) |
Default authentication callback, compares the client-supplied token against the server's stored token. |
quack_nop_authorization(sid, query) |
Default authorization callback, always allows. |
ATTACH Options
| Option | Type | Default | Description |
|---|---|---|---|
TOKEN |
VARCHAR |
(unset) | Authentication token. Overrides any matching quack secret on the client side. |
DISABLE_SSL |
BOOLEAN |
true for local, else false |
Force the client transport. Local URIs default to plain HTTP. |
TYPE |
VARCHAR |
inferred | Pin the secret type used for token resolution (e.g., quack). |
Settings
All settings are regular DuckDB session / global options. Set with SET name = value or SET GLOBAL.
Authentication / Authorization
The auth callbacks are evaluated on a fresh server-side connection every time, so the two settings below are global-scoped (SET GLOBAL). A plain SET on these is forwarded to the global slot automatically. Use RESET GLOBAL to restore the default, a plain RESET only clears the session view and the auth path will keep reading the stale global value.
| Setting | Type | Default | Description |
|---|---|---|---|
quack_authentication_function |
VARCHAR |
quack_check_token |
Name of a 3-arg scalar function (sid, client_token, server_token) -> BOOLEAN used by the server to authenticate clients. |
quack_authorization_function |
VARCHAR |
quack_nop_authorization |
Name of a 2-arg scalar function (sid, query) -> BOOLEAN used by the server to authorize each query. |
You can plug in your own auth by creating any scalar function with the expected signature and pointing the setting at it. See Security for examples.
FETCH Batching (Server-Side)
The server batches multiple DataChunks into each FETCH response to reduce per-chunk overhead.
| Setting | Type | Default | Description |
|---|---|---|---|
quack_fetch_batch_chunks |
UBIGINT |
12 |
Maximum number of DataChunks shipped per FETCH response. |
Node Identity
These settings back the whoami() macro. quack_identify(...) is sugar that updates them.
| Setting | Type | Default | Description |
|---|---|---|---|
whoami_name |
VARCHAR |
(empty) | Human-readable node name. |
whoami_provider |
VARCHAR |
(empty) | Deployment provider (ec2, docker, local, …). |
whoami_hostname |
VARCHAR |
(empty) | Network hostname / public address. |
whoami_region |
VARCHAR |
(empty) | Deployment region. |
whoami_started_at |
VARCHAR |
(empty) | Node start time (ISO 8601 timestamp). Anchors uptime. |
whoami_meta |
VARCHAR |
{} |
Provider-specific metadata as JSON. |
quack_loaded_at_us |
BIGINT |
Epoch microseconds at extension load | Fallback uptime anchor when whoami_started_at is empty. |
Logging
Two log types are registered by the extension. Enable them to debug connectivity or measure request timing.
Quack Log
Structured log of every Quack message (both client- and server-side):
CALL enable_logging('Quack');
FROM quack_query('quack:localhost', 'SELECT 42');
SELECT * FROM duckdb_logs_parsed('Quack');
| context_id | scope | connection_id | transaction_id | query_id | thread_id | timestamp | type | log_level | message_type | quack_connection_id | client_query_id | query | server | duration_ms | response_type | error |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 60 | CONNECTION | 2 | 18 | 18 | NULL | 2026-05-10 09:06:19.841623+02 | Quack | DEBUG | CONNECTION_REQUEST | 18 | NULL | http://localhost:9494 | 41 | CONNECTION_RESPONSE | NULL | |
| 60 | CONNECTION | 2 | 18 | 18 | NULL | 2026-05-10 09:06:19.842407+02 | Quack | DEBUG | PREPARE_REQUEST | 091A003553E7E67B615B73D6BE81FD2E | 18 | SELECT 42 | http://localhost:9494 | 0 | PREPARE_RESPONSE | NULL |
Fields on each entry:
| Field | Description |
|---|---|
message_type |
Request type: PREPARE_REQUEST, FETCH_REQUEST, etc. |
quack_connection_id |
Server-issued connection id (stable across requests in one ATTACH). |
client_query_id |
Monotonic id assigned by the client, correlates client / server logs. |
query |
SQL payload for PREPARE_REQUESTs. |
server |
HTTP URL on client-side logs, NULL on server-side logs. |
duration_ms |
Round-trip time (client) or handling time (server). |
response_type |
Response type or ERROR. |
error |
Error message if the request failed. |
To correlate a client request with its server-side handling, join on (quack_connection_id, client_query_id).
HTTP Log
The underlying HTTP transport can be logged separately:
CALL enable_logging('HTTP');
FROM quack_query('quack:localhost', 'SELECT 1');
SELECT request.type, request.url, response.status
FROM duckdb_logs_parsed('HTTP');
| type | url | status |
|---|---|---|
| POST | http://localhost:9494/quack | OK_200 |
| POST | http://localhost:9494/quack | OK_200 |
Requests are POSTs to a /quack endpoint.
Persisting Logs for Querying
duckdb_logs_parsed reads from DuckDB's in-memory log buffer. For non-trivial sessions you'll want to persist logs:
CALL enable_logging(
'Quack',
storage => 'file',
storage_config => {'path': '/tmp/duckdb-rpc-logs'}
);
To clear the log between runs, use:
CALL truncate_duckdb_logs();
To turn logging off, run:
CALL disable_logging();