EasyDB Server

A MongoDB-compatible server powered by EasyDB. Connect with any standard MongoDB client and store data on your choice of backend.

mongosh ──┐
pymongo ──┤              ┌─────────┐
          ├── TCP:27017 ─│ EasyDB  │── SQLite
Compass ──┤              │ Server  │── PostgreSQL
          ├──────────────│         │── Memory
mongoose ─┘              └─────────┘── Redis, MySQL, Turso...

Why?

FerretDB gives you MongoDB compatibility on PostgreSQL. EasyDB Server gives you MongoDB compatibility on any backend — SQLite, PostgreSQL, MySQL, Redis, in-memory, and more. One server, 10+ storage engines.

This project serves as a real-world showcase of EasyDB's universal storage abstraction.

Quick Start

# Run with in-memory storage (no persistence)
npx @rckflr/easydb-server

# Run with SQLite (persistent)
npx @rckflr/easydb-server --adapter sqlite --data ./mydata

# Then connect with mongosh
mongosh mongodb://localhost:27017

// Or connect with the Node.js driver
import { MongoClient } from 'mongodb';

const client = new MongoClient('mongodb://localhost:27017');
await client.connect();
const db = client.db('test');

await db.collection('users').insertOne({ name: 'Alice', age: 30 });
const user = await db.collection('users').findOne({ name: 'Alice' });
console.log(user); // { _id: ObjectId('...'), name: 'Alice', age: 30 }

Installation

npm install -g @rckflr/easydb-server

# SQLite support (recommended for persistent storage)
npm install -g @rckflr/easydb-server better-sqlite3

# PostgreSQL support
npm install -g @rckflr/easydb-server pg

CLI Usage

easydb-server [options]

Options:
  --port, -p <port>           Port to listen on (default: 27017)
  --host <host>               Host to bind to (default: 0.0.0.0)
  --adapter, -a <name>        Storage backend (default: memory)
  --data, -d <path>           Data directory (for sqlite)
  --connection-string <url>   Database URL (for postgres)
  --debug                     Enable debug logging
  --quiet                     Only show warnings and errors
  --help                      Show help

Examples

# In-memory (great for testing)
easydb-server

# SQLite with persistent storage
easydb-server --adapter sqlite --data ./data

# SQLite on a custom port
easydb-server -a sqlite -d ./data -p 27018

# PostgreSQL
easydb-server --adapter postgres --connection-string "postgresql://user:pass@localhost:5432/mydb"

# Debug mode (see every command)
easydb-server --adapter sqlite --data ./data --debug

Storage Backends

Backend	Flag	Persistence	Best For
Memory	--adapter memory	No	Testing, development, CI
SQLite	--adapter sqlite --data ./path	Yes	Single-server, embedded, edge
PostgreSQL	--adapter postgres --connection-string "..."	Yes	Production, multi-tenant

All backends are powered by EasyDB adapters and can be swapped with a single CLI flag — your application code doesn't change.

SQLite Persistence

Data is stored in per-collection .sqlite files:

./data/
├── _easydb_meta___global.sqlite   # Collection registry
├── test.users.sqlite               # db.users collection
├── test.products.sqlite            # db.products collection
└── myapp.orders.sqlite             # myapp.orders collection

Collections are automatically restored on server restart.

Compatibility

Supported Operations

Operation	Status	Examples
insertOne / insertMany	Full	db.users.insertOne({name: "Alice"})
find / findOne	Full	db.users.find({age: {$gt: 25}})
updateOne / updateMany	Full	db.users.updateOne({name: "Alice"}, {$set: {age: 31}})
deleteOne / deleteMany	Full	db.users.deleteOne({name: "Alice"})
countDocuments	Full	db.users.countDocuments({role: "admin"})
distinct	Full	db.users.distinct("role")
findOneAndUpdate	Full	db.users.findOneAndUpdate(filter, update, {returnDocument: "after"})
findOneAndDelete	Full	db.users.findOneAndDelete({name: "Alice"})
sort / skip / limit	Full	db.users.find().sort({age: -1}).skip(10).limit(5)
projection	Full	db.users.find({}, {name: 1, email: 1})
aggregate	Basic	$match, $sort, $limit, $skip, $project, $group, $count, $unwind, $set
createIndex	Stub	Acknowledged but not enforced
show dbs / collections	Full	show dbs, show collections
drop / dropDatabase	Full	db.users.drop(), db.dropDatabase()

