DEV Community: Swaraj Puppalwar

Meet LioranDB: A Document Database Built in Rust

Swaraj Puppalwar — Tue, 01 Sep 2026 17:25:36 +0000

Meet LioranDB: A Document Database Built in Rust

I've been working on LioranDB, a document database built in Rust with a MongoDB-style developer experience.

And now there's a video about it on YouTube:

Watch: https://www.youtube.com/watch?v=tAAOfV-HyAs

LioranDB V2 is currently in pre-alpha, so this isn't a polished "we've finished everything" announcement.

It's an invitation to developers to experiment with the database, test it, benchmark it, find strange edge cases, and preferably break things before somebody else does.

What Is LioranDB?

LioranDB is a document-oriented database designed around a familiar developer experience while building the underlying database engine in Rust.

The V2 architecture includes components such as:

B+Tree primary storage
MVCC
Write-Ahead Logging (WAL)
Crash recovery
Secondary indexes
Full-text indexing
Page caching
A query and DBMS layer
TypeScript/JavaScript driver
Docker deployment

Conceptually, an application talks to LioranDB like this:

Application
     ↓
LioranDB Driver
     ↓
LioranDB Server
     ↓
Query / DBMS Layer
     ↓
MVCC + Transactions
     ↓
Storage Engine
     ↓
B+Tree / WAL / Cache
     ↓
Disk

Why Build Another Database?

That's a fair question.

There are already excellent databases available today.

LioranDB isn't being built because the world desperately needs another CRUD API.

The interesting part for me is the infrastructure underneath it.

How do you make writes durable without destroying throughput?

How should secondary indexes interact with document storage?

How do you recover correctly after a crash?

How do you execute limit(), sorting and indexed queries without accidentally scanning or hydrating millions of unnecessary documents?

How do you maintain correctness while optimizing performance?

Those questions are where building a database gets interesting very quickly.

Sometimes an optimization gives you a beautiful benchmark.

Sometimes a tiny change takes performance from nice to what have I done.

That's part of building infrastructure.

LioranDB V2 Is Still Pre-Alpha

This part is important.

LioranDB V2 is not currently presented as production-ready.

Pre-alpha is where we're testing the architecture, fixing correctness problems, improving performance and learning from real workloads.

That also makes this one of the best times for developers interested in databases to experiment with it.

Don't just test:

insertOne(...)

Try ugly workloads.

Create indexes.

Query large collections.

Restart the database unexpectedly.

Run concurrent reads and writes.

Try unusual filters.

Push pagination.

Try to make something behave incorrectly.

If you find something broken, that's useful information.

Current Performance Target

Our pre-alpha development target has been approximately:

10,000 writes/sec
+
35,000 reads/sec
------------------
≈ 45,000 operations/sec

These are development benchmark figures, not an SLA or guaranteed production performance.

Actual throughput depends on hardware, dataset size, document structure, indexes, query patterns, concurrency and many other factors.

Performance numbers without workload context are mostly decorative numbers wearing suits.

Watch the Video

If you'd rather see LioranDB than read another wall of database text, I've published a video on YouTube:

https://www.youtube.com/watch?v=tAAOfV-HyAs

I'll continue publishing more about the internals of LioranDB, including the storage engine, indexing, WAL, MVCC, query execution, performance work and some of the bugs we've encountered while building it.

Try LioranDB

Website: https://liorandb.com

Documentation: https://docs.liorandb.com

LioranDB V2 is still evolving, so feedback at this stage genuinely matters.

If you're a backend, Rust, database or infrastructure developer, try it.

Benchmark it.

Inspect how it behaves.

And if you can break it, please tell me how you did it.

LioranDB Managed Hosting Is Now Open: ₹5,000/Month for Early-Stage Startups

Swaraj Puppalwar — Tue, 01 Sep 2026 17:20:57 +0000

LioranDB V2 is currently in pre-alpha, and we're now opening managed LioranDB deployments for selected early-stage startups and developers.

Until now, the focus has primarily been on building and testing the database itself: the Rust storage engine, B+Tree primary storage, MVCC, WAL and crash recovery, secondary indexes, full-text search, and the developer APIs around them.

Now I want to start working directly with real applications.

So instead of simply giving developers a Docker image and saying good luck, we're introducing a small managed offering with direct founder support.

Two Pricing Options

1. Fixed Plan: ₹5,000/month

This is designed primarily for early-stage products that don't need huge infrastructure yet.

The plan includes:

Up to 1 million documents
Daily database backups
Managed LioranDB deployment
Infrastructure monitoring and maintenance
Direct founder support
Basic feature requests based on your application's requirements
Help with database integration and deployment

