GunDB — Decentralized Real-Time Graph Database

Introduction

GunDB is an open-source, decentralized graph database protocol that enables peer-to-peer data synchronization with no single point of failure. It works in browsers, on servers, and on mobile devices, providing offline-first real-time data without relying on a central backend.

What GunDB Does

• Provides a decentralized graph database with automatic conflict resolution via CRDTs
• Syncs data peer-to-peer across browsers, Node.js servers, and mobile devices in real time
• Operates offline-first so apps continue working without connectivity
• Offers built-in end-to-end encryption via the SEA (Security, Encryption, Authorization) module
• Scales horizontally by adding relay peers rather than upgrading a single server

Architecture Overview

GunDB uses a DAG (directed acyclic graph) storage model with a custom CRDT-based conflict resolution algorithm called HAM (Hypothetical Amnesia Machine). Each node stores key-value pairs with vector-clock-style metadata. Data propagates through a gossip protocol between peers, with relay servers acting as optional always-on nodes to improve availability. The storage adapter layer supports pluggable backends including localStorage, IndexedDB, Radisk (file-based), and S3.

Self-Hosting & Configuration

• Install via npm: npm install gun and start a relay with node node_modules/gun/examples/http.js
• Configure relay peers by passing a list of URLs to the Gun constructor
• Deploy behind a reverse proxy with WebSocket support for production use
• Use environment variables or constructor options to set the storage adapter and file path
• Enable SEA for user authentication and encrypted data at rest

Key Features

• Zero-config peer-to-peer sync that works in the browser with no server required
• Built-in user system with public/private key pairs for decentralized authentication
• Reactive data subscriptions with .on() for live-updating UIs
• Pluggable storage adapters for persistence across environments
• Sub-millisecond local reads with eventual consistency across the network

Comparison with Similar Tools

• Firebase — managed cloud service with vendor lock-in; GunDB is fully decentralized and self-hostable
• PouchDB/CouchDB — document-oriented sync; GunDB uses a graph model with finer-grained conflict resolution
• OrbitDB — built on IPFS with heavier infrastructure; GunDB runs directly in the browser with no external daemon
• Automerge — CRDT library without built-in networking; GunDB bundles sync, storage, and encryption together
• Supabase Realtime — centralized Postgres-based; GunDB requires no central database server

FAQ

Q: Does GunDB guarantee strong consistency? A: No. GunDB provides eventual consistency via CRDTs. All peers converge to the same state, but there is no global transaction ordering.

Q: Can I use GunDB in production? A: Yes. Several apps use GunDB in production. Deploy multiple relay peers behind a load balancer for redundancy.

Q: How large can the dataset be? A: Each peer only loads data it subscribes to, so the total dataset can be large. Individual peers should keep active working sets manageable for their storage backend.

Q: Does GunDB work without any server? A: Yes. Two browsers on the same network can sync directly via WebRTC. Relay servers improve availability for users behind NATs.

Sources

• https://github.com/amark/gun
• https://gun.eco/docs