quackapi

HTTP-Framework der FastAPI-Klasse in DuckDB — CREATE ROUTE macht aus SQL typisierte, validierte Endpunkte; ein Prozess ist DB + HTTP (+ PDF/Renderer über Begleiterweiterungen).

Maintainer: asubbarao

Installation und Laden

INSTALL quackapi FROM community;
LOAD quackapi;

Beispiel

LOAD quackapi;

-- JSON endpoint: the SELECT is the handler
CREATE ROUTE hello GET '/hello' AS SELECT 'world' AS msg;

-- Path params bind as $id; cast failure → FastAPI-shaped 422
CREATE ROUTE item GET '/items/:id' AS SELECT $id::INTEGER AS id;

-- HTML when the single output column is named html
CREATE ROUTE home GET '/' AS SELECT '<h1>quackapi</h1>' AS html;

-- Typed optional query param with constraint
CREATE ROUTE search GET '/search'
  PARAM limit INTEGER DEFAULT 10 LE 100
  AS
SELECT $q::VARCHAR AS q, $limit::INTEGER AS limit;

-- POST mutation (JSON body fields bind as $name / $age)
CREATE ROUTE create_user POST '/users' STATUS 201 AS
SELECT $name::VARCHAR AS name, $age::INTEGER AS age;

-- Serve (background threads; shell stays usable)
-- Optional: static_dir for unrouted GETs; cors_origins for browser CORS
SELECT * FROM quackapi_serve(8000, static_dir := './static');

-- curl http://127.0.0.1:8000/hello          → [{"msg":"world"}]
-- curl http://127.0.0.1:8000/items/42       → [{"id":42}]
-- curl http://127.0.0.1:8000/items/abc      → 422 detail[loc=path,id]
-- curl -X POST …/users -H 'Content-Type: application/json' -d '{"name":"a","age":3}'

SELECT * FROM quackapi_routes();
SELECT * FROM quackapi_stop(8000);

Über quackapi

quackapi

Ein HTTP-Framework der FastAPI-Klasse, das in DuckDB lebt. Routen sind DDL, Handler sind SQL, und die Anfragevalidierung ist das Typensystem der Datenbank.

These: das Backend IST die Datenbank

Ein konventioneller Stack serialisiert an jedem Hop (App-Server → Worker → DB → PDF-Microservice). quackapi verdichtet das zu einem DuckDB-Prozess:

browser → DuckDB [ quackapi(HTTP) · pdf · tera · fakeit · webbed · … ]

Begleitende Community-Erweiterungen (pdf, tera, fakeit, crawler/webbed, cronjob, curl_httpfs, …) werden in denselben Adressraum geladen. Ein Handler, der ein PDF schwärzt, ist wörtlich SELECT pdf_redact(...) — kein RPC zwischen Schichten.

Showcase: die Closure-Redaction-Review-App (DB + HTML-UI + PDF-Wort- boxen + POST-Entscheidungen + statische Assets) läuft als einzelner DuckDB-Prozess über CREATE ROUTE + quackapi_serve.

CREATE ROUTE

CREATE [OR REPLACE] ROUTE <name> <METHOD> '<pattern>'
  [STATUS <n>] [REQUIRE <auth>] [GROUP <g>]
  [BODY SCHEMA '<json-schema>']
  [PARAM <name> [<type>] [HEADER|COOKIE|QUERY …] [DEFAULT …] [GE|LE|…] …]
  AS <select>;

• Methoden: GET, POST, PUT, DELETE, PATCH, HEAD.
• Pfadsegmente :id / {id} und Query-/Body-Felder binden an $id.
• Cast-/Constraint-Fehler liefern 422 im FastAPI-Format {"detail":[{"loc":[...],"msg":...,"type":...}]}.
• Die Standard-JSON-Antwort ist ein Array von Zeilenobjekten (SQL-Resultset- Semantik). Eine einzelne Spalte namens html oder text gibt rohes HTML/Text zurück; location / set_cookie setzen Antwort-Header.
• quackapi_serve([port], host := …, static_dir := …, cors_origins := …, memory_limit := …) verwendet DuckDBs mitgeliefertes httplib (Hintergrund-Listener + Worker).
• Eingebautes OpenAPI: GET /openapi.json, GET /docs, GET /redoc.

Weitere DDL / Funktionen

• Auth: CREATE AUTH … AS API_KEY | JWT (SECRET … [, ALGORITHM HS256]), REQUIRE an Routen, quackapi_add_api_key, quackapi_auths, Claims als $claims_*. Die JWT-Prüfung ist in sich geschlossen (von DuckDB mitgeliefertes mbedtls + json_*-Claims) — hängt nicht von der Community-Erweiterung crypto ab (diese ist nur Hash/HMAC, kein JWT-Parse/exp/nbf/Claims).
• Gruppen: CREATE GROUP … WITH (prefix=…, auth=…, tags=…) — Pfadpräfix
  • Auth-Vererbung (quackapi_groups()).
• Table API: CREATE API FOR TABLE t [AT '/path'] [KEY 'id'] → nur GET-Liste
  • GET per Schlüssel.
• Queue: CREATE QUEUE, quackapi_enqueue/dequeue/ack/nack, Tabelle quackapi_jobs (ohne Broker; kombinieren Sie cronjob für Worker).
• SSE: CREATE STREAM … GET '/path' AS <select> (text/event-stream; WebSocket wird von httplib nicht unterstützt).
• Policies: CREATE ROW ACCESS POLICY / CREATE MASKING POLICY + Bindung über ALTER TABLE; quackapi_policies().
• Inspektion: quackapi_routes(), quackapi_servers(), quackapi_http_util_name().

Plattformen und Build

Zielt nur auf DuckDB v1.5.5. C++17; hängt nur von DuckDBs mitgeliefertem httplib und mbedtls ab (kein vcpkg, kein libcurl). CI baut linux/macOS/windows_amd64; schließt wasm und Windows MinGW/rtools/arm64 aus.

Grenzen (offen)

• DuckDB Single-Writer / Dateikonkurrenz — kein High-Write-Multi-Tenant-OLTP.
• Der Serve-memory_limit-Standard von 256 MB gilt nur, wenn nichts konfiguriert ist; verwenden Sie memory_limit := '4GB' / SET quackapi_memory_limit (überschreibt nie ein Operator-SET memory_limit).
• Request-Body maximal 8 MiB; JWT nur HS256 (kein RS256/OIDC); die Table API ist ein schreibgeschütztes Gerüst.
• Die Routenregistry ist instanzbezogen (DDL nach erneutem Öffnen erneut ausführen); Queue-Jobs bleiben in quackapi_jobs erhalten.

Vollständige Referenz: https://github.com/asubbarao/quackapi
Entwurf der Community-Seite: https://github.com/asubbarao/quackapi/blob/main/docs/community-page.md

Hinzugefügte Funktionen

Überladene Funktionen

Diese Erweiterung fügt keine Funktionsüberladungen hinzu.

Hinzugefügte Typen

Diese Erweiterung fügt keine Typen hinzu.

Hinzugefügte Einstellungen