LioranDB's current development testing has demonstrated workloads around 10K writes/sec + 35K reads/sec, or roughly 45K operations/sec under tested configurations.

These numbers should be treated as development benchmark figures, not guaranteed production throughput or an SLA. Actual performance depends heavily on hardware, indexes, query patterns, document sizes, concurrency, and workload.

LioranDB V2 itself is also currently pre-alpha, so this offering is aimed at teams comfortable adopting early infrastructure and working directly with its developer.

2. Custom Plan

Need more than 1 million documents?

Need different CPU, memory, storage, backup policies, or workload requirements?

That's where the custom plan comes in.

Instead of forcing every application into the same infrastructure configuration, we'll review your application's expected workload and determine an appropriate deployment and monthly price.

This is particularly useful for SaaS platforms, CRM systems, backend services, AI applications, and other products with unusual or rapidly growing database workloads.

How Do You Get a Managed LioranDB Database?

We're not making managed deployments instantly purchasable yet.

There is an application process.

Visit:

app.liorandb.com

Create an account and submit an application describing your product, expected workload, and database requirements.

We'll review the application.

If it's approved, we'll provision your LioranDB database and provide the information you need to connect your application.

Billing is monthly.

The process looks roughly like this:

Create Account
      ↓
Submit Application
      ↓
Application Review
      ↓
Approved
      ↓
Database Provisioned
      ↓
Connect Your Application
      ↓
Monthly Billing

Why an Application Process?

Because LioranDB V2 is still pre-alpha.

I'd rather onboard a smaller number of applications and understand exactly how they're using the database than throw open a giant "Buy Now" button and pretend the product has already reached cloud-database maturity.

Working with early users also gives us something benchmarks can't provide: real workloads.

Different applications create very different database pressure.

A CRM might perform huge numbers of indexed lookups.

A SaaS product might have strongly tenant-oriented access patterns.

An API might perform thousands of tiny reads.

Another application might continuously ingest data.

Those workloads expose problems synthetic benchmarks simply won't.

And because managed customers have direct founder support, if something strange happens, you're talking directly to the person building the database rather than bouncing through three support tiers.

What Is LioranDB?

LioranDB V2 is a document database developed in Rust with a MongoDB-style developer experience.

Its current architecture includes:

Application
     ↓
LioranDB Query Layer
     ↓
Transactions + MVCC
     ↓
B+Tree Primary Storage
     ↓
WAL + Checkpoints
     ↓
Page Cache
     ↓
Persistent Storage

     + Secondary LSM Indexes
     + Inverted Text Index

V2 pre-alpha launched on August 16, 2026, and development is currently moving toward the Alpha release planned for October 23, 2026.

The database is still under active development and is not currently presented as production-ready.

That's also why I'm particularly interested in working with developers who are willing to test it, push it, report weird behavior, and tell me where the developer experience sucks.

Interested?

You can learn about LioranDB on liorandb.com, or apply for a managed deployment through app.liorandb.com.

If you're building an early-stage SaaS, CRM, API, internal tool, or another backend-heavy product and want to experiment with LioranDB, I'd particularly like to hear about your workload.

And yes, trying to break the database is still encouraged.

LioranDB V2 Is in Pre-Alpha. Please Try to Break It.

Swaraj Puppalwar — Sat, 29 Aug 2026 19:39:12 +0000

LioranDB V2 is now publicly available in pre-alpha, and I want developers to do something slightly unusual:

Try to break it.

Not just install it, run insertOne(), see that it works, and close the terminal.

Push it.

Give it weird queries. Throw large datasets at it. Create indexes. Delete things. Restart the server. Send concurrent requests. Test edge cases. Try workflows I probably didn't think about.

If something behaves strangely, becomes painfully slow, crashes, returns an unexpected result, or simply feels bad to use, I want to know.

What is LioranDB?

LioranDB is a developer-first document database being developed in India.

V2 is written in Rust and currently includes things such as:

B+ Tree primary storage
MVCC
Write-Ahead Logging
Checkpoints and crash recovery
Secondary indexes
Full-text indexing
Docker deployment
TypeScript/JavaScript driver
MongoDB-style document APIs

The goal isn't to pretend that a pre-alpha database is already production-ready.

The goal is to find everything that's wrong with it before it gets there.

So, I'm Looking for Feedback

I'm especially interested in hearing about:

🐛 Bugs

Anything that crashes, hangs, produces incorrect results, corrupts state, or behaves differently from what you'd expect.

⚡ Performance problems

Slow queries, unexpected latency, bad scaling with larger collections, inefficient indexes, memory problems, or operations that become suspiciously expensive.

🧪 Edge cases

