Quack-Remote-Protokoll

Wir haben Quack am 12. Mai 2026 veröffentlicht. Lesen Sie den Ankündigungsbeitrag!

Die Quack-Erweiterung macht eine DuckDB-Instanz zu einem Server, mit dem sich andere DuckDB-Instanzen (Clients) über HTTP verbinden können.

Diese Seite gibt einen kurzen Überblick über das Protokoll und führt durch die grundlegende Nutzung auf beiden Seiten der Verbindung. Die vollständige Liste der Funktionen, Einstellungen und Logging-Schalter finden Sie in der Referenz. Zur Konfiguration von TLS sowie Authentifizierung / Autorisierung siehe Sicherheit. Anleitungen finden Sie unter Einrichtung.

Warnung Quack befindet sich in aktiver Entwicklung; Protokoll, Funktionsnamen, Einstellungen und Standardwerte können sich noch ändern. Diese Seite dokumentiert die Beta-Version von Quack, verfügbar in DuckDB v1.5.3, ausgeliefert über das Repository core.

Quack in Kürze

Kurz gesagt funktioniert das Quack-Protokoll und seine Interaktionen wie folgt:

• HTTP-basiert. Quack-Nachrichten laufen über einfaches HTTP oder HTTPS über einen Reverse-Proxy (siehe Sicherheit). Standard-Load-Balancer, Firewalls und Reverse-Proxys behandeln Quack-Verkehr daher wie jeden anderen HTTP-Dienst. Es gibt kein eigenes Wire-Transport zu betreiben.
• Clientgesteuerte Anfrage und Antwort. Jede Interaktion wird vom Client ausgelöst. Der Server startet keine Interaktionen per Push.
• Serialisierung application/duckdb. Anfragen und Antworten werden mit DuckDBs internen Serialisierungsprimitiven kodiert (derselbe Codepfad wie beim Write-Ahead Log). So entfällt der Umweg über ein Austauschformat, und komplexe Typen (geschachtelt, Decimals, Intervals, …) bleiben über die Leitung verlustfrei.
• Ein Roundtrip pro Abfrage. Nach dem initialen Connection-Handshake braucht eine Abfrage nur ein Request-Response-Paar. Große Ergebnisse streamen in Chunks über nachfolgende FETCH-Anfragen zurück, optional parallelisiert auf mehreren Threads.
• Standardport: 9494. Alle URIs nutzen das Schema quack:, z. B. quack:hostname:port, wobei der Port standardmäßig 9494 ist.

Nutzung auf der Serverseite

Einen Server starten

Ein Server wird aus einer bestehenden DuckDB-Sitzung gestartet. Alles, was die Sitzung sehen kann (In-Memory-Tabellen, angehängte Dateien, Schemas), wird über das Remote-Protokoll erreichbar.

Um auf localhost zu lauschen, führen Sie aus:

{:.codebox-server}

CALL quack_serve('quack:localhost');

quack_serve liefert die Listen-URI, die HTTP-URL und – wenn die Standard-Authentifizierungsfunktion verwendet wird – das auth_token, das Clients zum Verbinden benötigen. Dieses Token kann auch vor dem Start explizit gesetzt werden (siehe Sicherheit).

Standardmäßig weigert sich der Server, etwas anderes als einen lokalen Hostnamen zu binden. Um auf einer von außen erreichbaren Adresse zu lauschen, übergeben Sie allow_other_hostname => true:

{:.codebox-server}

CALL quack_serve('quack:0.0.0.0:9494', allow_other_hostname => true);

In diesem Fall sollten Sie den Server hinter einen TLS-terminierenden Reverse-Proxy stellen. Siehe Quack mit einem Reverse-Proxy absichern.

URI-Format

Quack-Endpunkte nutzen das URI-Schema quack: und 9494 als Standardport. Einige Beispiele:

URI	Host	Port	Kommentar
quack:localhost	localhost	9494
quack://localhost	localhost	9494
quack:myhost:9000	myhost	9000
quack:127.0.0.1	127.0.0.1	9494
quack:[::1]:1234	::1	1234	(IPv6)

Sie können eine URI mit der Skalarfunktion quack_uri_parser(uri, ssl) parsen und validieren.

Einen Server stoppen

Um einen Server zu stoppen, führen Sie aus:

{:.codebox-server}

CALL quack_stop('quack:localhost');

Nutzung auf der Clientseite

Es gibt zwei Wege, mit einem Quack-Server zu sprechen:

1. quack_query(uri, query): zustandslose Abfragen.
2. ATTACH 'quack:host' AS name: die Remote-Seite als vollständigen Katalog anhängen.

In beiden Fällen müssen Sie sich authentifizieren.

Der Client wählt für lokale URIs (localhost, 127.0.0.1, ::1) automatisch einfaches HTTP und sonst HTTPS. Beide Standardwerte lassen sich mit der Konfigurationsoption DISABLE_SSL überschreiben.

Zustandslose Abfragen mit quack_query

Sie können beliebiges SQL gegen einen Server ausführen, ohne ihn anzuhängen. Um eine lokale Datenbank über HTTP abzufragen, führen Sie aus:

{:.codebox-client}

FROM quack_query(
    'quack:localhost',
    'SELECT 42',
    token = '⟨MY_QUACK_TOKEN_01234567890ABCDEF⟩');

