GUN — Decentralized Real-Time Graph Database

Introduction

GUN is a decentralized, peer-to-peer graph database that syncs data across browsers and servers in real time. It works offline by default and merges changes automatically when peers reconnect, making it a foundation for apps that need resilience without relying on a single backend.

What GUN Does

• Stores graph-structured data that syncs across peers in real time
• Works fully offline and merges changes on reconnect via CRDTs
• Runs in browsers, Node.js, and React Native without a central server
• Provides built-in user authentication and data encryption (SEA module)
• Supports pub/sub style reactive data subscriptions

Architecture Overview

GUN uses a directed graph model where every node is identified by a soul (unique key). Data propagates via a gossip protocol over WebSockets, WebRTC, or any custom transport. Conflict resolution relies on a HAM (Hypothetical Amnesia Machine) CRDT algorithm that deterministically merges concurrent writes without coordination. Peers can be browsers, relay servers, or both.

Self-Hosting & Configuration

• Run a relay peer with npx gun or add GUN as Express/Koa middleware
• Relay peers are optional — browsers can sync directly via WebRTC
• Persistence is pluggable: RAD (Radix Storage Adapter) writes to disk, S3, or IPFS
• The SEA (Security, Encryption, Authorization) module handles user key pairs
• Configure peer URLs at instantiation to point at your relay servers

Key Features

• No single point of failure; any peer can join or leave the network
• HAM-based CRDT ensures deterministic conflict resolution without locking
• Graph traversal API supports nested references and back-links
• End-to-end encryption via the SEA module for private user data
• Lightweight — the core library is under 10 KB gzipped

Comparison with Similar Tools

• Firebase Realtime Database — cloud-managed and centralized; GUN is fully decentralized
• CouchDB + PouchDB — document-based with server-centric replication; GUN uses peer-to-peer gossip
• OrbitDB — built on IPFS; GUN has its own transport layer and works in plain browsers
• Automerge — CRDT library without a built-in database; GUN provides storage and networking together

FAQ

Q: Do I need a server to use GUN? A: No. Browsers can sync directly via WebRTC. A relay server helps with NAT traversal and persistence but is not mandatory.

Q: How does conflict resolution work? A: GUN uses the HAM algorithm, a state-based CRDT that picks a deterministic winner for each field based on timestamps and state vectors.

Q: Is the data encrypted by default? A: Not by default. Enable the SEA module to add user-level key pairs and field-level encryption.

Q: Can GUN handle large datasets? A: It works best for real-time collaborative data. For analytical queries on large volumes, a traditional database is more appropriate.

Sources

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