Strange documents. Strange queries. Strange sequences of operations.

Basically, be creative.

Databases tend to behave nicely until somebody does something the database author never imagined.

Be that somebody.

🧑‍💻 Developer experience

I'd also love feedback about the API itself.

Is something confusing?

Does an error message suck?

Is an operation unnecessarily complicated?

Did you have to read the documentation three times to understand something?

That's a bug too, just wearing nicer clothes.

How to Test It

Start here:

Documentation:
https://docs.liorandb.com

LioranDB:
https://liorandb.com

The documentation contains the setup instructions and APIs needed to start experimenting with LioranDB.

You don't need to build a serious application.

Create a test project, generate some data, connect the driver, and start attacking it.

Try things like:

thousands or millions of documents
concurrent reads and writes
secondary indexes
text search
pagination
large limit() values
unusual filters
sorting
aggregations
repeated updates and deletes
restarting LioranDB during workloads
crash/recovery scenarios
combinations of operations that look suspicious

If you manage to make LioranDB unhappy, congratulations.

That's exactly what I'm looking for.

Found Something?

Send me what happened at:

feedback@liorandb.com

If possible, include:

what you were trying to do
the query/code you ran
what you expected
what actually happened
dataset size
logs or error messages
your OS/environment
reproduction steps

Even if you're unsure whether something is technically a bug, send it.

Performance observations, confusing APIs, documentation problems, missing features, architectural criticism, and general feedback are all useful.

Why I'm Doing This

A database isn't validated because its benchmark graph looks pretty.

It's validated when people outside the project start doing things the original developer didn't anticipate.

LioranDB V2 is still pre-alpha.

There are going to be bugs.

There are going to be slow paths.

There are probably wonderfully cursed combinations of operations waiting somewhere in the engine.

I'd rather developers discover them now than users discover them later.

So install LioranDB.

Build something stupid with it.

Stress it.

Abuse the API.

And please, try to break my database.

https://liorandb.com

https://docs.liorandb.com

Feedback: feedback@liorandb.com

Swaraj's High Rise in Computers! | Nagpur Post | 23 May 2023

Swaraj Puppalwar — Mon, 24 Aug 2026 15:14:50 +0000

On Tuesday, 23 May 2023, Nagpur Post published an English feature about my early journey into computers and programming.

The article was titled “Swaraj's high rise in computers!” with the subheading “Developed many computer programs at an early age.”

I was 15 years old when the article was published.

I had started programming at the age of 11 and was primarily self-taught, learning through books, online tutorials, platforms such as Udemy and YouTube, and, most importantly, building projects.

By that point, I had experimented with software, Android applications, websites and games.

Some of my early projects included Productive Pay, a productivity tool for Python developers, a calculation-speed improvement tool for mathematics practice, and applications built while experimenting with multiple programming languages.

My early technology stack included Python, Java, C/C++, HTML, CSS, JavaScript and Node.js.

The newspaper also covered some of my participation and achievements in computer science and academic competitions, including cyber, computer and mathematics olympiads and the National Children's Science Congress.

Reading the article again years later feels almost like opening an old Git commit.

The codebase has changed considerably.

What started as curiosity about programming eventually grew into an interest in full-stack development, backend engineering, databases and developer infrastructure.

Today, I am building LioranDB and working toward a much larger goal: building developer infrastructure from India.

I am preserving this article here because it captures one of the earliest public records of that journey, from a time when I was simply a school student fascinated by what could be built with a computer and some code.

Publication: Nagpur Post
Location: Nagpur
Date: Tuesday, 23 May 2023
Original Headline: Swaraj's high rise in computers!
Subheading: Developed many computer programs at an early age

स्वराजची संगणक क्षेत्रात उंच भरारी | Navarashtra, Chandrapur | 23 May 2023

Swaraj Puppalwar — Mon, 24 Aug 2026 15:14:10 +0000

On 23 May 2023, Navarashtra featured my early journey in computer science and programming in its Chandrapur edition.

The article was published under the Marathi headline “स्वराजची संगणक क्षेत्रात उंच भरारी” on Page 4.

I was 15 years old at the time.

My journey into programming had started several years earlier, when I began learning to code at the age of 11. Instead of limiting that learning to tutorials, I became interested in actually building things.

Over the following years, I experimented with software, Android applications, websites, games and programming projects while continuing to learn different technologies.

The Navarashtra article documented this early phase of my journey and highlighted both my programming work and participation in technology and academic competitions.

Some of the technologies I explored during those years included Python, Java, C/C++, HTML, CSS, JavaScript and Node.js.

What I find interesting about looking at this article years later is how much the scale of the problems I want to solve has changed.

