pip install nedb-engine

python3 -c "import nedb; print(nedb.__version__)"
# 0.3.1

nedbd
# nedbd 0.3.1 — http://127.0.0.1:7070  data=./nedb-data  auth=off

from nedb import NEDB

# Durable (persists to disk). Use NEDB() for in-memory.
db = NEDB("./mydata")

# Indexes power fast filtering, sorting, and full-text search
db.create_index("users", "status", "eq")
db.create_index("users", "age", "ordered")
db.create_index("users", "bio", "search")

# Write rows
db.put("users", "alice", {"name": "Alice", "age": 31, "status": "active", "bio": "systems engineer"})
db.put("users", "bob",   {"name": "Bob",   "age": 40, "status": "active", "bio": "database architect"})

# Idempotent write — safe to retry forever
db.put("orders", "o1", {"total": 42}, client="checkout", nonce=7, idem="charge-o1")

# Query with NQL
db.query('FROM users WHERE status = "active" ORDER BY age DESC')
db.query('FROM users SEARCH "systems"')

# Relations + traversal
db.link("users:alice", "follows", "users:bob")
db.q("users").where("_id", "=", "alice").traverse("follows").run()

# Time-travel
snap = db.seq
db.put("users", "alice", {"age": 32, "status": "active"})
db.get("users", "alice", as_of=snap)["age"]  # → 31

# Integrity
assert db.verify()              # hash chain intact
assert db.verify_determinism()  # state == replay(log)

db.close()

db = NEDB()              # in-memory
db = NEDB("./data")     # durable — creates ./data/log.aof + meta.json

# Use as a context manager for automatic close/flush:
with NEDB("./data") as db:
    db.put("k", "1", {"v": 1})

# Simple write
doc = db.put("users", "alice", {"name": "Alice", "age": 31})

# Idempotent write — calling this 100 times = calling it once
db.put("orders", "o1", {"total": 99}, client="api", nonce=1, idem="order-o1-v1")

# Explicit nonce (replay-protected from a distributed service)
db.put("events", "e1", {"type": "click"}, client="tracker", nonce=42)

db.delete("users", "alice")

doc = db.get("users", "alice")          # current HEAD
old = db.get("users", "alice", as_of=3)  # as it was at seq 3

rows = db.query('FROM users WHERE status = "active" ORDER BY age DESC LIMIT 10')
found = db.query('FROM users SEARCH "engineer"')
old   = db.query('FROM users AS OF 5 WHERE age > 25')

db.create_index("users", "status", "eq")       # WHERE status = "active"
db.create_index("users", "created_at", "ordered")  # ORDER BY created_at DESC
db.create_index("users", "bio", "search")        # SEARCH "engineer"

db.link("users:alice", "follows", "users:bob")
db.link("users:alice", "follows", "users:carol")

db.neighbors("users:alice", "follows")         # ["users:bob", "users:carol"]
db.inbound("users:bob", "follows")             # ["users:alice"]

snap = db.seq
db.unlink("users:alice", "follows", "users:bob")
db.neighbors("users:alice", "follows", as_of=snap)  # ["users:bob", "users:carol"] (time-travel)

data = open("notes.txt", "rb").read()
v1 = db.put_file("notes.txt", data)           # warm tier (fast)
v2 = db.put_file("notes.txt", new_data, tier="cold")  # cold tier (max compression)

db.get_file("notes.txt", v1)                  # original bytes back
db.file_root("notes.txt", v1)                 # Merkle root — anchorable on ITC
db.compression_stats("warm")                  # {"ratio": 39.9, "dedup_hits": 20, ...}

results = (
    db.q("users")
      .where("status", "=", "active")
      .where("age", ">=", 25)
      .order_by("age", "DESC")
      .limit(10)
      .run()
)

db.query('FROM users')                     # all users
db.query('FROM orders LIMIT 20')           # first 20 orders

db.query('FROM users WHERE status = "active"')
db.query('FROM users WHERE age >= 25 AND status = "active"')
db.query('FROM orders WHERE total > 100 AND status != "cancelled"')

db.create_index("users", "bio", "search")

db.query('FROM users SEARCH "rust"')
db.query('FROM users SEARCH "systems engineer"')  # both terms must match

db.query('FROM users ORDER BY age ASC')
db.query('FROM users ORDER BY created_at DESC LIMIT 10')
db.query('FROM orders WHERE status = "paid" ORDER BY total DESC')

