ZDB — Web3 Database

 ███████████ ██████████   ███████████    
▒█▒▒▒▒▒▒███ ▒▒███▒▒▒▒███ ▒▒███▒▒▒▒▒███   
▒     ███▒   ▒███   ▒▒███ ▒███    ▒███   
     ███     ▒███    ▒███ ▒██████████    
    ███      ▒███    ▒███ ▒███▒▒▒▒▒███   
  ████     █ ▒███    ███  ▒███    ▒███   
 ███████████ ██████████   ███████████    
▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒▒▒

 ███████████ ██████████   ███████████    
▒█▒▒▒▒▒▒███ ▒▒███▒▒▒▒███ ▒▒███▒▒▒▒▒███   
▒     ███▒   ▒███   ▒▒███ ▒███    ▒███   
     ███     ▒███    ▒███ ▒██████████    
    ███      ▒███    ▒███ ▒███▒▒▒▒▒███   
  ████     █ ▒███    ███  ▒███    ▒███   
 ███████████ ██████████   ███████████    
▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒▒▒

web3 database · ipfs native · encrypted

install

curl -fsSL https://zdb.zexvro.in/install.sh | bash

requires node 20+. works on linux, macos, termux.

v 0.2.1 ↓

─────────────────────────────────────────────────────────────────────────────────────────────────────────────

what it does

ZDB is a web3-native database. data is AES-256-GCM encrypted, stored on IPFS, and verified by content hash. self-hosted, zero dependencies, runs anywhere Node.js runs.

encrypted

AES-256-GCM on every shard. your data is random bytes on IPFS. only you hold the key.

ipfs native

content-addressed storage with CID chains. data lives on the distributed web, not a single server.

zero deps

pure node.js. no frameworks, no build step, no npm install. just a single server binary.

semantic search

cosine similarity over vectors. insert, search, query — all through a simple REST API.

self-hosted

runs on your phone, your laptop, your raspberry pi. you own the infrastructure.

compact

entire codebase fits in a single directory. readable, auditable, forkable.

quickstart

from zero to running in under a minute.

install

one command installs Node 20+, Kubo IPFS, PM2, and the ZDB server.

start

launch IPFS and the ZDB daemon. health check confirms everything is running.

write data

POST JSON to any collection. data is encrypted and pinned to IPFS automatically.

read data

GET by ID or query with filters. data is fetched from IPFS and decrypted on the fly.

api

REST API on localhost:8899. every endpoint returns JSON.

create recordPOST
// request
POST /v1/db/users
{ "name": "zexvro", "role": "admin" }

// response
{ "ok": true, "id": "a1b2c3d4", "cid": "Qm..." }

read recordGET
GET /v1/db/users/a1b2c3d4

{ "name": "zexvro", "role": "admin" }

query recordsPOST
POST /v1/db/users/query
{ "where": { "field": "role", "op": "==", "value": "admin" } }

GET /health	server health check
POST /v1/db/:col	create record
GET /v1/db/:col/:id	get record by ID
GET /v1/db/:col	list all records
PUT /v1/db/:col/:id	update record
DELETE /v1/db/:col/:id	delete record
POST /v1/db/:col/query	query with filters

architecture

phone = storage + compute + IPFS. laptop = frontend + API. zero moving parts.

engine

storage engine with CID shard chain, async record loading, and IPFS pin management.

crypto

AES-256-GCM encryption. auto-generated key, unique IV per shard, backward-compatible reads.

router

lightweight HTTP router with middleware pipeline. rate limiting, CORS, CSP built in.

ipfs client

Kubo RPC integration. pin, fetch, and verify shards over the IPFS network.

auth

scrypt password hashing, admin sessions, API key authentication for protected routes.

rules engine

Firebase-style rules for access control. define who can read, write, and query.

┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

zdb up	start IPFS + ZDB daemons
zdb up --info	start and show system info
zdb down	stop all services
zdb status	check daemon status
zdb info	traffic, storage, memory, peers
zdb logs	tail daemon logs
zdb install	install or update ZDB

PORT	server port (default: 8899)
IPFS_API_URL	Kubo API endpoint (default: http://localhost:5001)
ZDB_ENCRYPT	enable AES-256-GCM encryption (default: 1)
ZDB_IPFS_ONLY	read data exclusively from IPFS (default: 0)
ADMIN_KEY	admin API authentication key