The 15-year-old version of me was excited about making applications and experimenting with code.

Today, I spend much of my time thinking about storage engines, databases, Rust, backend architecture and developer infrastructure.

Those are very different engineering problems, but they came from the same curiosity.

This clipping is therefore more than a newspaper mention for me. It is a snapshot of where the journey was in May 2023, long before I knew where that curiosity would eventually lead.

Publication: Navarashtra
Edition: Chandrapur
Date: 23 May 2023
Page: 4
Original Marathi Headline: स्वराजची संगणक क्षेत्रात उंच भरारी

‘स्वराज’ची संगणकात गगनभरारी | Tarun Bharat, Purva Vidarbha | 29 May 2023

Swaraj Puppalwar — Mon, 24 Aug 2026 15:13:30 +0000

On 29 May 2023, Tarun Bharat featured my journey in technology and programming in its Purva Vidarbha edition.

The Marathi article, titled “‘स्वराज’ची संगणकात गगनभरारी”, appeared on Page 2 of the newspaper.

At the time, I was 15 years old and had already spent several years exploring programming and computer science. I started programming at the age of 11, largely learning through experimentation, books, online resources and building projects of my own.

The article covered my early journey in software development, including my work with programming languages and technologies such as Python, Java, C/C++, HTML, CSS, JavaScript and Node.js.

It also highlighted some of the projects I had built while learning programming, along with my participation and achievements in computer science, cyber and mathematics competitions.

Looking back from 2026, this newspaper clipping represents a very different stage of my journey.

Back then, I was a school student experimenting with software because I genuinely enjoyed understanding how computers worked.

Today, that curiosity has evolved into working on databases, backend systems and developer infrastructure, including building LioranDB.

The technology has changed. The projects have become much larger. But the habit that started everything remains the same: learn something, build something, break it, understand it, and build again.

Publication: Tarun Bharat
Edition: Purva Vidarbha
Date: 29 May 2023
Page: 2
Original Marathi Headline: ‘स्वराज’ची संगणकात गगनभरारी

LioranDB TypeScript Series #12: Production Patterns, Error Handling and What Comes Next

Swaraj Puppalwar — Sat, 15 Aug 2026 20:16:34 +0000

LioranDB TypeScript Series #12: Production Patterns, Error Handling and What Comes Next

LioranDB TypeScript Series: Build with a developer-first document database powered by Rust and designed for TypeScript.

We started this series with:

docker run ...

Eleven articles later, we've covered application queries, indexes, authentication, operations, backups, the CLI and managed deployment.

Let's finish with the things that matter when your application stops being a demo.

Understand driver errors

The LioranDB TypeScript driver exports a structured error hierarchy.

General errors include:

LioranDriverError
ApiError
AuthError
NetworkError
TimeoutError
ConfigurationError
SerializationError

Authentication-related errors include:

AuthenticationError
AuthorizationError
PasswordChangeRequiredError
SessionExpiredError

Lifecycle errors include:

ClientClosedError
CursorClosedError
CursorInitializedError

Server-side conditions include errors such as:

ConflictError
DuplicateKeyError
NotFoundError
ServerNotReadyError
ServerOverloadedError
ServerUnavailableError
ValidationError

Use `instanceof`

Don't parse human-readable error messages.

import {
  DuplicateKeyError,
  TimeoutError,
} from "@liorandb/driver";

try {
  await users.insertOne(user);
} catch (error) {
  if (error instanceof DuplicateKeyError) {
    // Handle duplicate data.
  }

  if (error instanceof TimeoutError) {
    // Apply your timeout/retry policy.
  }

  throw error;
}

The driver also exports error and warning code constants for applications that need structured classification.

Add diagnostics

Attach your application's trace identifier:

client.setDiagnosticHeaders({
  "x-trace-id": traceId,
});

Observe operations:

client.setResponseObserver((event) => {
  console.log({
    transport: event.transport,
    operation: event.operation,
    durationMS: event.durationMS,
    requestId: event.requestId,
  });
});

And surface slow operations:

const client = await LioranDBClient.connect(uri, {
  slowRequestThresholdMS: 200,

  onWarning(warning) {
    console.warn(
      warning.code,
      warning.message
    );
  },
});

Production checklist

Before calling a deployment production-ready:

URL-encode credentials inside connection strings.
Rotate bootstrap credentials immediately.
Use application-specific users and roles.
Prefer least-privilege permissions.
Use typed collections.
Use idempotency keys where retry safety matters.
Configure appropriate request timeouts.
Poll backup and restore jobs until terminal state.
Verify backups.
Monitor health, readiness and metrics.
Keep database ports private.
Put TLS at the public edge.
Close clients and cursors cleanly.
Handle structured driver errors rather than parsing strings.

