# GunDB — Decentralized Real-Time Graph Database

> GunDB is an open-source, peer-to-peer graph database that syncs data in real time across browsers and servers without a central authority.

## Install

Save as a script file and run:

# GunDB — Decentralized Real-Time Graph Database

## Quick Use
```bash
npm install gun
node -e "const Gun = require('gun'); const gun = Gun(); gun.get('hello').put({name: 'world'}); gun.get('hello').on(data => console.log(data));"
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-2f950de3
Author: Script Depot