@anteros/duckdb
v0.0.15
Published
Anteros DuckDB — a DuckDB instance over the Quack protocol
Readme
@anteros/duckdb
A DuckDB instance over the Quack protocol — the protocol that turns DuckDB into a client-server database.
- Two classes:
DuckdbQuackInstance(the client) andDuckdbQuackServer(the server) - Attaching a server makes it the default catalog: unqualified
eventsis the server's table, and the client's own memory catalog stays reachable asmemory.<table> - Data tables:
db.table("tickets")→data(JSON) +ts(TIMESTAMP),tsmapping a document field exec,createTable,deleteTable,listTables,ingest+flush,raw(),close()— and nothing else to configure- Backups:
db.backup()snapshots the database while it serves — a hot clone of the file or anEXPORT DATABASEdump, on demand or on a timer — andantd restoreputs either one back
⚠️ Quack is experimental through DuckDB 1.x. DuckDB documents the protocol, the function names and the implementation details as subject to change up to the stable 2.0 line. This package is pinned to
@duckdb/node-api2.0.0-r.1 (DuckDB 2.0.0): pin it too, and prefer this package over hand-rolling the attach so the SQL lives in one place.
CLI
The package ships the antd binary as well: same server, from the terminal, no code —
bunx @anteros/duckdb start --token …, or antd start … once installed. It is a thin layer over
DuckdbQuackServer: flags, banner, signals. antd restore is the other direction: it puts a
backup() snapshot back into a database file. The options and examples are under
The antd CLI.
Install
bun add @anteros/duckdbQuack in 30 seconds
The server is a DuckDB instance that listens (any DuckDB process — the CLI, another Bun process, a container):
INSTALL quack; -- auto-installed on first use, but explicit is fine
LOAD quack;
CALL quack_serve('quack:0.0.0.0:9494', token = 'super-secret');The client is this package:
import { DuckdbQuackInstance } from "@anteros/duckdb";
const db = new DuckdbQuackInstance({
url: "quack:localhost:9494",
token: process.env.QUACK_TOKEN,
settings: { threads: 2 }, // the client instance: pin the threads
});
// One table, two columns: `data` (JSON) and `ts` (TIMESTAMP).
const tickets = await db.table("tickets", { ts: "createdAt" });
await tickets.ingest([
{ ref: "A-1", total: 42, createdAt: "2026-10-01T08:30:00Z" },
{ ref: "A-2", total: 7 },
]);
await tickets.flush();
const { rows, duration_ms } = await db.exec(`
SELECT ts, data->>'ref' AS ref, CAST(data->>'total' AS DOUBLE) AS total
FROM tickets ORDER BY ts
`);
// CRUD on matching documents — `where` is mandatory.
await tickets.update("data->>'ref' = 'A-1'", { total: 43 });
await tickets.replace("data->>'ref' = 'A-2'", { ref: "A-2", total: 7 });
await tickets.delete("data->>'ref' = 'A-2'");
await db.close();Options
| Option | Type | Default | Description |
| ---------- | --------------------------------------- | ------------------ | ------------------------------------------------------------------------------ |
| url | string | — | The Quack server, 'quack:host' (9494) or 'quack:host:port'. IPv6: 'quack:[::1]:9494'. Omit for a purely local instance. |
| token | string | DUCKDB_QUACK_TOKEN | The shared secret, sent as a secret scoped to url (CREATE SECRET … SCOPE '…'). |
| as | string | 'quack' | The catalog name the remote is attached under — and then made the default catalog (USE). |
| db | string | — | Select a database on the server (USE) — for a server exposing several attached databases; requires url. |
| readOnly | boolean | — | Refused — Quack 2.0 accepts READ_ONLY on ATTACH and ignores it. Enforce it on the server (authorizationFunction). |
| disableSsl | boolean | Quack's default | true = plain HTTP, false = forced TLS (even localhost), omitted = plain for a local URI and TLS otherwise (DISABLE_SSL). |
| sslFingerprint | string | — | Trust a self-signed certificate (SSL_FINGERPRINT) — the value quack_generate_keys returns. |
| clientId | string | random | Client id sent to the server (CLIENT_ID), at least 4 characters. |
| heartbeatTimeout | number | 60 | Heartbeat lease in seconds (HEARTBEAT_TIMEOUT). |
| autoReattach | boolean \| 'reads' \| 'always' | 'reads' | Re-attach and retry after a server restart — reads only by default; true retries any statement. |
| secret | string | 'anteros_quack' | Name given to the created secret. |
| dbPath | string | — | Open a local DuckDB file instead of memory. The remote's data is never here. |
| settings | DuckdbOptions | — | DuckDB configuration of the local instance — threads, memory_limit… autocomplete; any other setting passes through. |
| columns | DuckdbColumn[] | id/ts/data | Shape of a table created without a schema. |
| tables | DuckdbTableSchema[] | — | Tables the instance must have — reconciled at startup (see below). |
| onError | (error: Error) => void | console.error | Where a failed background ingest is reported immediately (flush() also throws it). |
| debug | boolean | false | Log every operation and failure to the console — [duckdb] for the instance, [quack] for the server (see below). |
| maxQueuedBatches | number | 64 | Backpressure: queued ingest() calls before the producer waits. 0 = unbounded (see below). |
| closeTimeoutMs | number | 30_000 | How long close() waits for queued writes; past it the statement is interrupted and DUCKDB_FLUSH_TIMEOUT thrown. |
as names the attachment on the client; db selects a database inside the server. If the
server has attached several files (ATTACH 'PROD_RTL.duckdb' AS PROD_RTL), a client can pick one:
const db = new DuckdbQuackInstance({ url, token, db: "PROD_RTL" });
await db.exec("SELECT * FROM orders"); // runs on PROD_RTL, not the server defaultThe choice is per client session (USE on the server). Without db, the server's default database is
used — the dbPath file's database (e.g. DEMO_ST for DEMO_ST.duckdb), or memory. A missing named
database fails at connect() with DUCKDB_QUACK_DATABASE_FAILED; db without url is refused.
Why USE, not CONNECT
Quack's overview recommends CONNECT qk to route a whole session to the remote. This wrapper does not: it
attaches the remote as a catalog, runs USE quack, and sends each exec through
quack_query_by_name('quack', sql) — one statement, executed remotely, result streamed back.
CONNECTdoes not lift the parameter limit. Verified against DuckDB 2.0: on a routed session,run('SELECT $1', [42])still fails with "Values were not provided for the following parameters" — so the inlining of literals stays necessary either way, andCONNECTbuys nothing there.- The workspace stays usable. With
USE,db.raw()is still the client's own catalog (memory.orders), anddb.exec('…')targets the server explicitly. Routing the whole session makes every statement remote — including the local bookkeeping (CREATE TEMP TABLE,SET), which then lands on the server. - Re-attaching stays simple.
reattach()steps back withUSE <local>,DETACH,ATTACH; a routed session needsDISCONNECTfirst, and one forgottenDISCONNECTsends the next local statement to the server.
If you want the routed session, it is one statement away — db.raw() gives the connection:
const { connection } = await db.raw();
await connection.run("CONNECT quack"); // now plain SQL runs on the server
await connection.run("DISCONNECT"); // back to the attached catalogHTTP connection caching
Quack clients talk HTTP through httpfs, which reuses the connection by default
(httpfs_connection_caching = true): the instance pays one TCP — and, when remote, one TLS — handshake, not one
per query. It is a setting like any other, so it belongs in settings:
const db = new DuckdbQuackInstance({
url,
token,
settings: { httpfs_connection_caching: false }, // disable — debugging only
});Keep the default on: a long-lived instance (or a pool of them) is what makes small, frequent queries cheap.
Turn it off to debug a proxy or a load balancer, or to force a fresh connection per request. It applies to the
whole httpfs client of the instance — Quack, S3, GCS — not just the remote.
Methods
| Method | What it does |
| ------------------------------------------- | ------------------------------------------------------------------------------- |
| connect() | Opens the local instance and attaches the remote. Idempotent, called for you. |
| reattach() | DETACH + ATTACH after a server restart; drops the schema caches. |
| exec(sql, values?) | Runs one statement, returns { columns, types, rows, duration_ms }. On an attached instance it runs on the Quack server (quack_query_by_name); values run in the client engine, inlined as SQL literals (Quack 2.0 cannot bind parameters on a remote catalog). |
| stream(sql, { signal? }) | The same statement, in batches (~2048 rows) — memory-safe reading of a big result. |
| stats | Live counters: queries, errors, rows, written, reconnects, pendingWrites, uptimeMs. |
| transaction(fn) | BEGIN TRANSACTION / COMMIT around fn(tx), ROLLBACK on throw; tx.exec stays server-side. |
| createTable(table, columns?) | CREATE TABLE IF NOT EXISTS — on the attached remote when there is one. |
| deleteTable(table) | DROP TABLE IF EXISTS — on the attached remote when there is one. |
| listTables() | The tables of the attached remote, or of the local catalog when not attached. |
| createFtsIndex(table, options) | Builds/rebuilds a full-text index (fts); on the attached remote when there is one. |
| searchFts(table, query, options) | BM25 search, best match first — runs on the server when attached. |
| dropFtsIndex(table) | Drops the index; dropped: false when there was none. |
| createVssIndex(table, options) | Builds/rebuilds an HNSW index on a FLOAT[N] column (vss). |
| searchVss(table, vector, options) | Nearest vectors, distance included — runs on the server when attached. |
| dropVssIndex(table, options) | Drops the HNSW index; dropped: false when there was none. |
| setVar(name, value) | SET VARIABLE name = value; on the server when attached. |
| getVar(name) / resetVar(name) | Read (null when unset) / RESET VARIABLE. |
| listVars() | Every session variable with its type (duckdb_variables()). |
| ingest({ table, rows, insertBatchSize?, appender? }) | Queues rows in the background; creates the table if it is missing (on the remote when attached). Waits for room past maxQueuedBatches. |
| flush() | Waits for every queued write, then throws the first failure once. |
| pendingWrites | How many background writes are queued right now — the number maxQueuedBatches bounds. |
| close({ timeoutMs? }) | Releases the instance; queued writes are awaited up to the deadline, then interrupted. |
| syncSchema() | Waits for the startup reconciliation of tables — reports what changed. |
| table(name, { ts? }) | A data table — data JSON + ts TIMESTAMP, created in the background. |
| update({ table, where, set, upsert? }) | Patches matching documents (json_merge_patch); upsert: true inserts set on a miss. |
| replace({ table, where, set }) | Replaces matching documents entirely — where mandatory; set is stored whole. |
| delete({ table, where }) | Deletes matching documents — where mandatory. |
| purge({ table, column, ttl, where?, batch? }) | Deletes rows older than ttl on a date column — no native DuckDB TTL. |
| retention({ …, every }) | Repeats the purge on a timer; returns { run, stop, running }. |
| backup({ directory, format?, keep? }) | Snapshots the database — a hot clone of the file (default) or EXPORT DATABASE; returns { path, format, at }. Local only (DUCKDB_BACKUP_REMOTE). See Backups. |
| raw() | The underlying { instance, connection } — the escape hatch. |
| close() | Closes the instance; later calls are refused. |
| isConnected / isAttached / url / alias | State, readable at any time. |
duration_ms is the call duration: execution, the result transfer (remote mode) and the
row materialisation (columns + rows built as JS objects) — opening/attaching the instance is not counted.
A query returning 500k rows costs far more than the same scan aggregated to one row, and that difference is
in duration_ms.
Quack settings
The extension registers ordinary DuckDB settings — set them in settings at creation, or with
SET GLOBAL at run time. Defaults are Quack's own.
| Setting | Default | What it does |
| --- | --- | --- |
| quack_target_batch_bytes | 32 MiB | Target size of one wire batch |
| quack_prepare_inline_rows | 24 576 | Rows returned inline in the PREPARE response |
| quack_fetch_read_ahead | 0 (async threads) | FETCH requests kept in flight ahead of the scan |
| quack_rebalance_buffer_bytes | 0 (auto) | Pending bytes the batch rebalancer buffers |
| quack_server_stream_buffer_bytes | 256 MiB | Server-side per-stream byte budget |
| quack_server_max_connections | 1024 | Maximum concurrent connections |
| quack_server_keep_alive_timeout | 300 | Seconds an idle keep-alive connection stays open |
| quack_default_client_id | random (QUACK_CLIENT_ID) | Client id sent to the server — at least 4 characters |
| quack_default_heartbeat_timeout | 60 | Heartbeat lease in seconds |
| quack_enable_reconnects | false | Acknowledge results and cache them for reconnects |
| quack_result_ttl | 3600 | Seconds an idle cached result is kept (0 = never) |
| quack_cache_max_rows | 100 000 | Maximum rows kept in the server result cache |
| quack_authentication_function | quack_check_token | 3-arg callback (sid, client_token, server_token) |
| quack_authorization_function | quack_nop_authorization | 2-arg callback (sid, query) |
const server = new DuckdbQuackServer({
token: "super-secret",
settings: {
quack_server_max_connections: 2048,
quack_server_keep_alive_timeout: 600,
quack_enable_reconnects: true,
quack_result_ttl: 600,
},
});The client side takes the same settings in its own settings, plus the ATTACH-level sslFingerprint,
clientId and heartbeatTimeout at the top level. A client setting (quack_fetch_read_ahead,
quack_default_client_id, reconnects…) only matters on the instance that talks to the server; the server
settings only on the instance that serves.
When the server restarts
An attachment is tied to the server's database instance, not just to its URL. A restart — deploy, crash,
stop() then start(), or a fatal I/O error — invalidates it: DuckDB says "invalidated its database" or
"invalid connection id", and the attachment cannot be reused as is. The wrapper maps both to
DUCKDB_QUACK_DATABASE_INVALIDATED and handles it according to autoReattach:
| autoReattach | Behaviour |
| --- | --- |
| 'reads' (default) | exec re-attaches and retries read-only statements (SELECT/FROM/WITH/SHOW/DESCRIBE/EXPLAIN…) |
| true / 'always' | Retries any statement — a write may have committed before the invalidation, so make it idempotent first |
| false | Throws the typed error; you call reattach() and retry |
const db = new DuckdbQuackInstance({
url,
token,
// autoReattach: "reads", // default — reads recover by themselves
});reattach()steps back to the client's own catalog (USE), detaches the alias, attaches again with the same token/settings, re-appliesdb, and drops the schema caches. It is always available for an explicit retry, whatever the option says. Concurrent calls are single-flight: a burst of failed reads (exactly what a restart produces) shares one DETACH/ATTACH instead of racing on the same connection.- An
execinsidedb.transaction(…)is never retried: the transaction is gone, and re-attaching would silently start a new one. quack_enable_reconnectsonly covers a dropped HTTP connection with a cached result — it cannot survive a restarted server.- Server side: keep
dbPathon a persistent volume, stop gracefully (stop()/Ctrl-C), supervise the process. A restart is expected; the client is what re-attaches. whoami()(orquack_server_list()) reports the server's uptime — the quickest way to confirm a restart.
Where a statement runs
On an attached instance, exec always runs the statement on the Quack server
(quack_query_by_name): the remote computes, and only the result crosses the wire — what a large aggregate
needs, since the client path would fetch every data.
await db.exec("SELECT SUM(CAST(data.prix AS INT)) AS total FROM tickets"); // on the server
await db.exec("SELECT * FROM tickets WHERE id = $1", ["a-1"]); // client (values inlined)One exception: a statement with bound values runs in the client's engine. Quack 2.0 prepares it against
the attached catalog and does not carry bind parameters over the wire, so this package inlines them as
escaped SQL literals ($1, $name; quoted strings, identifiers, dollar-quotes and comments are left alone).
The client's own catalog and the remote alias are then reachable through db.raw() — an escape hatch, not the
normal path. On a local instance (no url), everything runs in the client and the values stay bound: there is
no server.
Session variables
SET VARIABLE is available through exec, and wrapped by four methods:
await db.setVar("my_var", 30);
await db.getVar("my_var"); // 30
await db.exec("SELECT 20 + $my_var"); // 50
await db.listVars(); // [{ name, value, type }]
await db.resetVar("my_var");setVarhandles scalars: string, number, boolean,null,Date(TIMESTAMP). For a DuckDB list/map or a query result, run the SQL yourself:db.exec("SET VARIABLE files = (SELECT list(...) …)").getVarusesgetvariable()and returnsnullfor an unset variable.- On an attached instance, the four methods run on the Quack server, and variables are session-scoped:
they persist across
execcalls without values. A statement with boundvaluesruns in the client engine, so it reads/writes client variables instead. $nameis DuckDB 2.0's shorthand forgetvariable('name'). Our inliner leaves a$nameit was not given a value for to DuckDB, so session variables still work; unlikegetvariable, an unset$nameraises.listVars()readsduckdb_variables():valueis text,typeis the DuckDB type.- Variables are session state — nothing is persisted in the database file.
Storage and files
A DuckDB database is one file, not a directory — the dbPath you pass (extension free: .duckdb,
.db, .ddb…). Schemas, tables, indexes, views and metadata live in it, in DuckDB's block/row-group
storage format (v2.0.0 / version 69 by default in DuckDB 2.0;
older versions cannot read it).
| File | Role | When |
| --- | --- | --- |
| app.duckdb | The database | Always (file mode) |
| app.duckdb.wal | Write-ahead log — committed changes not yet checkpointed | During writes, until a checkpoint |
| app.duckdb.tmp/ | Spilling files (temp_directory) | Only when a query exceeds memory |
| ~/.duckdb/extensions/… | Installed extensions (quack, fts, vss…) | Outside the database |
| ~/.duckdb/stored_secrets/ | Persistent secrets | Outside the database |
The WAL is the crash-recovery journal: a committed write is appended there, and a
checkpoint merges it into the main file. Checkpoints
happen automatically when the WAL grows (checkpoint_threshold, 16 MiB by default), on CHECKPOINT, or on a
clean close — which is why a running database can show two files and a closed one shows a single file.
PRAGMA database_size reports database_size and wal_size separately. Attached databases are separate
files, each with its own optional .wal; duckdb_databases() lists them.
A clean stop() / close() checkpoints and releases the file — what a backup should copy. Do not copy only
the main file while its WAL still holds changes, and never delete a live .wal. A running database needs no
stop at all: db.backup() takes a consistent clone in the engine (see Backups).
const db = new DuckdbQuackInstance({ dbPath: "./data/analytics.duckdb" });
const snapshot = await db.backup({ directory: "./backups" });
// { path: "./backups/analytics-20261101T143000Z.duckdb", format: "file", at: … }A Quack client is in memory by default (its own dbPath, if any, is a separate local file); only the
server's dbPath is durable.
Transactions
await db.transaction(async (tx) => {
await tx.exec("INSERT INTO orders VALUES ($1, $2)", ["A-1", 42]);
await db.ingest({ table: "events", rows: [{ id: "e-1", kind: "created" }] });
await db.update({ table: "docs", where: "data->>'ref' = 'A-1'", set: { v: 2 } });
});
// COMMIT on success, ROLLBACK when the callback throwsOn an attached instance the transaction runs on the Quack server; tx.exec stays there (values are
inlined), so it participates. Another client sees nothing before COMMIT (snapshot isolation).
The instance-level writers join it as well: db.ingest, db.update, db.replace and db.delete run
server-side, on the transaction's connection. ingest requires the table to already exist — a table created
inside the transaction is refused (DUCKDB_TRANSACTION_TABLE_REQUIRED), since createTable runs in the client
engine and cannot see the open server transaction. Create it before, or with a raw
tx.exec("CREATE TABLE …"). On a local instance ingest reuses the same connection, so it joins there too —
a table it creates inside the transaction is rolled back with it. That is also the case for a
DuckdbQuackServer's own server.db: a client's open transaction does not block its writes.
On an attached instance, still outside the transaction: createTable, deleteTable, the
db.table(name) handle methods, and exec(sql, values) called outside tx — all run in the client engine.
A local instance shares one connection, so those join the transaction instead. tx.exec is server-side on an
attached instance, so it cannot run client-only SQL (USE, ATTACH, memory.…).
One transaction at a time per instance (DUCKDB_TRANSACTION_NESTED); the connection is shared, so do not run
concurrent queries on the same instance while it runs. Manual db.exec("BEGIN TRANSACTION") / COMMIT /
ROLLBACK also work, with the same rule: writes must use exec without values (server-side).
Default table shape
id (VARCHAR), ts (TIMESTAMP), data (JSON) — an append-only event log. A row that leaves ts or id out gets the current time and a UUID; a Date is written as the local wall clock (formatTimestamp, exported).
A JSON column reads back as the string DuckDB stores: JSON.parse it for the object.
Retention (TTL)
DuckDB has no native TTL — no background job, no expiry index. purge() deletes what a date column says is
too old, and retention() repeats it on a timer:
// Once
const { deleted } = await db.purge({ table: "events", column: "ts", ttl: "30d" });
// …or on a schedule (`runOnStart` is the default)
const job = db.retention({ table: "events", column: "ts", ttl: "30d", every: "1h" });
// … later
job.stop();ttl—'30d','24h','90m','3600s','2w', or aDate(rows older than that instant).column— aDATE,TIMESTAMP,TIMESTAMPTZor ISO-string column; it is cast toTIMESTAMP.where— extra predicate, ANDed with the window ("data->>'kind' = 'log'").batch— rows perDELETE(default 100 000). The call loops until the table is clean, so a large table never runs one giant statement.- On an attached instance the delete runs on the server; inside
db.transaction(…)it joins the transaction and rolls back with it. - The timer is unref'd (a cleanup job never keeps the process alive), and a run is skipped while a
transaction is open. Failures go to
onError— or the instance'sonError— and the timer keeps going.
Data tables (JSON documents)
The canonical shape: two columns, data (JSON) and ts (TIMESTAMP). db.table(name) returns a
handle and creates the table in the background when it is missing — ingest() waits for that creation.
A call can lower the batch size: db.ingest({ table, rows, insertBatchSize: 1 }) writes one row per
statement. That is the safe setting for a FLOAT[N] column, where a multi-row INSERT built from constant
vectors is the shape DuckDB's engine is most likely to reject. The table handle takes the same option:
tickets.ingest(docs, { insertBatchSize: 1 }).
const tickets = await db.table("tickets", { ts: "createdAt" }); // ts ← data.createdAt
await tickets.ingest([
{ ref: "A-1", total: 42, createdAt: "2026-10-01T08:30:00Z" },
{ ref: "A-2", total: 7 }, // no createdAt → now()
]);
await tickets.flush();
const { rows } = await db.exec(`
SELECT ts, data->>'ref' AS ref, CAST(data->>'total' AS DOUBLE) AS total
FROM tickets ORDER BY ts
`);Backpressure and shutdown
The queue is bounded: past maxQueuedBatches queued calls (default 64), ingest() waits for room
instead of returning immediately. Without that cap, a producer faster than the engine grows the process until
it is killed — the rows live in JS until they are written. ingest() therefore stops being instant exactly
when the engine is behind, which is the point; pendingWrites is the current depth:
const db = new DuckdbQuackInstance({ maxQueuedBatches: 64 }); // 0 = unbounded
for await (const page of pages()) {
await db.ingest({ table: "events", rows: page }); // waits when the queue is full
}
await db.flush(); // everything landed, or the first failure is thrown
await db.close(); // bounded: 30 s by default, then interrupt + DUCKDB_FLUSH_TIMEOUTclose() never hangs on a dead socket: past closeTimeoutMs (30_000, or close({ timeoutMs })) it
interrupts the running statement and throws DUCKDB_FLUSH_TIMEOUT after releasing the instance — the rows
still queued did not land, and the caller is told. A batch that legitimately needs longer is a flush()
first, then close().
Appender ingest (local only)
ingest({ table, rows, appender: true }) writes through DuckDB's Appender instead of
building one INSERT per batch — faster for a bulk load into the local instance (and the
server's own tables):
await db.ingest({ table: "events", rows, appender: true });- Local only. Quack cannot carry an appender over the wire: an attached instance refuses
with
DUCKDB_APPENDER_REMOTE, and an opendb.transaction(…)refuses withDUCKDB_APPENDER_IN_TRANSACTION. - Values are appended by column type (
appendInteger,appendBoolean,appendBigInt,appendTimestamp,appendVarcharfor VARCHAR and JSON). ATIMESTAMPaccepts aDateor a'YYYY-MM-DD HH:MM:SS'string. - The types are checked before the first row: nested lists,
FLOAT[N],DATE,DECIMAL… are refused withDUCKDB_APPENDER_UNSUPPORTED_TYPErather than written wrong. flush(),insertBatchSize-style batching do not apply (the appender streams rows itself);stats.writtencounts them like the SQL path.
Streaming a big result
exec() builds one array of every row: a SELECT * over millions of rows is an OOM waiting for a place to
happen. stream() reads the same statement one wire chunk at a time and yields it:
for await (const batch of db.stream("SELECT id, data FROM events")) {
for (const row of batch.rows) await sink.write(row); // ~2048 rows, then freed
}- On an attached instance the statement still runs on the server (
quack_query_by_name); only the result is consumed in chunks. NoLIMIT/OFFSETpagination, one remote execution. - Each batch is a
DuckdbBatch:{ index, columns, types, rows }. batch.rowscarry native values (aBIGINTis abigint, aTIMESTAMPaDuckDBTimestampValue) — no JSON conversion, unlikeexec(). Convert in your loop if you need JSON-safe rows.breakout of the loop to stop early, or pass{ signal }: the native result is closed either way, releasing the connection.- The counters
stats.rowsinclude what a stream read, even when it stopped early.
Client pool
One DuckdbQuackInstance is one Quack session. Opening one per request is exactly how a deployment reaches
quack_server_max_connections (1024) and starts refusing clients with an opaque IO error — so the package
ships a bounded pool:
import { DuckdbQuackPool } from "@anteros/duckdb";
const pool = new DuckdbQuackPool({ url, token, size: 4 });
const { rows } = await pool.exec("SELECT count(*) AS n FROM tickets");
await pool.withClient(async (db) => {
await db.ingest({ table: "events", rows });
await db.flush();
});
console.log(pool.created, pool.idle, pool.waiting); // never above `size`
await pool.close();withClient()returns the client even when the callback throws; callers pastsizewait instead of opening a new session.- A client whose attachment was invalidated is re-attached before it goes back to the pool; one that is closed or cannot re-attach is dropped and replaced on the next call.
- The pool does not retry the failed call: the error reaches you, with the client already made usable.
- Never close a borrowed client.
await db.close()insidewithClientis a caller mistake — the pool notices the dead handle, drops it, and builds a replacement for the next caller (covered by a test). - A pool needs a
url. Without one, the constructor throwsDuckdbQuackErrorwithDUCKDB_POOL_REMOTE_REQUIRED: it would otherwise opensizeindependent local databases, each with its own memory catalog, instead ofsizeclients of one database.
new DuckdbQuackPool({ size: 4 }); // throws: DUCKDB_POOL_REMOTE_REQUIREDCRUD on the matching documents — the where predicate is mandatory: a non-empty SQL string. Omitted, blank,
or not a string (undefined, an array…) → DUCKDB_WHERE_REQUIRED, because an update without one would
patch every row.
await tickets.update("data->>'ref' = 'A-1'", { total: 43 }); // { table, updated }
await tickets.replace("data->>'ref' = 'A-2'", { ref: "A-2" }); // { table, replaced }
await tickets.delete("data->>'ref' = 'A-2'"); // { table, deleted }
// Or from the instance, without holding the handle:
await db.update({ table: "tickets", where: "data->>'ref' = 'A-1'", set: { total: 44 } });
await db.replace({ table: "tickets", where: "data->>'ref' = 'A-2'", set: { ref: "A-2" } });
await db.delete({ table: "tickets", where: "data->>'ref' = 'A-2'" });
// Upsert: insert `set` when nothing matches — returns { table, updated: 0, inserted: 1 }
await db.update({
table: "tickets",
where: "data->>'ref' = 'A-3'",
set: { ref: "A-3", total: 7 },
upsert: true,
});upsert inserts set as the whole document, with ts = now(). There is no key column and no
unique constraint: include the identifying fields in set, and serialise concurrent upserts (a
transaction, or one writer) when duplicates would matter.
update, replace and delete also take an array, run in order, returning results in the same order.
The batch is atomic — it opens a transaction, or joins the one you already have:
await db.update([
{ table: "tickets", where: "data->>'ref' = 'A-1'", set: { total: 43 } },
{ table: "tickets", where: "data->>'ref' = 'A-2'", set: { ref: "A-2", total: 7 }, upsert: true },
]); // → [{ table, updated: 1 }, { table, updated: 0, inserted: 1 }]
await db.replace([
{ table: "tickets", where: "data->>'ref' = 'A-1'", set: { ref: "A-1", total: 50 } },
]);
await db.delete([
{ table: "tickets", where: "data->>'ref' = 'A-3'" },
]);One failing entry rolls the whole batch back; an empty array returns [].
| Element | What it does |
| --- | --- |
| db.table(name, { ts }) | A handle; the table (data JSON, ts TIMESTAMP) is created in the background if missing |
| table.ready() | Waits for that creation |
| table.ingest(documents, { ts }) | Queues documents — one row each: data = the object, ts = the mapped field or the ingestion time |
| table.update(where, patch) | Patches matching documents (json_merge_patch) — where mandatory, server-side |
| table.replace(where, document) | Replaces matching documents entirely — where mandatory, server-side |
| table.delete(where) | Deletes matching documents — where mandatory, server-side |
| table.flush() | Waits for the queued writes |
ts is mapped from a document field ({ ts: "createdAt" }, or per ingest call); a Date, an epoch number
or an ISO string is accepted, and anything unreadable falls back to the ingestion time. A table that already
exists with another shape is refused (DUCKDB_TABLE_SHAPE_INVALID) rather than written into blindly.
Declared tables (startup schema)
The tables an instance must have can be declared at initialization, with their fields:
const db = new DuckdbQuackInstance({
url: "quack:127.0.0.1:9494",
token: process.env.QUACK_TOKEN,
tables: [
{ name: "tickets", fields: [
{ name: "prix", type: "DOUBLE" },
{ name: "libelle", type: "string" },
] },
],
});When the instance opens, the declaration is reconciled in the background — syncSchema() waits for it and
returns what changed:
| Situation | What happens |
| --- | --- |
| table missing | created with the declared fields |
| a declared field is missing | added (ALTER TABLE … ADD COLUMN) |
| a declared type differs | changed (ALTER TABLE … ALTER COLUMN … SET DATA TYPE) |
| a column the declaration does not name | never dropped — carried over untouched |
const report = await db.syncSchema();
// { tables: [{ table: "tickets", created: false, added: ["zone"], retyped: ["prix"] }] }A failure in the background goes to onError, not to the next query. required/primaryKey only apply when
the table is created: a column added to an existing table cannot be NOT NULL without a default.
⚠️ Quack does not implement
ALTER TABLEon an attached catalog (Not implemented Error: Alter not implemented yet). On a remote, the migration is a rebuild: the rows are copied into a temp table, the table recreated with the reconciled schema, then the rows copied back — unknown columns included. It is a startup reconciliation, not an online migration: it is not atomic, and the rows travel through the client. A copy is kept while it runs — if the rebuild fails after the drop, the original table is restored from it. On a local instance (server.db), the migration is an in-placeALTER TABLE.
Full-text search
DuckDB's fts extension is wrapped by three
methods. It is autoloaded on first use; the index lives in a schema named fts_<catalog>_<table>
(fts_main_documents for documents).
await db.createFtsIndex("documents", {
id: "document_identifier", // the id column
fields: ["text_content", "author"], // a name, a list, or "*" for every VARCHAR
stemmer: "english", // porter by default
incremental: true, // keep it current; id must be NOT NULL / PRIMARY KEY
});
const { rows } = await db.searchFts("documents", "small cats", {
id: "document_identifier", // the column, not its name as a string
fields: "text_content", // default: every indexed field
limit: 10,
});
// rows: [{ document_identifier, text_content, …, score }]
await db.dropFtsIndex("documents");| Option (createFtsIndex) | Default | What it does |
| ---------------------------------------- | -------------------------- | ------------------------------------------------------------------- |
| id | — | Document identifier column |
| fields | — | One name, string[], or '*' for every VARCHAR column |
| stemmer / stopwords / ignore | porter / english / … | Tokenisation — see the extension's reference |
| stripAccents / lower | true | Normalise before indexing |
| overwrite | true | true rebuilds; false keeps an existing index (creates only when missing) |
| incremental | false | Triggers keep it current; id must be NOT NULL / PRIMARY KEY |
searchFts adds fields (a name, a list, or a comma-separated string), k (1.2), b (0.75),
conjunctive, where (a raw SQL predicate — never pass untrusted input), select (an array of
returned columns, default *) and limit (default 100; 0 disables the cap). score is the BM25
score, best match first.
Three options are easy to confuse: id is the index's join key — pass the same column as
createFtsIndex, it is not a filter; fields narrows the search to some indexed columns; select only
narrows the returned columns. An id that does not match the index yields no rows; a fields entry that
was not indexed throws DUCKDB_FTS_FIELD_UNKNOWN (the method checks the index's own field list).
On an attached instance, createFtsIndex and searchFts run on the Quack server — the index and its
macro live where the table is. Use the server-side table name (unqualified or schema.table); the client
alias (quack.table) is accepted and stripped.
A server can build indexes before it opens the port:
new DuckdbQuackServer({
token: process.env.QUACK_TOKEN!,
dbPath: "./data/docs.duckdb",
ftsIndexes: [
// `overwrite: false` keeps the index across restarts; omit it to rebuild.
{ table: "documents", id: "document_identifier", fields: ["text_content", "author"], overwrite: false },
],
});⚠️ Without
incremental: true, the index does not follow inserts/deletes — recreate it after a batch (createFtsIndexdefaults tooverwrite: true), or useincrementalwith aNOT NULL/PRIMARY KEYid.
Worked example
await db.createTable("documents", [
{ name: "id", type: "string", primaryKey: true },
{ name: "title", type: "string" },
{ name: "body", type: "string" },
{ name: "author", type: "string" },
{ name: "category", type: "string" },
]);
await db.ingest({
table: "documents",
rows: [
{ id: "d1", title: "The cat", body: "The cat is a small carnivorous mammal.", author: "Alice", category: "animals" },
{ id: "d2", title: "Domestic cats", body: "Domestic cats sleep a lot.", author: "Bob", category: "animals" },
{ id: "d3", title: "The mallard", body: "The mallard is a migratory duck.", author: "Alice", category: "animals" },
{ id: "d4", title: "Filter coffee", body: "A recipe for filter coffee and green tea.", author: "Chloe", category: "food" },
],
});
await db.flush();
await db.createFtsIndex("documents", {
id: "id",
fields: ["title", "body", "author"],
stemmer: "english",
incremental: true,
});
// Stemming matches "cat" and "cats".
const byText = await db.searchFts("documents", "cats", { id: "id", limit: 5 });
// d1 The cat · d2 Domestic cats
// One field only, plus an extra SQL predicate.
const byAuthor = await db.searchFts("documents", "Alice", {
id: "id",
fields: "author",
where: "category = 'animals'",
select: ["id", "title", "author"],
});
// d1 The cat · d3 The mallard
// Every term must be present.
const conjunctive = await db.searchFts("documents", "migratory duck", { id: "id", conjunctive: true });
// d3 The mallardBecause the index is incremental, a row ingested afterwards is searchable without rebuilding:
await db.ingest({
table: "documents",
rows: [{ id: "d5", title: "The swan", body: "The swan is an aquatic bird.", author: "Alice", category: "animals" }],
});
await db.flush();
const swan = await db.searchFts("documents", "swan", { id: "id" });
// d5 The swanSearch from SQL
The wrapper is optional: the macro is a normal DuckDB function. match_bm25 takes the id column (not its
name as a string), and the index lives in fts_main_<table>:
SELECT document_identifier, text_content, score
FROM (
SELECT *, fts_main_documents.match_bm25(document_identifier, 'small cats') AS score
FROM documents
) sq
WHERE score IS NOT NULL
ORDER BY score DESC
LIMIT 10;Vector similarity search
DuckDB's vss extension adds HNSW indexes on fixed-size
FLOAT[N] columns. Unlike fts, it is not autoloaded: createVssIndex / searchVss run LOAD vss
(installing it on first use) on the instance — on the Quack server when attached.
await db.createTable("embeddings", [
{ name: "id", type: "string", primaryKey: true },
{ name: "label", type: "string" },
{ name: "vec", type: "FLOAT[3]" },
]);
await db.ingest({
table: "embeddings",
rows: [
{ id: "e1", label: "cat", vec: [1, 0, 0] },
{ id: "e2", label: "dog", vec: [0, 1, 0] },
{ id: "e3", label: "bird", vec: [0, 0, 1] },
{ id: "e4", label: "kitten", vec: [0.9, 0.1, 0] },
],
});
await db.flush();
await db.createVssIndex("embeddings", { column: "vec", metric: "cosine" });
const { rows } = await db.searchVss("embeddings", [1, 0, 0], {
column: "vec", // the FLOAT[N] column
metric: "cosine", // must match the index to accelerate
select: ["id", "label"],
limit: 3, // default: 10
});
// e1 cat (0) · e4 kitten (0.006) · e2 dog (1)
await db.dropVssIndex("embeddings", { column: "vec" });| Option (createVssIndex) | Default | What it does |
| ------------------------------- | ------------------------ | ------------------------------------------------------------------ |
| column | — | FLOAT[N] column to index |
| metric | 'l2sq' | 'l2sq', 'cosine' or 'ip' |
| efConstruction / efSearch | 128 / 64 | HNSW construction/search candidate count |
| m / m0 | 16 / 2 * M | Graph connectivity (per level / level 0) |
| name | vss_<table>_<column> | Index name |
| overwrite | true | Drop and recreate an existing index |
| persist | false | Enable experimental persistence — required for a file database |
| metric | Distance function | Meaning |
| -------- | -------------------------------- | -------------------------- |
| l2sq | array_distance | Squared L2 (Euclidean) |
| cosine | array_cosine_distance | Cosine distance |
| ip | array_negative_inner_product | Negative inner product |
searchVss(table, vector, { column, metric, limit, select, where }) returns the nearest rows with a
distance column, closest first. select is an array of columns (default *); where is raw SQL
(trusted input only); limit defaults to 10 and must be greater than 0. The HNSW index accelerates the
ORDER BY <distance>(col, constant) LIMIT n shape — a where predicate may make the planner fall back to a
scan. Check with EXPLAIN: the plan shows Hnsw Index Scan.
Experimental persistence is enabled by default (hnsw_enable_experimental_persistence): a file
database accepts HNSW indexes, and a persisted index stays writable after a restart, without any option. It
must be set when the database is opened — loading vss later on a file that already holds such an index
hangs (DuckDB 2.0.0-r.1), which is why the wrapper sets it at creation.
new DuckdbQuackServer({
token: process.env.QUACK_TOKEN!,
dbPath: "./data/vecs.duckdb",
vssIndexes: [
{ table: "embeddings", column: "vec", metric: "cosine" },
],
});Opt out only deliberately: settings: { hnsw_enable_experimental_persistence: false }. A persisted index then
cannot be bound, and writes fail with DUCKDB_VSS_INDEX_NOT_LOADED ("unknown index type 'HNSW'"). DuckDB marks
the persistence as experimental — WAL recovery is not implemented for custom indexes.
Search vectors from SQL
The distance functions are core DuckDB; only the index needs vss:
SELECT id, label, array_cosine_distance(vec, CAST([1, 0, 0] AS FLOAT[3])) AS distance
FROM embeddings
ORDER BY array_cosine_distance(vec, CAST([1, 0, 0] AS FLOAT[3]))
LIMIT 3;Embeddings from Transformers.js
@xenova/transformers runs the model locally (ONNX). Its output is a Float32Array; convert it with
output.tolist() — a Float32Array would be serialised as JSON by ingest instead of being a vector. Build
the column from the model's dimension:
import { pipeline } from "@xenova/transformers";
const embedder = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
const embed = async (texts: string[]) =>
(await embedder(texts, { pooling: "mean", normalize: true })).tolist();
const texts = ["The cat is a small mammal.", "The mallard is a migratory duck."];
const vectors = await embed(texts);
await db.createTable("documents", [
{ name: "id", type: "string", primaryKey: true },
{ name: "text", type: "string" },
{ name: "vec", type: `FLOAT[${vectors[0]!.length}]` },
]);
await db.ingest({
table: "documents",
rows: texts.map((text, index) => ({ id: `d${index + 1}`, text, vec: vectors[index] })),
});
await db.flush();
await db.createVssIndex("documents", { column: "vec", metric: "cosine" });
const [queryVector] = await embed(["A migratory bird"]);
const { rows } = await db.searchVss("documents", queryVector, {
column: "vec",
metric: "cosine",
limit: 3,
});Common dimensions: all-MiniLM-L6-v2 and paraphrase-multilingual-MiniLM-L12-v2 → 384;
bge-base-en-v1.5 and all-mpnet-base-v2 → 768. Use the same model, pooling and normalization for documents
and queries; changing the model means a new FLOAT[N] column and a rebuilt index. For French, prefer the
multilingual models (paraphrase-multilingual-MiniLM-L12-v2, multilingual-e5-small — the latter expects
query: / passage: prefixes).
Serving — the server side
DuckdbQuackServer is the other half: a DuckDB instance that accepts clients over the protocol, on a port, behind a token.
import { DuckdbQuackServer } from "@anteros/duckdb";
const server = new DuckdbQuackServer({
port: 9494, // default: 9494
host: "127.0.0.1", // default: localhost
token: process.env.QUACK_TOKEN!, // required, at least 4 characters
dbPath: "./data/analytics.duckdb", // ← the only place the data is saved (omit → in memory)
allowOtherHostname: false, // true to accept a non-localhost Host header
// disableSsl: true, // true = plain HTTP, false = forced TLS, omitted = Quack's default
targetBatchBytes: 33_554_432, // quack_target_batch_bytes (32 MiB, Quack's default)
// sslCertFile: "./certs/server.pem", // TLS pair; omitted → Quack generates a self-signed one
// sslKeyFile: "./certs/private_key.pem",
settings: { threads: 4 },
debug: true, // every operation and failure → console.debug / console.error
maxQueuedBatches: 64, // backpressure of the server's own writes
// closeTimeoutMs: 30_000, // stop() gives up on a stuck write after this
healthPort: 9495, // GET / → 200/503, for a load balancer or k8s
// backup: { directory: "./backups", every: "6h", keep: 14, onStart: true }, // scheduled snapshots (see Backups)
rebuildIndexesOnStart: ["hnsw"], // replay every HNSW index before the port opens
beforeStart: async (db) => { // maintenance on the served database, before any client
await db.purge({ table: "events", column: "ts", ttl: "30d" });
},
// beforeStartTimeoutMs: 30_000, // past it: DUCKDB_QUACK_BEFORE_START_TIMEOUT
onReady: async (server) => { // awaited before start() resolves
console.log(`serving on ${server.listenUri}`);
},
// afterStart: (server) => metrics.announce(server.listenUri), // after start(), not awaited
});
// `start()` keeps the **Bun process alive** while serving: the Quack listener is
// a native thread, invisible to the event loop, so a plain script would exit as
// soon as `start()` resolved. `stop()` releases the timer.
// Ctrl-C and SIGTERM then run `quack_stop` and unlock a `dbPath`:
const dispose = server.handleSignals(); // ["SIGINT", "SIGTERM"], one pair of listeners
await server.start(); // CALL quack_serve(…), idempotent
// The server owns the data, and builds it with the very same methods:
await server.db.createTable("orders");
await server.db.ingest({ table: "orders", rows: [{ data: { ref: "A-1" } }] });
await server.db.flush();
await server.backup(); // one snapshot now, through the served instance
console.log(server.listenUri); // quack:127.0.0.1:9494 — what clients attach
console.log(server.listenUrl); // http://127.0.0.1:9494 — what quack_serve bound
await server.stop(); // CALL quack_stop(…), then closes the instance
dispose(); // removes the signal listenersRefused at construction
Four options are validated at construction, so a typo fails immediately instead of at start() — or binds
the wrong socket:
| Option | Refused when | Error |
| --- | --- | --- |
| port | not an integer in 1–65535 | DUCKDB_QUACK_PORT_INVALID |
| healthPort | not an integer in 1–65535, or equal to the Quack port (9494 by default) | DUCKDB_QUACK_HEALTH_PORT_INVALID |
| beforeStartTimeoutMs | not a finite number greater than zero | DUCKDB_QUACK_OPTION_INVALID |
| backup | directory missing, every not a positive duration, keep not a non-negative integer, unknown format, or format: "file" without dbPath | DUCKDB_BACKUP_INVALID |
healthPort must differ from port: the readiness endpoint would otherwise compete with the Quack listener
for the same socket. backup follows the same rule — a schedule that cannot run is refused before the
database is even opened, rather than failing on its first tick; format: "file" needs a dbPath to clone.
A refusal is a DuckdbQuackError thrown before anything is opened — no file, no port, nothing to clean up.
Startup hooks and index recovery
Around a start, the order is: settings → rebuildIndexesOnStart → beforeStart → declared
ftsIndexes/vssIndexes → the Quack listener and healthPort → onReady → start() resolves →
afterStart. Everything up to onReady runs inside start(), so a caller that awaits it either gets a
server that is already serving, or an error.
const server = new DuckdbQuackServer({
token: process.env.QUACK_TOKEN!,
dbPath: "./data/analytics.duckdb",
rebuildIndexesOnStart: ["hnsw"], // replay every HNSW index found in the catalog
beforeStart: async (db) => { // `db` is `server.db` — the database clients will see
await db.purge({ table: "events", column: "ts", ttl: "90d" });
await db.exec("CHECKPOINT");
},
beforeStartTimeoutMs: 60_000, // default 30_000
});beforeStart(db)runs once the settings are applied and the index rebuild has run, and before any listener is open — maintenance with no client watching: a migration, a purge, an index build.dbis the instance being served (server.db). A throw fails the start withDUCKDB_QUACK_BEFORE_START_FAILED.beforeStartTimeoutMs(default30_000) bounds that hook: past it the start fails withDUCKDB_QUACK_BEFORE_START_TIMEOUT. Both are aDuckdbQuackError, and a failed start releases what it opened — the nextstart()builds a fresh one (see Lifecycle and liveness).rebuildIndexesOnStarttakes an array of index kinds —RebuildIndexKind,"hnsw"for now:["hnsw"]. For"hnsw"the server readsSELECT index_name, sql FROM duckdb_indexes(), keeps the secondary indexes whose stored SQL matches/USING\s+HNSW/i, runsLOAD vss(best effort) and replays each one asDROP INDEX IF EXISTS <name>; <sql>. It runs beforebeforeStart, and a failure fails the start withDUCKDB_QUACK_REBUILD_FAILED. A kind the package does not know — or a bare"hnsw"/true, the former scalar forms — is refused at construction withDUCKDB_QUACK_REBUILD_INVALID, before anything is opened. The array is what leaves room for the next kind ("fts", say) without changing the option's type — the kind is the exportedRebuildIndexKindtype. It is for the restart: HNSW persistence is experimental and DuckDB does not replay a custom index's changes through WAL recovery, so a file that comes back from an unclean stop can answer from a stale graph. Rebuilding from the index's own SQL in the catalog makes it match the rows again, with no index declaration to keep in sync with the code that created it.onReady(server)runs once the listener and the optionalhealthPortare up, and is awaited insidestart(): warm a cache, register the URI, make the start fail loudly when the node cannot really serve. A throw fails the start withDUCKDB_QUACK_READY_FAILED, and what was opened is released.afterStart(server)is invoked afterstart()resolved — scheduled, never awaited: metrics, a log line, a background job that must not delay readiness. Its errors go toonError; the server keeps serving.
onReady: async (server) => { await warmCaches(server.db); }, // awaited — a failure fails the start
afterStart: (server) => metrics.announce(server.listenUri), // not awaited — readiness is already onWhere the data is saved
Quack has no storage option of its own: the server is a DuckDB database, and whatever is in it is what clients see over the protocol. So the answer is one line of configuration:
| dbPath | Where the data lives | Survives a restart |
| --- | --- | --- |
| omitted | in memory | no — the tables serve every attached client for the lifetime of the process, then die with it |
| set | a DuckDB file | yes — the file is the database; backup() it while serving (see Backups), and stop() releases the lock |
dbPath may point into a folder that does not exist yet: the directory is created on connect
(mkdir -p semantics), for the server and for a local DuckdbQuackInstance alike.
This is the one place a DuckDB file is the right answer: a Quack server is a single process owning its database, so the cross-process lock that rules a file out for per-worker instances cannot happen — that is exactly the architecture Quack exists to allow (one writer, N readers).
The token is at least 4 characters (Quack's rule, checked at construction), and a non-loopback
hostis not enough to accept a remote client: Quack checks theHostheader and refuses anything but localhost unlessallowOtherHostnameis set. A server meant to be reached sets both — and then the token (and TLS) is all that stands between the network and the data.
Backups
backup() takes a consistent snapshot of the database while it keeps serving — no stop(), no copying a
file whose WAL is still open:
// The served instance: one snapshot, now.
const snapshot = await server.db.backup({ directory: "./backups", keep: 7 });
// { path: "./backups/analytics-20261101T143000Z.duckdb", format: "file", at: … }
// A portable dump instead of a file copy.
const dump = await server.db.backup({ directory: "./backups", format: "export" });A client instance that is attached (url set) refuses with DUCKDB_BACKUP_REMOTE: the database to back up
is the server's own file, so the call belongs on the server side (server.db).
The result is { path, format, at } — where the snapshot landed, the format used, and when it was taken.
directory is created when missing (mkdir -p semantics), as for dbPath.
| format | What lands in directory | When |
| --- | --- | --- |
| 'file' (default) | <stem>-<stamp>.duckdb — a hot clone: ATTACH the target, COPY FROM DATABASE, DETACH | The database is a dbPath file; without one the call is refused (DUCKDB_BACKUP_REQUIRES_DBPATH) |
| 'export' | <stem>-<stamp>.export/ — schema.sql, load.sql and one .parquet per table (EXPORT DATABASE … (FORMAT PARQUET)) | A dump to read with another DuckDB, another version or any Parquet tool — and the only format an in-memory instance can produce |
- Naming.
<stem>is thedbPathbasename without its.duckdbextension, the stamp UTCYYYYMMDDTHHmmssZ(analytics-20261101T143000Z.duckdb); an in-memory instance exports asmemory-<stamp>.export. The stamp sorts, so the newest snapshot is the last name. - A clone is a database. Open it with
new DuckdbQuackInstance({ dbPath: snapshot.path })— there is nothing to convert. To put it back in place instead,antd restoredoes the swap (see TheantdCLI). - Rotation.
keep(default 7,0= keep everything) bounds the directory: after a successful snapshot, the entries matching<stem>-and the format's suffix (.duckdb, or a.exportdirectory) are deleted beyond the newestkeep. Anexportdoes not count thefileclones, and the other way round. A rotation that fails does not fail the snapshot it followed (debugreports it). - Consistency. The clone is written by the engine (
COPY FROM DATABASE), so it is a transaction-consistent copy of a live database — no committed change is left behind in a.wal, and nocpof a running server's file can offer that (see Storage and files). - Failure leaves nothing behind. A failed clone detaches the target (best effort), deletes the partial
file (or
.exportdirectory) and throwsDUCKDB_BACKUP_FAILED; the server keeps serving, and an existing snapshot is untouched. - No interleaving. Two
backup()calls on one instance are serialised — each waits for the previous one, since they share the connection.
Restoring is antd restore, one form per format: a clone is swapped over the target file, an .export
directory is replayed into it with IMPORT DATABASE. The target's folder is created if missing, and an
existing target is only replaced with --force — moved aside as <dbPath>.bak-<stamp>, never deleted:
antd restore --backup ./backups/app-20261101T134500Z.duckdb --dbPath ./data/app.duckdb --force
antd restore --backup ./backups/app-20261101T134500Z.export --dbPath ./data/app.duckdb --forceThe types are DuckdbBackupOptions, DuckdbBackupResult, DuckdbBackupFormat and, for the server option,
DuckdbBackupSchedule.
A schedule is one option on the server, and the manual call is the same with overrides:
const server = new DuckdbQuackServer({
token: process.env.QUACK_TOKEN!,
dbPath: "./data/analytics.duckdb",
backup: {
directory: "./backups", // required — created when missing
format: "file", // default; "export" for a portable dump
keep: 14, // snapshots kept; 0 = keep everything (default 7)
every: "6h", // '15m', '1h', '24h'… or milliseconds (default '1h')
onStart: true, // one snapshot as soon as the server runs (default false)
},
});
await server.backup(); // now, with the configured options
await server.backup({ format: "export" }); // overrides merge over the configurationonStarttakes the first snapshot once the server is running — afteronReady; the timer then fires everyevery(default'1h'). A tick is skipped while a snapshot is in flight, so a slow clone never stacks up.- The timer is unref'd: a backup schedule never keeps the process alive by itself.
- A failed snapshot goes to
onError(orconsole.error) and the schedule continues; what succeeded is still rotated bykeep. stop()clears the timer and awaits a scheduled snapshot already in flight (best effort — its failure is not rethrown), so a shutdown does not cut a clone in half.start()after astop()re-arms the schedule.- Without a configured
backup,server.backup({ directory })still works: the directory is required, and its absence isDUCKDB_BACKUP_INVALID.
The antd CLI
The same server, from the terminal — no code to write. bun add @anteros/duckdb installs the library and
the antd binary; without installing, bunx @anteros/duckdb start … works too.
antd start --token super-secret
antd start --dbPath ./data/analytics.duckdb --port 9494 --token super-secret
antd start --host 0.0.0.0 --allowOtherHostname --token super-secret
antd start --dbPath ./data/docs.duckdb --fts documents:document_identifier:text_content,author --token super-secret
antd start --dbPath ./data/docs.duckdb --ftsConfig ./fts.json --token super-secret
antd start --dbPath ./data/vecs.duckdb --vss embeddings:vec:cosine --token super-secret
antd restore --backup ./backups/app-20261101T134500Z.duckdb --dbPath ./data/app.duckdb --force
antd restore --backup ./backups/app-20261101T134500Z.export --dbPath ./data/app.duckdb --forceThe banner names the URI actually bound, the data source and the masked token; the process then serves until
Ctrl-C, which runs quack_stop and releases a --dbPath lock:
@anteros/duckdb — antd
mode quack
url quack:127.0.0.1:9494
db in memory (nothing is persisted)
token ******** (12 characters)| Option | Default | What it does |
| --- | --- | --- |
| --quack | on | The serving mode — the only one; --quack=false is r