Remember: this is pre-alpha

LioranDB V2 launched its pre-alpha on 16 August 2026.

That word matters.

Pre-alpha is where APIs can evolve, edge cases get discovered and real workloads expose assumptions that benchmarks don't.

If you're experimenting with it today, feedback is extremely valuable.

What comes next?

The current target for the LioranDB V2 alpha is:

23 October 2026

Work toward alpha includes areas such as:

production hardening
larger dataset testing
richer aggregation capabilities
clustering improvements
deployment tooling
managed infrastructure
developer experience improvements

The direction remains the same:

Build developer infrastructure from India that developers can actually use.

Start building

Install the driver:

npm install @liorandb/driver@2.0.6

Install the CLI:

npm install -g @liorandb/cli@1.0.6

Run the database:

docker pull liorandb/liorandb:pre-alpha

Resources

LioranDB: https://liorandb.com
Documentation: https://docs.liorandb.com
Driver: @liorandb/driver@2.0.5
CLI: @liorandb/cli@1.0.5

LioranDB is created by Swaraj Puppalwar, Founder & CTO at Lioran Developer Solutions.

GitHub: https://github.com/UltronTheAI
Lioran Developer Solutions: https://lioransolutions.com

Previous: Part 11 → Docker Compose, Caddy & TLS

That's the end of the LioranDB TypeScript Series.

Now comes the fun part:

Build something with it, stress it, benchmark it, find the weird edge cases and tell us what you discover.

Pre-alpha gets better when developers actually try to break it. 💗

LioranDB TypeScript Series #11: Deploy LioranDB with Docker Compose, Caddy and TLS

Swaraj Puppalwar — Sat, 15 Aug 2026 20:14:45 +0000

LioranDB TypeScript Series #11: Deploy LioranDB with Docker Compose, Caddy and TLS

LioranDB TypeScript Series: Build with a developer-first document database powered by Rust and designed for TypeScript.

Running LioranDB locally is easy.

Exposing a database server to the internet deserves considerably more care.

Let's build a cleaner managed deployment.

Architecture

Instead of publishing every LioranDB port:

Internet
   ↓
HTTPS / TLS
   ↓
Caddy
   ↓
Docker network
   ↓
LioranDB

Only the reverse proxy should be publicly reachable.

Example Caddy configuration

acme.db.example.com {
  reverse_proxy liorandb:27018
}

acme.grpc.example.com {
  reverse_proxy h2c://liorandb:27019
}

Caddy handles the public TLS edge while LioranDB remains inside the Docker network.

Docker Compose

services:
  liorandb:
    image: liorandb/liorandb:pre-alpha
    container_name: liorandb-acme
    restart: unless-stopped

    cpus: 2.0
    mem_limit: 3.5g

    environment:
      LIORANDB_TLS_MODE: insecure
      LIORANDB_GRPC_BIND_ADDR: 0.0.0.0:27019
      LIORANDB_METRICS_ADDR: 0.0.0.0:27201

      LIORANDB_ADVERTISED_HTTP_ADDR: acme.db.example.com:443
      LIORANDB_ADVERTISED_GRPC_ADDR: acme.grpc.example.com:443

      LIORANDB_BOOTSTRAP_PASSWORD_FILE: /run/liorandb/bootstrap-password.txt

    expose:
      - "27018"
      - "27019"
      - "27201"

    volumes:
      - liorandb-data:/var/lib/liorandb/data
      - ./bootstrap-password.txt:/run/liorandb/bootstrap-password.txt:ro

    networks:
      - public-edge
      - metrics-private

  caddy:
    image: caddy:2
    restart: unless-stopped

    ports:
      - "80:80"
      - "443:443"

    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro

    networks:
      - public-edge

volumes:
  liorandb-data:

networks:
  public-edge:

  metrics-private:
    internal: true

Notice what's missing

There is no:

ports:
  - "27018:27018"
  - "27019:27019"
  - "27201:27201"

on the LioranDB service.

That's deliberate.

expose makes the ports available to services on the Docker network without publishing them directly on the host.

Firewall

For a typical Ubuntu deployment, the public firewall should only need the services you intentionally expose, such as:

22   SSH
80   HTTP
443  HTTPS

Don't casually expose:

27018
27019
27201

to the public internet.

Bootstrap password file

Generate a strong secret:

openssl rand -base64 32

Store it in:

bootstrap-password.txt

Then restrict access:

chmod 600 bootstrap-password.txt

The container receives it as a read-only mounted file.

Deployment flow

Validate your Compose configuration:

docker compose config