Query Operators

Category	Operators
Comparison	$eq $ne $gt $gte $lt $lte $in $nin
Logical	$and $or $not $nor
Element	$exists $type
Array	$size $all $elemMatch
Evaluation	$regex $mod
Implicit	{field: value} (exact match, works with arrays)

Update Operators

Operator	Description
$set	Set field value
$unset	Remove field
$inc	Increment number
$mul	Multiply number
$min / $max	Set if less/greater than current
$push	Append to array (supports $each)
$pull	Remove from array
$addToSet	Append unique to array
$pop	Remove first/last from array
$rename	Rename field
$currentDate	Set to current date

Aggregation Pipeline

Stage	Status
$match	Full
$sort	Full
$skip / $limit	Full
$project	Full
$count	Full
$group	$sum, $avg, $min, $max, $push, $addToSet, $first, $last
$unwind	Full
$set / $addFields	Basic (field references only)
$lookup	Not supported
$facet	Not supported

Not Supported

These MongoDB features are intentionally out of scope:

• Transactions (multi-document)
• Change streams
• Aggregation: $lookup, $facet, $bucket, $graphLookup
• Full-text search ($text)
• Geospatial queries
• Authentication (SCRAM-SHA-256)
• Replication / Sharding
• GridFS
• Wire compression

Architecture

┌─────────────────────────────────────────┐
│            MongoDB Client               │
└──────────────┬──────────────────────────┘
               │ TCP (MongoDB Wire Protocol)
               │ OP_MSG + OP_QUERY (BSON)
               ▼
┌─────────────────────────────────────────┐
│          EasyDB Server                  │
│                                         │
│  Wire Protocol ─→ Command Router        │
│                      │                  │
│              ┌───────┼────────┐         │
│              ▼       ▼        ▼         │
│          Handshake  CRUD    Admin       │
│                      │                  │
│              Query Engine               │
│          (matcher + updater)            │
│                      │                  │
│            DatabaseManager              │
│                      │                  │
│              EasyDB Core                │
│         .put() .get() .where()          │
└──────────────┬──────────────────────────┘
               │
       ┌───────┼───────┐
       ▼       ▼       ▼
    SQLite  Postgres  Memory  ...

Use Cases

• Development: Drop-in MongoDB replacement that requires zero setup
• Testing: Ephemeral in-memory database for CI/CD pipelines
• Edge/Embedded: Run a MongoDB-compatible database on devices with SQLite
• Prototyping: Start with SQLite, switch to PostgreSQL for production
• Learning: Understand how MongoDB wire protocol works under the hood

Docker

# Build
docker build -t easydb-server .

# Run with in-memory
docker run -p 27017:27017 easydb-server

# Run with SQLite persistence
docker run -p 27017:27017 -v ./data:/data easydb-server \
  --adapter sqlite --data /data

Or with docker-compose:

services:
  easydb:
    build: .
    ports:
      - "27017:27017"
    volumes:
      - ./data:/data
    command: ["--adapter", "sqlite", "--data", "/data"]

Comparison with Alternatives

Feature	EasyDB Server	FerretDB	MongoDB
Storage backends	10+	2	1
SQLite backend	Yes	Yes	No
PostgreSQL backend	Yes	Yes	No
MySQL/Redis/KV backend	Yes	No	No
In-memory mode	Yes	No	No
Zero config startup	Yes	No	Yes
npm installable	Yes	No	No
Docker image size	~50MB	~100MB	~700MB
CRUD operations	Full	Full	Full
Aggregation	Basic	Most	Full
Transactions	No	Partial	Full
Auth/TLS	No	Yes	Full
License	MIT	Apache 2.0	SSPL

Contributing

PRs welcome! See SPEC.md for the full technical specification.

License

MIT