# Who does alice follow?
db.query('FROM users WHERE _id = "alice" TRAVERSE follows')

# All work orders for active projects
db.query('FROM projects WHERE status = "active" TRAVERSE contains')

snap = db.seq
db.put("users", "alice", {"age": 32})

# alice is 31 at the snapshot, 32 at HEAD
db.query(f'FROM users AS OF {snap} WHERE _id = "alice"')
db.query('FROM users AS OF 0')   # empty — nothing existed at seq 0

db.query('FROM users ORDER BY created_at DESC LIMIT 5')
db.query('FROM users WHERE status = "active" LIMIT 100')

# Session 1 — write data
db = NEDB("./mydata")
db.create_index("users", "status", "eq")
db.put("users", "alice", {"name": "Alice", "status": "active"})
db.close()  # flush + fsync

# Session 2 — reopen (replays log.aof, rebuilds state)
db = NEDB("./mydata")
assert db.verify()                            # chain intact across the restart
assert db.get("users", "alice")["name"] == "Alice"

nedbd
# nedbd 0.3.1 — http://127.0.0.1:7070  data=./nedb-data  auth=off

NEDBD_PORT=9000 NEDBD_DATA=/var/db/nedb NEDBD_TOKEN=my-secret nedbd

{
  "name": "shop",
  "init": {
    "indexes": [
      ["users", "status", "eq"],
      ["orders", "total", "ordered"]
    ],
    "seed": {
      "users": [{"id": "u1", "name": "Ada", "status": "active"}]
    },
    "links": [
      ["users:u1", "placed", "orders:o1"]
    ]
  }
}

curl -X POST http://localhost:7070/v1/databases \
  -H 'Content-Type: application/json' \
  -d '{"name":"myapp"}'

curl -X POST http://localhost:7070/v1/databases/myapp/query \
  -H 'Content-Type: application/json' \
  -d '{"nql":"FROM users WHERE status = \"active\" ORDER BY age DESC LIMIT 5"}'

curl -X POST http://localhost:7070/v1/databases/myapp/put \
  -H 'Content-Type: application/json' \
  -d '{"coll":"users","id":"u1","doc":{"name":"Ada","status":"active","age":31}}'

curl http://localhost:7070/v1/databases/myapp/verify
# {"ok": true, "seq": 1, "head": "a3f..."}

curl http://localhost:7070/v1/databases \
  -H 'Authorization: Bearer my-secret'

const BASE = 'http://127.0.0.1:7070'

async function query(db, nql) {
  const res = await fetch(`${BASE}/v1/databases/${db}/query`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ nql })
  })
  return (await res.json()).rows
}

async function put(db, coll, id, doc) {
  const res = await fetch(`${BASE}/v1/databases/${db}/put`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ coll, id, doc })
  })
  return res.json()
}

// Usage
const users = await query('myapp', 'FROM users WHERE status = "active"')
await put('myapp', 'users', 'u2', { name: 'Bo', status: 'active', age: 28 })

import requests

BASE = "http://127.0.0.1:7070"

rows = requests.post(
    f"{BASE}/v1/databases/myapp/query",
    json={"nql": 'FROM users WHERE status = "active" ORDER BY age DESC'}
).json()["rows"]

requests.post(
    f"{BASE}/v1/databases/myapp/put",
    json={"coll": "users", "id": "u3", "doc": {"name": "Cy", "status": "active"}}
)

from nedb import NEDB
from nedb.sql import sql_exec, sql_to_nql

db = NEDB("./data")

# SELECT → NQL query
sql_exec(db, "SELECT * FROM users WHERE status = 'active' ORDER BY age DESC LIMIT 10")
sql_exec(db, "SELECT * FROM users WHERE bio LIKE '%rust%'")       # LIKE → SEARCH
sql_exec(db, f"SELECT * FROM orders AS OF {snap}")               # NEDB extension: time-travel

# INSERT → db.put()
sql_exec(db, "INSERT INTO users (id, name, age, status) VALUES ('u1', 'Ada', 31, 'active')")

# UPDATE → fetch + merge + db.put()  (all other fields preserved)
sql_exec(db, "UPDATE users SET age = 32 WHERE id = 'u1'")

# DELETE → db.delete()
sql_exec(db, "DELETE FROM users WHERE id = 'u1'")

# See what NQL a SELECT compiles to:
sql_to_nql("SELECT * FROM users WHERE status = 'active' ORDER BY age DESC LIMIT 5")
# → 'FROM users WHERE status = "active" ORDER BY age DESC LIMIT 5'

