Skip to main content

Databases

The driver provides both:

  • management APIs (client.*) and
  • database scoped APIs (await client.db(name))

Related pages:

  • Collections for collection-level CRUD and streaming bulk inserts
  • Schemas & migrations for schema versions and doc migration workflows

Management (LioranClient)​

Requires authentication.

listDatabases()​

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

const client = new LioranClient("http://localhost:4000");
await client.login("admin", "admin");

console.log(await client.listDatabases());

countDatabases(userId?)​

console.log(await client.countDatabases()); // all visible DBs
console.log(await client.countDatabases("admin")); // for a specific owner userId

listUserDatabases(userId)​

console.log(await client.listUserDatabases("admin"));

createDatabase(name | { name; ownerUserId? })​

console.log(await client.createDatabase("app"));
console.log(await client.createDatabase({ name: "analytics", ownerUserId: "admin" }));

dropDatabase(name)​

console.log(await client.dropDatabase("analytics"));

databaseStats(name)​

console.log(await client.databaseStats("app"));

Database wrapper (DB)​

await client.db(name) returns a DB instance with:

Collections​

collection(name)​

const db = await client.db("app");
const users = db.collection<{ _id?: string; email: string }>("users");
await users.insertOne({ email: "a@b.com" });

listCollections()​

console.log(await db.listCollections());

createCollection(name) / dropCollection(name) / renameCollection(old, next)​

console.log(await db.createCollection("items"));
console.log(await db.renameCollection("items", "inventory"));
console.log(await db.dropCollection("inventory"));

Stats and maintenance​

stats()​

console.log(await db.stats());

compactAll() / compactCollection(name)​

console.log(await db.compactCollection("users"));
console.log(await db.compactAll());

Schema versions and migrations​

The server can store a database schema version (a string) and can apply structured migrations.

getSchemaVersion() / setSchemaVersion(schemaVersion)​

console.log(await db.getSchemaVersion()); // string | null
console.log(await db.setSchemaVersion("2026-05-16"));

applyMigrations(targetVersion, migrations)​

The remote driver intentionally does not support a function-based db.migrate() API.

Use applyMigrations(...) instead:

await db.applyMigrations("v2", [
  {
    from: "v1",
    to: "v2",
    actions: [
      { type: "createIndex", collection: "users", field: "email", options: { unique: true } },
    ],
  },
]);

rotateEncryptionKey(newKey)​

If your server is configured to support it:

await db.rotateEncryptionKey("<new-key>");

Collection options (database-scoped admin APIs)​

These methods operate on a collection by name (without needing a Collection instance):

  • getCollectionOptions(collection)
  • setCollectionDateOption(collection, date)
console.log(await db.getCollectionOptions("users"));
await db.setCollectionDateOption("users", { mode: "epoch_ms" });

Indexes​

createIndex(collection, field, options?)​

console.log(await db.createIndex("users", "email", { unique: true }));

createTextIndex(collection, field, options?)​

await db.createTextIndex("posts", "title", { normalize: true });

Text search is performed via the $text query operator on collection methods like find() / findOne():

const posts = db.collection("posts");
console.log(await posts.find({ $text: { $search: "hello world" } }, { limit: 10 }));

listIndexes(collection)​

console.log(await db.listIndexes("users"));

dropIndex(collection, field)​

console.log(await db.dropIndex("users", "email"));

rebuildIndex(collection, field) / rebuildIndexes(collection)​

console.log(await db.rebuildIndex("users", "email"));
console.log(await db.rebuildIndexes("users"));

explain(collection, query?, options?)​

const explain = await db.explain("users", { email: "a@b.com" }, { limit: 1 });
console.log(explain);

Transactions​

transaction(ops[])​

await db.transaction([
  { col: "accounts", op: "updateOne", args: [{ id: "a" }, { $inc: { balance: -50 } }, { upsert: true }] },
  { col: "accounts", op: "updateOne", args: [{ id: "b" }, { $inc: { balance: 50 } }, { upsert: true }] },
]);

transaction(fn)​

await db.transaction(async (tx) => {
  await tx.collection("audit").insertOne({ at: Date.now(), event: "purchase" });
});

Database credentials (connection strings)​

getCredentials()​

console.log(await db.getCredentials());

setCredentials({ username, password })​

console.log(await db.setCredentials({ username: "app_user", password: "app_pass_123" }));

getConnectionString()​

console.log(await db.getConnectionString());