@redocly/realm-db-client

A dependency-free Hrana v3 client for the Realm DB service (apps/realm-db). It speaks POST <base>/v3/pipeline over fetch, encodes and decodes SQLite values, and hands back libsql-shaped result sets whose rows are array-like and keyed by column name. It targets Node 22+ (fetch, AbortSignal.timeout and Buffer are used directly) and ships both CommonJS and ESM builds.

import { createHranaClient } from '@redocly/realm-db-client';

const db = createHranaClient({ url: 'https://realm-db.example.com/p/my-project', authToken });
const { rows } = await db.execute({ sql: 'SELECT id, name FROM entities WHERE key = ?', args: [key] });

Rowids and change counts after a write

The service journals every write inside the same transaction as the write itself. A separate SELECT last_insert_rowid() or SELECT changes() statement sent after a write therefore reports the journal insert, not the caller's statement. Read lastInsertRowid and rowsAffected from the ResultSet of the write itself.

Retries

A 503 carrying X-Realm-Db-Retry: nothing-ran means the request never reached a database, so the client sends it again — four attempts by default, 100 ms doubling, configurable through retry. A connection that drops before any response header is retried only for a baton-less SELECT; a plain 5xx and anything sent on a transaction's baton are surfaced to the caller as a RealmDbError, whose retryable flag says whether sending it again is safe.