Start everything:

docker compose up -d

Inspect:

docker compose ps

Then verify health/readiness and advertised endpoints before connecting application traffic.

Application connection

Your application can then connect through the public TLS endpoint:

liorandb://admin:<encoded-password>@acme.db.example.com:443/default

Remember to URL-encode the password.

The important boundary

The database is not your public web server.

Treat the reverse proxy as the edge and keep the database itself on the private network.

That one architectural decision removes an impressive collection of future headaches.

Resources

Managed Deployment Guide:
https://docs.liorandb.com/docs/deployment/managed

Documentation: https://docs.liorandb.com
Website: https://liorandb.com

Previous: Part 10 → Official CLI
Next: Part 12 → Production Patterns, Diagnostics & What's Next

LioranDB TypeScript Series #10: Mastering the Official LioranDB CLI

Swaraj Puppalwar — Sat, 15 Aug 2026 20:13:15 +0000

LioranDB TypeScript Series #10: Mastering the Official LioranDB CLI

LioranDB TypeScript Series: Build with a developer-first document database powered by Rust and designed for TypeScript.

Not everything needs a dashboard.

Sometimes you just want a terminal and a database that listens.

Meet the official LioranDB CLI.

Install

npm install -g @liorandb/cli@1.0.5

The executable is:

liorandb

Initialize

liorandb init

Configure a connection:

liorandb set url \
  "liorandb://admin:YOUR_PASSWORD@127.0.0.1:27018/default"

Authenticate:

printf '%s' "$LIORANDB_PASSWORD" |
liorandb login admin --password-stdin

Select a database

liorandb db use default

Create a collection:

liorandb collection create products

Insert from stdin

printf '{"sku":"bk-001","title":"Blue Notebook","active":true}' |
liorandb insert-one products --stdin

Count:

liorandb count products

Then jump into the interactive shell:

liorandb shell

Profiles

The CLI supports local profiles, which makes switching environments much less painful.

Think:

local
staging
production
client-a
client-b

instead of repeatedly pasting connection information.

Output formats

Automation doesn't want pretty tables.

Humans often do.

The CLI supports output modes including:

table
json
ndjson
quiet

Global flags include:

--profile
--url
--output
--json
--quiet
--no-color
--debug

What can the CLI control?

Quite a lot.

Data

db
collection
find
find-one
insert-one
update-one
delete-many
aggregate
count

Indexes

index list
index create
index create-text
index drop

Authentication

login
logout
whoami
sessions
change-password

Administration

user
role
settings
cors

Operations

status
health
doctor
metrics
cluster
backup

Safety

Destructive commands should be difficult to trigger accidentally.

Operations such as drops, broad deletions and backup restore/delete flows use confirmation mechanisms unless explicitly overridden where supported.

That's intentional.

A CLI should help you operate the database, not speedrun deleting Tuesday.

Local state

CLI state is stored under:

.liorandb/state

You can override the location with:

LIORANDB_STATE_DIR

Passwords are not persisted as ordinary stored profile values.

CLI + Driver

The CLI and TypeScript driver aren't competing interfaces.

A common setup is:

Application code
    → @liorandb/driver

Developers / CI / Operations
    → @liorandb/cli

Use each where it fits best.

Resources

CLI Documentation:
https://docs.liorandb.com/docs/cli/overview

Documentation: https://docs.liorandb.com
Website: https://liorandb.com

Previous: Part 9 → Operations & Backups
Next: Part 11 → Docker Compose, Caddy & TLS

LioranDB TypeScript Series #9: Backups, Cluster Health and Operational APIs

Swaraj Puppalwar — Sat, 15 Aug 2026 20:11:45 +0000

LioranDB TypeScript Series #9: Backups, Cluster Health and Operational APIs

LioranDB TypeScript Series: Build with a developer-first document database powered by Rust and designed for TypeScript.

So far we've mostly treated LioranDB as an application database.

But the driver also exposes the operational side of the server.

Cluster state

const summary =
  await client.cluster.summary();

const nodes =
  await client.cluster.nodes();

const partitions =
  await client.cluster.partitions();

const health =
  await client.cluster.health();

const readiness =
  await client.cluster.readiness();

This makes operational tooling possible without maintaining a completely separate client stack.

Administrative operations

await client.cluster.checkpoint();
await client.cluster.compact();

These are administrative operations, so treat them accordingly.

Don't put compact() inside the request handler for /api/users.

I shouldn't need to say that, but somewhere a server just became nervous. 🤕

Creating a backup

const backup = await client.backups.create({
  label: "production-before-migration",
  scope: "local_node",
});

Cluster-scoped backups can also be requested where supported.

