npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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) and DuckdbQuackServer (the server)
  • Attaching a server makes it the default catalog: unqualified events is the server's table, and the client's own memory catalog stays reachable as memory.<table>
  • Data tables: db.table("tickets") → data (JSON) + ts (TIMESTAMP), ts mapping 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 an EXPORT DATABASE dump, on demand or on a timer — and antd restore puts 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-api 2.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/duckdb

Quack 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 default

The 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.

  • CONNECT does 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, and CONNECT buys nothing there.
  • The workspace stays usable. With USE, db.raw() is still the client's own catalog (memory.orders), and db.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 with USE <local>, DETACH, ATTACH; a routed session needs DISCONNECT first, and one forgotten DISCONNECT sends 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 catalog

HTTP 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-applies db, 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 exec inside db.transaction(…) is never retried: the transaction is gone, and re-attaching would silently start a new one.
  • quack_enable_reconnects only covers a dropped HTTP connection with a cached result — it cannot survive a restarted server.
  • Server side: keep dbPath on a persistent volume, stop gracefully (stop() / Ctrl-C), supervise the process. A restart is expected; the client is what re-attaches.
  • whoami() (or quack_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");
  • setVar handles 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(...) …)").
  • getVar uses getvariable() and returns null for an unset variable.
  • On an attached instance, the four methods run on the Quack server, and variables are session-scoped: they persist across exec calls without values. A statement with bound values runs in the client engine, so it reads/writes client variables instead.
  • $name is DuckDB 2.0's shorthand for getvariable('name'). Our inliner leaves a $name it was not given a value for to DuckDB, so session variables still work; unlike getvariable, an unset $name raises.
  • listVars() reads duckdb_variables(): value is text, type is 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 throws

On 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 a Date (rows older than that instant).
  • column — a DATE, TIMESTAMP, TIMESTAMPTZ or ISO-string column; it is cast to TIMESTAMP.
  • where — extra predicate, ANDed with the window ("data->>'kind' = 'log'").
  • batch — rows per DELETE (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's onError — 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_TIMEOUT

close() 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 open db.transaction(…) refuses with DUCKDB_APPENDER_IN_TRANSACTION.
  • Values are appended by column type (appendInteger, appendBoolean, appendBigInt, appendTimestamp, appendVarchar for VARCHAR and JSON). A TIMESTAMP accepts a Date or a 'YYYY-MM-DD HH:MM:SS' string.
  • The types are checked before the first row: nested lists, FLOAT[N], DATE, DECIMAL… are refused with DUCKDB_APPENDER_UNSUPPORTED_TYPE rather than written wrong.
  • flush(), insertBatchSize-style batching do not apply (the appender streams rows itself); stats.written counts 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. No LIMIT/OFFSET pagination, one remote execution.
  • Each batch is a DuckdbBatch: { index, columns, types, rows }.
  • batch.rows carry native values (a BIGINT is a bigint, a TIMESTAMP a DuckDBTimestampValue) — no JSON conversion, unlike exec(). Convert in your loop if you need JSON-safe rows.
  • break out of the loop to stop early, or pass { signal }: the native result is closed either way, releasing the connection.
  • The counters stats.rows include 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 past size wait 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() inside withClient is 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 throws DuckdbQuackError with DUCKDB_POOL_REMOTE_REQUIRED: it would otherwise open size independent local databases, each with its own memory catalog, instead of size clients of one database.
new DuckdbQuackPool({ size: 4 }); // throws: DUCKDB_POOL_REMOTE_REQUIRED

CRUD 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 TABLE on 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-place ALTER 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 (createFtsIndex defaults to overwrite: true), or use incremental with a NOT NULL / PRIMARY KEY id.

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 mallard

Because 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 swan

Search 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 listeners

Refused 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. db is the instance being served (server.db). A throw fails the start with DUCKDB_QUACK_BEFORE_START_FAILED.
  • beforeStartTimeoutMs (default 30_000) bounds that hook: past it the start fails with DUCKDB_QUACK_BEFORE_START_TIMEOUT. Both are a DuckdbQuackError, and a failed start releases what it opened — the next start() builds a fresh one (see Lifecycle and liveness).
  • rebuildIndexesOnStart takes an array of index kinds — RebuildIndexKind, "hnsw" for now: ["hnsw"]. For "hnsw" the server reads SELECT index_name, sql FROM duckdb_indexes(), keeps the secondary indexes whose stored SQL matches /USING\s+HNSW/i, runs LOAD vss (best effort) and replays each one as DROP INDEX IF EXISTS <name>; <sql>. It runs before beforeStart, and a failure fails the start with DUCKDB_QUACK_REBUILD_FAILED. A kind the package does not know — or a bare "hnsw" / true, the former scalar forms — is refused at construction with DUCKDB_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 exported RebuildIndexKind type. 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 optional healthPort are up, and is awaited inside start(): warm a cache, register the URI, make the start fail loudly when the node cannot really serve. A throw fails the start with DUCKDB_QUACK_READY_FAILED, and what was opened is released.
  • afterStart(server) is invoked after start() resolved — scheduled, never awaited: metrics, a log line, a background job that must not delay readiness. Its errors go to onError; 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 on

Where 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 host is not enough to accept a remote client: Quack checks the Host header and refuses anything but localhost unless allowOtherHostname is 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 the dbPath basename without its .duckdb extension, the stamp UTC YYYYMMDDTHHmmssZ (analytics-20261101T143000Z.duckdb); an in-memory instance exports as memory-<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 restore does the swap (see The antd CLI).
  • 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 .export directory) are deleted beyond the newest keep. An export does not count the file clones, and the other way round. A rotation that fails does not fail the snapshot it followed (debug reports 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 no cp of 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 .export directory) and throws DUCKDB_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 --force

The 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 configuration
  • onStart takes the first snapshot once the server is running — after onReady; the timer then fires every every (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 (or console.error) and the schedule continues; what succeeded is still rotated by keep.
  • 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 a stop() re-arms the schedule.
  • Without a configured backup, server.backup({ directory }) still works: the directory is required, and its absence is DUCKDB_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 --force

The 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