from nedb import NEDB
from nedb.redis_compat import RedisCompat

r = RedisCompat(NEDB("./data"))

# Strings
r.execute("SET", "k", "hello")           # → "OK"
r.execute("GET", "k")                    # → "hello"
r.execute("INCR", "counter")             # → 1
r.execute("MSET", "a", "1", "b", "2")   # → "OK"

# Hashes  (Redis key names with colons work: "user:1")
r.execute("HSET", "user:1", "name", "Ada", "age", "31")
r.execute("HGET", "user:1", "name")     # → "Ada"
r.execute("HGETALL", "user:1")          # → {"name": "Ada", "age": "31"}

# Sets
r.execute("SADD", "tags", "python", "rust")
r.execute("SMEMBERS", "tags")           # → {"python", "rust"}
r.execute("SISMEMBER", "tags", "rust") # → 1

# Lists
r.execute("RPUSH", "q", "a", "b", "c")
r.execute("LRANGE", "q", 0, -1)         # → ["a", "b", "c"]
r.execute("LPOP", "q")                  # → "a"

# Unsupported — clear error + roadmap link
r.execute("EXPIRE", "k", 60)            # → RedisUnsupportedError

import redis, json
from nedb import wrap_redis

# ONE LINE — Alice's app code doesn't change
r = wrap_redis(redis.Redis("localhost", 6379), db_name="rideshare")

# Surface 1 — existing Redis commands, unchanged
r.set("driver:d1", json.dumps({"name": "Bob", "status": "active"}))
r.get("driver:d1")     # → b'{"name": "Bob", ...}'
r.hset("trip:t1", mapping={"status": "requested"})

# Surface 2 — new NEDB features on the same connection
r.nedb.put("driver", "d1", {"name": "Bob", "status": "active"})
r.nedb.query('FROM driver WHERE status = "active"')
r.nedb.verify()    # → True

wrap_redis(
    r,                         # redis.Redis (or compatible) connection
    db_name: str = "default",  # logical name; NEDB uses nedb:{db_name}:*
    nedbd_url: str = None,     # route r.nedb.* to a nedbd server (see below)
    nedbd_token: str = None,   # bearer token for nedbd auth (optional)
) → WrappedRedis

# Step 1 — register: map Redis key globs to NEDB collections (chainable)
(r.nedb
 .register("driver:*", collection="driver", value_parser=json.loads)
 .register("trip:*",   collection="trip",   value_type="hash")
)

# Step 2 — backfill: import all existing Redis data once
imported = r.nedb.backfill()     # → int (number of keys imported)

# Step 3 — shadow: all future surface-1 writes auto-chain
r.nedb.shadow_writes = True

# Backfill all registered patterns
imported = r.nedb.backfill()

# Or backfill a single pattern directly (no prior register needed)
imported = r.nedb.backfill("zone:*", "zone", value_parser=json.loads)

r.nedb.shadow_writes = True

# Alice's code — unchanged
r.set("driver:d1", json.dumps({"name": "Bob", "status": "active"}))
r.hset("trip:t1", mapping={"status": "en_route", "driver_id": "d1"})

# → both writes auto-chained into NEDB
r.nedb.get("driver", "d1")  # → {"name": "Bob", "status": "active", "_source": "shadow"}

# HSET merges with existing NEDB doc
r.nedb.get("trip", "t1")   # → {"status": "en_route", "driver_id": "d1", "rider_id": "u1", ...}

# Time-travel through shadowed writes
snap = r.nedb.seq
r.set("driver:d1", json.dumps({"name": "Bob", "status": "offline"}))
r.nedb.get_as_of("driver", "d1", snap)   # → {"status": "active", ...}

# Disable at any time
r.nedb.shadow_writes = False

import redis
from nedb import wrap_redis

r = wrap_redis(
    redis.Redis("localhost", 6379),
    db_name="rideshare",
    nedbd_url="http://localhost:8421",   # ← nedbd server
    nedbd_token="my-secret",             # ← optional bearer token
)

# Surface 1 — Redis, unchanged
r.set("driver:d1", "...")

# Surface 2 — forwarded to nedbd over HTTP/JSON
r.nedb.put("driver", "d1", {"name": "Bob"})
r.nedb.query('FROM driver WHERE status = "active"')
r.nedb.verify()   # → True

