Skip to main content

Getting started

This page shows the fastest path to connect to a running LioranDB server from Node.js using the JS/TS driver (@liorandb/driver).

1) Run a server​

Install the server package and start it:

npm i -g @liorandb/db
ldb-serve

By default the server listens on http://localhost:4000.

2) Install the driver​

npm i @liorandb/driver

Looking for the Python driver? Go to Driver (Python: liorandb-driver) -> Getting started.

3) Connect and use a collection​

import { LioranClient } from "@liorandb/driver";

const client = new LioranClient("lioran://admin:admin@localhost:4000");
await client.connect();

const db = await client.db("default");
const items = db.collection<{ _id?: string; sku: string; qty: number }>("items");

await items.insertOne({ sku: "A", qty: 1 });
console.log(await items.findOne({ sku: "A" }));

Connection URIs (what connect() does)​

connect() behaves differently depending on the URI:

  • lioran://username:password@host:port → logs in and stores a JWT token
  • liorans://username:password@host:port → same as lioran://, but uses HTTPS
  • liorandb://dbUsername:dbPassword@host[:port]/databaseName → uses database-scoped connection-string mode
  • liorandbs://dbUsername:dbPassword@host[:port]/databaseName → same as liorandb://, but uses HTTPS
  • http(s)://host:port → does not auto-login (call login() / superAdminLogin() or setToken() / setConnectionString())

If you pass :443 with lioran://...:443, the driver auto-upgrades the protocol to HTTPS for backward compatibility.

What you get (high level)​

  • client.* methods: server management and auth helpers (requires auth)
  • await client.db(name): returns a DB wrapper
  • db.collection(name): returns a Collection<T> wrapper calling HTTP endpoints

Integrations (Next.js / NestJS / Express)​

If you’re using a framework, prefer creating one LioranClient in a dedicated module/provider and importing/injecting it everywhere (instead of creating a new client per request):

  • Next.js: Driver -> Integrations -> Next.js
  • NestJS: Driver -> Integrations -> NestJS
  • Express: Driver -> Integrations -> Express.js

Core-style API (optional): LioranManager​

If you prefer the embedded/core "manager -> db -> collection" shape, the driver also exports a remote-compatible LioranManager facade:

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

const manager = new LioranManager("lioran://admin:admin@localhost:4000");
await manager.connect();

const db = await manager.db("default");
const items = db.collection("items");
console.log(await items.findOne({ sku: "A" }));