Build With TypeScript

Install

Install the npm package. Runtime assets and helper executables resolve through package configuration.

npm install @oliphaunt/ts

Open and query

Create a client, open a root, run SQL, and close the handle.

import { Oliphaunt } from '@oliphaunt/ts';

const db = await Oliphaunt.open({
  engine: 'nativeBroker',
  root: './app-data/main.oliphaunt',
  extensions: ['vector'],
});

const rows = await db.query('SELECT 1::text AS value');
const value = rows.getText(0, 'value');

await db.close();

Keep one client per app database root unless you intentionally use a mode that supports independent sessions.

Create app data

Use the TypeScript query helpers for app code and keep the client in a service or framework-owned dependency container:

await db.execute(`
  CREATE TABLE IF NOT EXISTS notes (
    id bigserial PRIMARY KEY,
    title text NOT NULL,
    body text NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now()
  )
`);

await db.query(
  'INSERT INTO notes (title, body) VALUES ($1, $2) RETURNING id::text AS id',
  ['First note', 'Stored in an embedded PostgreSQL root'],
);

const notes = await db.query(
  'SELECT id, title FROM notes ORDER BY id DESC LIMIT 20',
);
const firstTitle = notes.getText(0, 'title');

Tauri apps keep the database in Rust state and expose narrow app-owned commands to the webview. A direct TypeScript/webview adapter is planned, not supported in the first release.

Configure

Configure mode, root, selected exact extensions, runtime asset locations, durability, startup identity, broker helper path, and server helper path through the JS configuration object.

Choose a mode

Direct mode is lowest-latency where a native binding is available. Broker mode uses a helper process and is the preferred robust desktop JavaScript path. Server mode is for PostgreSQL-compatible tools and independent clients.

Handle lifecycle

The client queues work through the selected runtime boundary. Close rejects queued work and waits for active work. Use explicit cancellation for long SQL.

Select extensions

Select exact SQL extension names before open. Generated resources include only selected extensions and mandatory dependencies.

Back up and restore

Use SDK backup and restore helpers for physical archives and supported server flows. Keep live PostgreSQL directories behind the SDK data-movement APIs.