Backup jobs are asynchronous

Creating a backup doesn't mean the backup has already completed.

Retrieve its state:

const job = await client.backups.get(
  backup.backup_id
);

Production code should poll the job until it reaches its terminal state.

Verify backups

A backup you have never verified is a very optimistic file.

await client.backups.verify(
  backup.backup_id
);

Restore

Restores intentionally require explicit confirmation.

const restore = await client.backups.restore(
  backup.backup_id,
  {
    confirmation:
      `RESTORE ${backup.backup_id}`,

    disable_safety_backup: true,
  }
);

Then monitor the restore job:

const restoreJob =
  await client.backups.getRestoreJob(
    restore.job.job_id
  );

Runtime settings

The driver also exposes server settings:

await client.settings.get();
await client.settings.getCors();
await client.settings.getPerformance();
await client.settings.getLimits();
await client.settings.getBackups();

Administrative applications can update the corresponding configuration through the settings service.

That includes areas such as:

CORS
performance controls
server limits
backup configuration
backup retention and schedules

Why expose operations through TypeScript?

Because infrastructure increasingly becomes software.

Your internal control plane, managed-database dashboard, backup worker and deployment automation can all talk to the same database through a typed SDK.

That's a much nicer foundation than a folder containing 37 shell scripts named things like:

backup-final-v2-real-final.sh

Resources

Auth & Admin Reference:
https://docs.liorandb.com/docs/driver/auth-and-admin

Documentation: https://docs.liorandb.com
Website: https://liorandb.com

Previous: Part 8 → Auth, Users & Roles
Next: Part 10 → Official LioranDB CLI

LioranDB TypeScript Series #8: Authentication, Users, Roles and Sessions

Swaraj Puppalwar — Sat, 15 Aug 2026 20:10:12 +0000

LioranDB TypeScript Series #8: Authentication, Users, Roles and Sessions

LioranDB TypeScript Series: Build with a developer-first document database powered by Rust and designed for TypeScript.

A database isn't production infrastructure if everyone connecting to it effectively becomes root.

LioranDB exposes authentication and authorization through the same TypeScript client.

Authentication

const login = await client.auth.login(
  "admin",
  "password"
);

The client also exposes session operations:

await client.auth.me();
await client.auth.listSessions();
await client.auth.refresh(refreshToken);
await client.auth.revokeSession(sessionId);
await client.auth.logout();
await client.auth.logoutAll();

Automatic token refresh

Configure:

const client = await LioranDBClient.connect(uri, {
  autoRefreshTokens: true,
});

The driver's token manager can then handle session refresh automatically.

Create a user

Administrative clients can use UsersService.

const user = await client.users.create({
  username: "analytics-user",
  password: "SuperStrongPassword123!",
  roles: ["read_only"],
  must_change_password: false,
});

Manage it:

await client.users.list();
await client.users.get(userId);

await client.users.update(userId, {
  enabled: true,
  metadata: {
    team: "analytics",
  },
});

await client.users.revokeSessions(userId);
await client.users.delete(userId);

Roles

Instead of scattering permissions directly across application logic, create roles.

const role = await client.roles.createRole({
  name: "readers",

  grants: [
    {
      permission: "DocumentRead",

      scope: {
        kind: "database",
        database: "default",
      },
    },
  ],
});

Permission scopes

Permissions can be scoped at different levels.

Cluster:

{
  kind: "cluster"
}

Database:

{
  kind: "database",
  database: "default"
}

Collection:

{
  kind: "collection",
  database: "default",
  collection: "users"
}

That gives you a useful building block for least-privilege application accounts.

Application pattern

Don't make every service use the administrator account.

For example:

Admin / Operations
    → administrative role

Backend API
    → application-specific read/write role

Analytics
    → read-only role

Backup worker
    → backup permissions

The fewer permissions a compromised credential has, the smaller your blast radius.

Resources

Auth & Admin Docs:
https://docs.liorandb.com/docs/driver/auth-and-admin

Documentation: https://docs.liorandb.com
Website: https://liorandb.com

Previous: Part 7 → Aggregation
Next: Part 9 → Cluster, Backups & Operational APIs

LioranDB TypeScript Series #7: Building Aggregation Pipelines in TypeScript

Swaraj Puppalwar — Sat, 15 Aug 2026 20:08:53 +0000

LioranDB TypeScript Series #7: Building Aggregation Pipelines in TypeScript

LioranDB TypeScript Series: Build with a developer-first document database powered by Rust and designed for TypeScript.

CRUD gets data in and out.

Aggregation starts turning those documents into answers.

Your first pipeline

Suppose our products contain:

