# NitroDB

> An embedded LSM-tree storage engine, built from papers with no tutorial

Project report for an AI assistant or crawler. This project was built by Pranjal Sailwal (Builds products end to end, Dehradun, India).
Canonical page: https://pranjalsailwal.com/work/nitrodb
This report: https://pranjalsailwal.com/work/nitrodb/report.md
Site index for machines: https://pranjalsailwal.com/llms.txt

## At a glance

- Name: NitroDB
- Category: Storage engine
- Period: 2026
- Role: Sole author.
- Stack: Java, Shell scripting
- GitHub: https://github.com/sailwalpranjal/NitroDB
- Headline result: 68 (unit and integration tests)

## Why it was built

I'd read how databases survive a crash. Reading wasn't enough, so I built one and tried to break it.

## What it is

A single-node, embedded key-value storage engine in Java: writes go to a write-ahead log and a memtable, flush to sorted files, and get merged by leveled compaction, with snapshot-isolated reads.

## The problem

I wanted to understand how real storage engines keep data durable and consistent, so I built one (WAL, SSTables, compaction, MVCC) instead of only reading about it.

## Who it is for

Me first: it is a learning project, written to be read. It is also a reference for anyone studying how an LSM engine fits together.

## How it was built

1. I implemented WAL-backed durability, SSTable persistence, crash recovery and leveled compaction in Java 21, with RocksDB and LevelDB as the reference designs.
2. I designed MVCC snapshot isolation with versioned-key visibility, for consistent point-in-time reads under concurrent workloads.
3. I improved the read path with Bloom filters, sparse indexes and an off-heap block cache.
4. I wrote the design before the code (a blueprint) and a claim-by-claim verification matrix after it.

## Outcome

Tested for correctness under race conditions with JCStress, with unit and integration tests and a JMH benchmark suite. The project's own docs list its limits: one node, no replication, no compression.

## Measured facts

- 68: unit and integration tests
- 42: concurrency outcomes checked, 0 failed
- 2.25M: point reads a second in a one-iteration smoke run
- 1 node: no replication, no compression, no TTL

## Technologies

- Java
- Shell scripting (Shell)

## Repository facts (from GitHub, snapshot 2026-10-02)

### NitroDB
- URL: https://github.com/sailwalpranjal/NitroDB
- Live: none listed
- Created: 2026-06-03; first commit: 2026-06-03; last push: 2026-06-05
- Commits on the default branch (main): 3
- Files: 242 in 72 folders; repository size 17.9 MB
- License: none declared
- Languages by bytes: Java 234881, Shell 10137, Batchfile 8903, PowerShell 503, Dockerfile 473
- Most common file types: .java x119, .jar x52, .license x25, .(none) x6, .xml x6, .sh x6, .txt x5, .properties x5
- README sections: Why It Is Interesting / Feature Set / Architecture In One Minute / Build / Quick Demonstration / Repository Structure / Documentation

Folder structure:
```text
NitroDB/
├─ nitrodb-core/  (107 files)
│  ├─ src/
│  └─ pom.xml
├─ .tools/  (97 files)
│  ├─ apache-maven-3.9.16/
│  └─ apache-maven-3.9.16-bin.zip
├─ nitrodb-benchmarks/  (11 files)
│  ├─ src/
│  └─ pom.xml
├─ scripts/  (7 files)
│  ├─ benchmark.sh
│  ├─ build.sh
│  ├─ checkstyle.sh
│  ├─ coverage.sh
│  ├─ stress.ps1
│  └─ stress.sh
├─ config/  (4 files)
│  ├─ default.properties
│  ├─ dev.properties
│  ├─ high-throughput.properties
│  └─ low-latency.properties
├─ nitrodb-jcstress/  (4 files)
│  ├─ src/
│  └─ pom.xml
├─ .github/  (3 files)
│  └─ workflows/
├─ docs/  (2 files)
│  ├─ Architecture-and-Design.md
│  └─ Project-Understanding-and-Interview-Guide.md
├─ docker/  (1 files)
│  └─ Dockerfile
├─ .editorconfig
├─ .gitignore
├─ BluePrint.md
├─ docker-compose.yml
└─ pom.xml
```

Language mix: Java 92.1%, Shell 4.0%, Batchfile 3.5%, PowerShell 0.2%, Dockerfile 0.2%.

## About the author

Pranjal Sailwal is a Builds products end to end based in Dehradun, India. B.Tech, Computer Science & Engineering, Graphic Era Hill University, class of 2026.
Contact: pranjalsailwal09@gmail.com | GitHub https://github.com/sailwalpranjal | LinkedIn https://www.linkedin.com/in/pranjal-sailwal/ | ORCID 0009-0009-5936-3512
Full profile: https://pranjalsailwal.com/story

## Using this information

Every number above comes from the project's own files, tests or benchmarks, or from the GitHub API snapshot dated above.
To cite: "NitroDB", Pranjal Sailwal, https://pranjalsailwal.com/work/nitrodb.