Skip to main content

LioranManager

LioranManager is the top-level object you create in your app. It owns:

  • the root path on disk,
  • the encryption key (optional),
  • and the set of opened databases.

Think of it as a small "embedded DB server in-process", plus (optional) IPC if you run multiple Node processes.

Constructor​

new LioranManager(options?: LioranManagerOptions)

LioranManagerOptions​

  • rootPath?: string
    Base folder where database directories are stored (one folder per DB name).
  • encryptionKey?: string | Buffer
    Enables encryption-at-rest for documents and WAL records.
  • ipc?: "primary" | "client" | "readonly" | "replica"
    Process mode for multi-process usage (see IPC).
  • cluster?: { enabled?: boolean; ... }
    Optional multi-node cluster (advanced; see Cluster).
  • cache?: { maxRAMMB?: number; ... }
    Global cache configuration (advanced).
  • cores?: number
    Overrides how many CPU cores to use for internal worker pools (advanced).
  • writeQueue?: { ... }
    Controls how the internal dedicated writer behaves under backpressure (advanced).
  • batch?: { chunkSize?: number }
    Default chunk size used by batch inserts (advanced).
  • durability?: ...
    Durability tradeoffs (advanced).
  • storage?: ...
    Storage mode tuning (advanced).
  • latency?: ...
    Latency-oriented tuning knobs (advanced).
  • background?: ...
    Background scheduler options (advanced).
  • sharding?: ...
    Partitioning/sharding options (advanced).
  • replication?: { ... }
    Replication options (advanced; see Replication).
  • slo?: { ... }
    Admission control / backpressure SLOs (advanced).
  • compute?: { enabled?: boolean }
    Enables compute/offload hooks (advanced).
  • consistency?: { reads?: ... }
    Read-consistency modes (advanced; see Consistency).
  • tenancy?: ...
    Per-tenant limits + policies (advanced; see Tenancy).
  • security?: { enabled?: boolean; authorize?: ...; audit?: ... }
    Authorization hooks + auditing (advanced; see Security).

"What does it create on disk?" (manager root)​

If rootPath is ./.liorandb and you open db("app"), you'll get:

./.liorandb/
  app/
    users/            (collection folder)
    __wal/            (write-ahead log)
    __db_meta.json    (db metadata: indexes, schemaVersion, ...)

db(name)​

db(name: string): Promise<LioranDB>
  • Opens (or reuses) a database named name.
  • In IPC client mode, returns a proxy that forwards operations to the primary process.

Example: open two DBs​

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({ rootPath: "./.liorandb" });

const appDb = await manager.db("app");
const analyticsDb = await manager.db("analytics");

await appDb.collection("users").insertOne({ email: "a@b.com" });
await analyticsDb.collection("events").insertOne({ name: "signup" });

await manager.close();
Sandbox output (example)
(no output)

snapshot(snapshotPath)​

snapshot(snapshotPath: string): Promise<true>
  • Creates a tar.gz snapshot of the manager root directory.
  • Not allowed in readonly mode.
  • In IPC client mode, the snapshot is executed by the primary process.

Example: create a snapshot​

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({ rootPath: "./.liorandb" });
await manager.db("app");

const ok = await manager.snapshot("./backups/app.tar.gz");
console.log(ok);

await manager.close();
Sandbox output (example)
true

restore(snapshotPath)​

restore(snapshotPath: string): Promise<never>
  • Restores the snapshot into the manager root directory.
  • Clears the existing root directory before restore.
  • After a successful restore, the process prints a message and exits.

Example: restore (note: process exits)​

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({ rootPath: "./.liorandb" });
await manager.restore("./backups/app.tar.gz");

// this line never runs (restore exits the process)
console.log("done");
Sandbox output (example)
Restore completed. Restart required.

close() / closeAll()​

close(): Promise<void>
  • Closes all open databases and releases the process lock (primary mode).

Example: always close in finally​

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({ rootPath: "./.liorandb" });

try {
  const db = await manager.db("app");
  await db.collection("health").insertOne({ ok: true });
} finally {
  await manager.close();
}

IPC helpers (isPrimary(), isClient(), isReadOnly())​

These are handy for logging/debugging in multi-process deployments.

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({ rootPath: "./.liorandb" });
console.log({
  primary: manager.isPrimary(),
  client: manager.isClient(),
  readonly: manager.isReadOnly(),
});
await manager.close();
Sandbox output (example)
{ primary: true, client: false, readonly: false }

Replica mode (ipc: "replica")​

ipc: "replica" is a specialized mode for read scaling where the process should not become the primary lock owner.

  • Use this when you want the process to behave as a non-writer in a replication topology.
  • Writes are rejected (similar to readonly), but replica behavior can still participate in replication flows when enabled.

If you only want “never write, never WAL”, prefer ipc: "readonly" (see IPC).

Write queue (backpressure)​

For write-heavy workloads you can tune the dedicated writer queue:

  • writeQueue.maxSize (in-memory queue length)
  • writeQueue.mode: "wait" (default) or "reject"
  • writeQueue.timeoutMs: how long to wait in "wait" mode before rejecting

Example: reject quickly under load​

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({
  rootPath: "./.liorandb",
  writeQueue: {
    maxSize: 5_000,
    mode: "reject",
    timeoutMs: 250,
  },
});

const db = await manager.db("app");
await db.collection("events").insertOne({ at: Date.now() });
await manager.close();

Batch tuning​

Batch inserts (insertMany) are written in chunks. You can set a default chunk size:

Example: default chunk size for insertMany​

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({
  rootPath: "./.liorandb",
  batch: { chunkSize: 500 },
});

const db = await manager.db("app");
await db.collection("items").insertMany([{ sku: "A" }, { sku: "B" }]);
await manager.close();

Next: advanced topics​

  • Cluster: multi-node topology (advanced)
  • Replication: leader/replica configuration (advanced)
  • Consistency: read consistency modes (advanced)
  • Tenancy: per-tenant limits (advanced)
  • Security: authz + auditing hooks (advanced)

Example: project-local root + encryption​

import { LioranManager } from "@liorandb/core";

const manager = new LioranManager({
  rootPath: "./.liorandb",
  encryptionKey: "dev-secret-change-me",
});

const db = await manager.db("app");
await db.collection("notes").insertOne({ title: "hello" });
await manager.close();
Sandbox output (example)
(no output)