{
  title: string;
  category: string;
  price: number;
  inStock: boolean;
}

We want to count available products by category.

const results = await products.aggregate([
  {
    $match: {
      inStock: true,
    },
  },
  {
    $group: {
      _id: "$category",
      count: {
        $sum: 1,
      },
    },
  },
]).toArray();

Conceptually:

Documents
   ↓
$match
   ↓
$group
   ↓
Result

Add projection

const results = await products.aggregate([
  {
    $match: {
      inStock: true,
    },
  },
  {
    $group: {
      _id: "$category",
      count: {
        $sum: 1,
      },
    },
  },
  {
    $project: {
      category: "$_id",
      count: 1,
      _id: 0,
    },
  },
  {
    $limit: 50,
  },
]).toArray();

Current verified stages

In the current pre-alpha release:

$match
$group
$project
$skip
$limit

are the core documented/verified stages.

The aggregation API is intentionally still evolving.

AggregationCursor behavior

aggregate() returns an AggregationCursor.

const cursor = products.aggregate(pipeline);

const results = await cursor.toArray();

One important implementation detail in the current driver is that the aggregation result is materialized when the cursor initially loads.

For very large result sets, don't automatically treat aggregation like incremental find() pagination.

When should I use `find()` instead?

If all you're doing is:

filtering
projection
pagination
limiting records

then find() may be the simpler tool.

Use aggregation when you're actually transforming or grouping data.

Need documents?
    → find()

Need derived results?
    → aggregate()

Pre-alpha limitations are intentional

This is one area where the API will become substantially richer over time.

I'd rather document the stages that work today than publish a giant MongoDB compatibility table containing features that don't exist yet.

Pre-alpha should be explicit about its edges.

Resources

Documentation: https://docs.liorandb.com
Website: https://liorandb.com
Driver: @liorandb/driver@2.0.5

Previous: Part 6 → Indexes
Next: Part 8 → Authentication, Users, Roles & Sessions

DEV Community: Swaraj Puppalwar

Meet LioranDB: A Document Database Built in Rust

Meet LioranDB: A Document Database Built in Rust

What Is LioranDB?

Why Build Another Database?

LioranDB V2 Is Still Pre-Alpha

Current Performance Target

Watch the Video

Try LioranDB

LioranDB Managed Hosting Is Now Open: ₹5,000/Month for Early-Stage Startups

Two Pricing Options

1. Fixed Plan: ₹5,000/month

2. Custom Plan

How Do You Get a Managed LioranDB Database?

Why an Application Process?

What Is LioranDB?

Interested?

LioranDB V2 Is in Pre-Alpha. Please Try to Break It.

What is LioranDB?

So, I'm Looking for Feedback

How to Test It

Found Something?

Why I'm Doing This

Swaraj's High Rise in Computers! | Nagpur Post | 23 May 2023

स्वराजची संगणक क्षेत्रात उंच भरारी | Navarashtra, Chandrapur | 23 May 2023

‘स्वराज’ची संगणकात गगनभरारी | Tarun Bharat, Purva Vidarbha | 29 May 2023

LioranDB TypeScript Series #12: Production Patterns, Error Handling and What Comes Next

LioranDB TypeScript Series #12: Production Patterns, Error Handling and What Comes Next

Understand driver errors

Use instanceof

Add diagnostics

Production checklist

Remember: this is pre-alpha

What comes next?

Start building

Resources

LioranDB TypeScript Series #11: Deploy LioranDB with Docker Compose, Caddy and TLS

LioranDB TypeScript Series #11: Deploy LioranDB with Docker Compose, Caddy and TLS

Architecture

Example Caddy configuration

Docker Compose

Notice what's missing

Firewall

Bootstrap password file

Deployment flow

Application connection

The important boundary

Resources

LioranDB TypeScript Series #10: Mastering the Official LioranDB CLI

LioranDB TypeScript Series #10: Mastering the Official LioranDB CLI

Install

Initialize

Select a database

Insert from stdin

Profiles

Output formats

What can the CLI control?

Data

Indexes

Authentication

Administration

Operations

Safety

Local state

CLI + Driver

Resources

LioranDB TypeScript Series #9: Backups, Cluster Health and Operational APIs

LioranDB TypeScript Series #9: Backups, Cluster Health and Operational APIs

Cluster state

Administrative operations

Creating a backup

Backup jobs are asynchronous

Verify backups

Restore

Runtime settings

Why expose operations through TypeScript?

Resources

LioranDB TypeScript Series #8: Authentication, Users, Roles and Sessions

LioranDB TypeScript Series #8: Authentication, Users, Roles and Sessions

Authentication

Use `instanceof`

When should I use `find()` instead?