Skip to content

shard-db 2026.06.2

Embedded mode, native Node.js/Bun npm package, and async Promise-based query API. Wire-compatible with 2026.06.1 — no migration required.

Highlights

  • Embedded mode — link shard-db as a library into any C process. No daemon, no TCP, no OpenSSL dependency. A ShardDb handle wraps the full engine in-process.
  • npm package — shard-db on npm: native N-API addon for Node.js ≥ 18 and Bun ≥ 1. Prebuilts for linux-x64, linux-arm64, and darwin-arm64. No compilation needed on supported platforms.
  • Async query API — db.query() returns a Promise<string>. Queries run on libuv worker threads so the JS event loop is never blocked, even under heavy load.
  • Log handler callback — register a callback to receive structured log events from the engine. Covers errors, warnings, slow queries, and audit events.

Features

Embedded mode (src/db/embedded.c)

shard-db can now run entirely in-process — no daemon process, no TCP socket, no OpenSSL.

#include "embedded.h"

ShardDb *db = shard_db_open("/path/to/data");
if (!db) { /* handle error */ }

char *resp = shard_db_query(db, "{\"mode\":\"count\",\"dir\":\"d\",\"object\":\"o\"}");
free(resp);

shard_db_close(db);

The embedded API is thread-safe: multiple threads can call shard_db_query on the same handle concurrently. The full engine — B+ tree indexes, typed binary records, parallel query execution — is available in-process. TLS is excluded (-DEMBED_NO_TLS); auth token checks are bypassed (the caller owns the process).

See docs/getting-started/embedded-mode.md for the full API reference and build instructions.

Log handler callback

Register a C function to receive log events from the embedded engine:

void my_logger(int type, const char *msg, void *userdata) {
    fprintf(stderr, "%s", msg);   // msg is already formatted with timestamp + level
}

shard_db_set_log_handler(db, my_logger, NULL);
shard_db_set_log_handler(db, NULL, NULL);  // unregister

Log types: 1=error 2=warn 3=info 4=debug 5=audit 6=slow-query.

The callback fires on the thread that completed the query — always call it after shard_db_query returns, not from a background thread. The msg pointer is valid only for the duration of the callback.

npm package

Install the native addon:

npm install shard-db
# or
bun add shard-db

import ShardDb from 'shard-db'

const db = new ShardDb('/path/to/data')

const result = JSON.parse(await db.query({
  mode: 'find',
  dir: 'mydir',
  object: 'items',
  criteria: { status: 'active' },
  limit: 20
}))

db.close()

Full TypeScript types are included (index.d.ts). The QueryBody discriminated union covers all query modes with autocomplete.

See docs/getting-started/npm.md for setup, usage, and the log handler API.

Async Promise-based query API

db.query() offloads shard_db_query to a libuv worker thread via napi_create_async_work. The JS event loop stays responsive during long-running queries. Multiple concurrent await db.query(...) calls are safe — the engine's internal worker pool handles parallelism.

Log buffer drain and Promise resolution happen on the JS main thread (in the complete callback), satisfying the N-API thread-safety contract.

TypeScript QueryBody discriminated union

db.query({ mode: 'aggregate', dir: 'd', object: 'o',
           aggregates: [{ fn: 'sum', field: 'score', alias: 'total' }] })
//         ^ full autocomplete, type-checked at compile time

All query modes are covered: CRUD, bulk, find/count/aggregate, schema mutations, maintenance, catalog. Accepts a QueryBody object or a raw JSON string (backward compatible).

Bug fixes

  • C1 cursor tiebreaker — small_prefilter_cmp_asc now includes hash16 as a secondary sort key. Without it, records with identical order-field values could appear in different positions across pages, causing duplicate or skipped results on cursor pagination.
  • JSON boolean flags — true (JSON boolean) is now accepted everywhere a boolean query flag is expected. Previously only 1 (integer) was accepted; this broke clients that sent well-typed JSON.
  • total for FP_PRIMARY_LEAF + post-filter — queries using a single indexed leaf with a post-filter sibling now correctly compute total via the hint KeySet path. Previously total was omitted for this plan shape.
  • Criteria array form in npm binding — criteria accepts unknown[] (array of {field, op, value} filter objects) in addition to Record<string, unknown>. The order field is correctly named (was order_by in an earlier type revision). format: 'dict' is now exposed in the find type.

Platform support

Platform Daemon Embedded npm
Linux x86_64 ✓ ✓ ✓ prebuild
Linux ARM64 ✓ ✓ ✓ prebuild
macOS ARM64 (Apple Silicon) ✓ ✓ ✓ prebuild
Windows ✗ ✗ ✗

Windows is not supported — the engine uses POSIX APIs throughout (mmap, flock, pthreads, sem_init). macOS Intel (x86_64) is also not supported.