Referenz

Diese Seite listet jede Funktion, Einstellung und jeden Log-Typ der quack-Erweiterung. Einen Überblick über das Protokoll finden Sie im Überblick.

Funktionsreferenz

Serververwaltung

Funktion	Beschreibung
quack_serve(uri, token := 'token_value', allow_other_hostname := false, disable_ssl := false)	Startet einen Server auf uri. Standardmäßig nur auf Localhost. Übergeben Sie token, um das Authentifizierungstoken des Servers explizit zu setzen (mindestens 4 Zeichen), andernfalls wird eines erzeugt. Liefert Listen-URI, URL und das Auth-Token.
quack_stop(uri)	Stoppt den Server, der auf uri lauscht.
quack_identify(name, provider, hostname, region, meta)	Setzt die whoami-Identitätsfelder dieses Knotens. Es kann eine beliebige Teilmenge übergeben werden.
whoami()	Tabellenmakro, das Identitäts- und Laufzeitinformationen für den aktuellen Knoten zurückgibt.

Client-Abfragen

Funktion	Beschreibung
quack_query(uri, query, token := 'token_value', disable_ssl := false)	Führt query auf der Remote-uri aus und streamt das Ergebnis zurück. Übergeben Sie token, um ein passendes Quack-Secret auf der Clientseite zu überschreiben.
quack_query_by_name(catalog, query)	Führt query gegen einen bereits angehängten Quack-Katalog aus (verwendet von ⟨catalog⟩.query(){:.language-sql .highlight}).

Hilfsfunktionen

Funktion	Beschreibung
quack_uri_parser(uri, ssl)	Parst eine Quack-URI in einen Eintrag STRUCT(host, port, ipv6, ssl, url)
quack_check_token(sid, client_token, server_token)	Standard-Authentifizierungs-Callback, vergleicht das vom Client gelieferte Token mit dem gespeicherten Token des Servers.
quack_nop_authorization(sid, query)	Standard-Autorisierungs-Callback, erlaubt immer.

ATTACH-Optionen

Option	Typ	Standard	Beschreibung
TOKEN	VARCHAR	(nicht gesetzt)	Authentifizierungstoken. Überschreibt ein passendes Quack-Secret auf der Clientseite.
DISABLE_SSL	BOOLEAN	true für lokal, sonst false	Erzwingt den Client-Transport. Lokale URIs nutzen standardmäßig einfaches HTTP.
TYPE	VARCHAR	abgeleitet	Legt den Secret-Typ fest, der zur Token-Auflösung verwendet wird (z. B. quack).

Einstellungen

Alle Einstellungen sind reguläre DuckDB-Sitzungs- / globale Optionen. Setzen Sie sie mit SET ⟨name⟩ = ⟨value⟩{:.language-sql .highlight} oder SET GLOBAL{:.language-sql .highlight}.

Authentifizierung / Autorisierung

Die Auth-Callbacks werden jedes Mal auf einer frischen serverseitigen Verbindung ausgewertet, daher sind die beiden folgenden Einstellungen global gültig (SET GLOBAL). Ein einfaches SET auf diesen Einstellungen wird automatisch an den globalen Slot weitergeleitet. Nutzen Sie RESET GLOBAL, um den Standard wiederherzustellen; ein einfaches RESET löscht nur die Sitzungssicht, und der Auth-Pfad liest weiterhin den veralteten globalen Wert.

Einstellung	Typ	Standard	Beschreibung
quack_authentication_function	VARCHAR	quack_check_token	Name einer 3-argumentigen Skalarfunktion (sid, client_token, server_token) -> BOOLEAN, mit der der Server Clients authentifiziert.
quack_authorization_function	VARCHAR	quack_nop_authorization	Name einer 2-argumentigen Skalarfunktion (sid, query) -> BOOLEAN, mit der der Server jede Abfrage autorisiert.

Sie können eigene Auth einbinden, indem Sie eine beliebige Skalarfunktion mit der erwarteten Signatur anlegen und die Einstellung darauf zeigen. Beispiele finden Sie unter Sicherheit.

FETCH-Batching (serverseitig)

Der Server fasst mehrere DataChunks in jeder FETCH-Antwort zusammen, um den Overhead pro Chunk zu senken.

Einstellung	Typ	Standard	Beschreibung
quack_fetch_batch_chunks	UBIGINT	12	Maximale Anzahl DataChunks, die pro FETCH-Antwort gesendet werden.

Knotenidentität

Diese Einstellungen speisen das Makro whoami(). quack_identify(...) ist syntaktischer Zucker, der sie aktualisiert.

Einstellung	Typ	Standard	Beschreibung
whoami_name	VARCHAR	(leer)	Menschenlesbarer Knotenname.
whoami_provider	VARCHAR	(leer)	Deployment-Anbieter (ec2, docker, local, …).
whoami_hostname	VARCHAR	(leer)	Netzwerk-Hostname / öffentliche Adresse.
whoami_region	VARCHAR	(leer)	Deployment-Region.
whoami_started_at	VARCHAR	(leer)	Startzeit des Knotens (ISO-8601-Zeitstempel). Ankert uptime.
whoami_meta	VARCHAR	{}	Anbieter-spezifische Metadaten als JSON.
quack_loaded_at_us	BIGINT	Epochenmikrosekunden beim Laden der Erweiterung	Fallback-Uptime-Anker, wenn whoami_started_at leer ist.

Logging

Die Erweiterung registriert zwei Log-Typen. Aktivieren Sie sie, um Konnektivität zu debuggen oder Request-Timing zu messen.

Quack-Log

Strukturiertes Log jeder Quack-Nachricht (client- und serverseitig):

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

Felder jedes Eintrags:

Feld	Beschreibung
message_type	Anfragetyp: PREPARE_REQUEST, FETCH_REQUEST usw.
quack_connection_id	Vom Server vergebene Verbindungs-ID (stabil über Anfragen in einem ATTACH).
client_query_id	Vom Client vergebene monotone ID, korreliert Client- / Server-Logs.
query	SQL-Nutzlast für PREPARE_REQUESTs.
server	HTTP-URL in clientseitigen Logs, NULL in serverseitigen Logs.
duration_ms	Roundtrip-Zeit (Client) oder Bearbeitungszeit (Server).
response_type	Antworttyp oder ERROR.
error	Fehlermeldung, wenn die Anfrage fehlgeschlagen ist.

Um eine Clientanfrage mit ihrer serverseitigen Verarbeitung zu korrelieren, joinen Sie auf (quack_connection_id, client_query_id).

HTTP-Log

Der zugrunde liegende HTTP-Transport kann separat geloggt werden:

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

Anfragen sind POSTs an einen Endpunkt /quack.

Logs zum Abfragen persistieren

duckdb_logs_parsed liest aus DuckDBs In-Memory-Log-Puffer. Für nicht-triviale Sitzungen sollten Sie Logs persistieren:

CALL enable_logging(
    'Quack',
    storage => 'file',
    storage_config => {'path': '/tmp/duckdb-rpc-logs'}
);

Um das Log zwischen Läufen zu leeren, nutzen Sie:

CALL truncate_duckdb_logs();

Um das Logging auszuschalten, führen Sie aus:

CALL disable_logging();