# Backfill + shadow_writes work identically in nedbd mode
r.nedb.register("driver:*", "driver", value_parser=json.loads)
r.nedb.backfill()
r.nedb.shadow_writes = True

r.nedb.put("trip", "t1",
    {"rider": "u1", "driver": "d1"},
    caused_by=[r.nedb.seq - 1],
    evidence="inference",
    confidence=0.97)

r.nedb.query('FROM trip WHERE _id = "t1" TRACE caused_by')  # works in nedbd mode

from nedb import NEDB, AutoIndexDB

db = AutoIndexDB(NEDB("./data"), threshold=5, verbose=True)

# Query as normal — field usage is tallied automatically
db.query('FROM users WHERE status = "active"')   # 1/5
db.query('FROM users WHERE status = "active"')   # 2/5
# ... 3 more ...
db.query('FROM users WHERE status = "active"')
# [autoindex] created eq index on users.status (threshold=5)

# Check what's been created and what's close
db.analyze()
# {"tallies": {"users.status (eq)": 5}, "indexes_created": ["users.status (eq)"], "threshold": 5}

db.suggest()
# ["users.age (ordered) — 3/5 queries"]  ← not yet at threshold

# All other NEDB methods work unchanged — AutoIndexDB is a transparent proxy
db.put("users", "u1", {"name": "Ada", "status": "active"})
db.get("users", "u1")
db.verify()

from nedb import NEDB

db = NEDB("./data")
# ... write 100 K rows ...
db.checkpoint()   # anchor state in the chain → writes snapshot.json
db.close()

# Next open: loads snapshot then replays only delta ops
db2 = NEDB("./data")
assert db2.verify()   # chain from genesis → checkpoint op → delta: intact

curl -X POST localhost:7070/v1/databases/mydb/checkpoint
# {"ok": true, "head": "abc...", "seq": 1042}

# Put with TTL
db.put("cache", "session", {"token": "xyz"}, ttl_s=3600)   # expires in 1 hour

# Set / update TTL on an existing doc
db.expire("cache", "session", ttl_s=300)   # update to 5 minutes; False if not found

# Bulk sweep (call periodically for background maintenance)
n = db.sweep()   # → number of expired docs deleted

# Count rows per group
db.query("FROM orders GROUP BY status COUNT")
# → [{"status": "paid", "count": 42}, {"status": "pending", "count": 7}]

# Sum a numeric field
db.query("FROM sales GROUP BY region SUM revenue")
# → [{"region": "north", "count": 3, "sum_revenue": 15000}, ...]

# Average
db.query("FROM scores GROUP BY grade AVG score")

# Min / Max
db.query("FROM items GROUP BY category MIN price")
db.query("FROM items GROUP BY category MAX price")

# With WHERE (filter before grouping)
db.query('FROM orders WHERE region = "EU" GROUP BY status COUNT')

db = NEDB("./data", tmk=bytes.fromhex("a3f1..."))   # 32-byte hex key

# .env
NEDB_TMK=a3f1...  # 64-char hex string (any length accepted, normalised via HKDF)

# or a key file
NEDB_TMK_FILE=/run/secrets/nedb-tmk

NEDB_TMK=a3f1... nedbd

db = NEDB("./data", tmk=old_key)
db.rewrap_key(old_tmk=old_key, new_tmk=new_key)
db.close()
# Database now only opens with new_key

# env var: NEDBD_RESP2_PORT (0 = disabled, default)
NEDBD_RESP2_PORT=6379 nedbd

# Boot log:
#   nedbd 0.6.0 — http://127.0.0.1:7070  data=./nedb-data  auth=off
#   resp2  — redis://  127.0.0.1:6379  (RESP2 wire protocol)

redis-cli -p 6379 PING                              # PONG
redis-cli -p 6379 SELECT salonbooking             # OK — open that database
redis-cli -p 6379 SET key "hello"                  # OK
redis-cli -p 6379 HSET "user:1" name Ada age 31   # :2
redis-cli -p 6379 SADD tags python rust            # :2
redis-cli -p 6379 SMEMBERS tags                     # {"python", "rust"}

# EVAL runs any NQL query; rows are returned as JSON strings
redis-cli -p 6379 EVAL "FROM users WHERE status = \"active\" LIMIT 5" 0
# 1) "{\"_id\":\"u1\",\"name\":\"Ada\",\"status\":\"active\"}"
# 2) "{\"_id\":\"u2\",\"name\":\"Bo\",\"status\":\"active\"}"