Remote-Datenbanken nutzen standardmäßig HTTPS. Um das für eine Remote-Seite mit einfachem HTTP zu überschreiben, führen Sie aus:

{:.codebox-client}

FROM quack_query(
    'quack:remote.com',
    'SELECT 42',
    token = '⟨MY_QUACK_TOKEN_01234567890ABCDEF⟩',
    disable_ssl => true
);

Die Abfrage wird remote ausgeführt, und der Server streamt das Ergebnis zurück. Fehler auf dem Server (Parse-Fehler, fehlende Tabellen usw.) werden lokal im DuckDB-Client angezeigt.

Eine Remote-Datenbank anhängen

Um eine lokale Datenbank über HTTP anzuhängen, führen Sie einfach aus:

{:.codebox-client}

ATTACH 'quack:localhost' AS remote_db (
    TOKEN '⟨MY_QUACK_TOKEN_01234567890ABCDEF⟩'
);

Das Anhängen von Remote-Datenbanken nutzt standardmäßig HTTPS. Um das für eine Remote-Seite mit einfachem HTTP zu überschreiben:

{:.codebox-client}

ATTACH 'quack:remote.com' AS remote_db (
    TOKEN '⟨MY_QUACK_TOKEN_01234567890ABCDEF⟩',
    DISABLE_SSL true
);

Nach dem Anhängen sehen Remote-Tabellen aus und verhalten sich wie lokale:

{:.codebox-client}

CREATE TABLE remote_db.t AS FROM range(10) r(i);  -- DDL on remote
INSERT INTO remote_db.t VALUES (42);              -- remote writes

Sie können Abfragen gegen die Remote-Datenbank ausführen:

{:.codebox-client}

FROM remote_db.t;              -- scan remote table
FROM remote_db.t WHERE i = 42; -- run filter remotely
BEGIN; ...; COMMIT;            -- transactions are forwarded
DETACH quack;                  -- detach from the remote database

Der angehängte Katalog stellt außerdem ein Tabellenmakro query für Ad-hoc-SQL im Umfang dieses Anhangs bereit:

{:.codebox-client}

FROM remote_db.query('SELECT 42');

Authentifizierung

Clients übergeben das Authentifizierungstoken an den Server auf eine von zwei Arten: ein auf die Server-URI beschränktes quack-Secret oder eine explizite Option TOKEN bei ATTACH / quack_query. Den vollständigen Überblick finden Sie unter Sicherheit.

Wir empfehlen ein auf die Server-URI beschränktes Secret:

{:.codebox-client}

CREATE SECRET (
    TYPE quack,
    TOKEN '⟨MY_QUACK_TOKEN_01234567890ABCDEF⟩',
    SCOPE 'quack:localhost'
);

ATTACH 'quack:localhost' AS remote_db (TYPE quack);

Alternativ können Sie das Token direkt übergeben; das überschreibt jedes passende Secret:

{:.codebox-client}

ATTACH 'quack:localhost' AS remote_db (
    TOKEN '⟨MY_QUACK_TOKEN_01234567890ABCDEF⟩'
);

HTTP-Verbindungscaching

Standardmäßig öffnet jede Quack-Clientanfrage eine neue Verbindung zum Server – ein neuer TCP- und, mit SSL, ein teurer TLS-Handshake. Verbindungscaching wiederverwendet Verbindungen über Anfragen hinweg und senkt so die Latenz pro Abfrage bei wiederholten Anfragen:

{:.codebox-client}

SET httpfs_connection_caching = true;

Knotenidentität (whoami)

Jeder Quack-Knoten stellt ein Tabellenmakro whoami() bereit, das grundlegende Identitäts- und Laufzeitinformationen liefert – nützlich beim Weiterleiten an eine Serverflotte oder beim Korrelieren von Logs:

{:.codebox-client}

FROM remote_db.query('FROM whoami()');

┌─────────┬──────────┬──────────┬─────────┬─────────────────┬───────────────────────────────┬────────────────────────────────────────────────────┐
│  name   │ provider │ hostname │ region  │     uptime      │            ts_now             │                        meta                        │
│ varchar │ varchar  │ varchar  │ varchar │    interval     │   timestamp with time zone    │                        json                        │
├─────────┼──────────┼──────────┼─────────┼─────────────────┼───────────────────────────────┼────────────────────────────────────────────────────┤
│ NULL    │ NULL     │ NULL     │ NULL    │ 00:04:56.832456 │ 2026-05-22 15:59:38.631715+02 │ {"duckdb_version":"v1.5.3","platform":"osx_arm64"} │
└─────────┴──────────┴──────────┴─────────┴─────────────────┴───────────────────────────────┴────────────────────────────────────────────────────┘

Identitätsfelder werden gesetzt, indem Sie entweder die Optionen whoami_* direkt setzen oder den Helfer quack_identify aufrufen:

{:.codebox-client}

CALL quack_identify(
    name => 'analytics-1',
    provider => 'ec2',
    region => 'eu-west-1',
    meta => '{"role": "worker"}'
);

meta wird mit den automatisch berechneten Schlüsseln duckdb_version und platform zusammengeführt; bei Konflikten gewinnen benutzerdefinierte Schlüssel. whoami_started_at (ein ISO-8601-Zeitstempel) überschreibt den Uptime-Anker, andernfalls wird die Uptime ab dem Laden der Erweiterung gemessen.