GUN — Decentralized Real-Time Graph Database

Introduction

GUN is an open-source, decentralized, real-time graph database designed for peer-to-peer applications. It synchronizes data across connected peers automatically, works offline, and resolves conflicts using a CRDT-based algorithm. GUN enables developers to build collaborative and real-time applications without relying on a centralized database server.

What GUN Does

• Stores and syncs graph-structured data across browsers, Node.js servers, and mobile devices in real time
• Works offline and automatically reconciles changes when connectivity resumes using conflict-free replicated data types
• Provides a reactive API where data subscriptions fire callbacks whenever values change anywhere in the network
• Supports end-to-end encryption via the SEA (Security, Encryption, Authorization) module for user authentication and data privacy
• Scales horizontally by adding relay peers without requiring database sharding or cluster management

Architecture Overview

GUN uses a directed graph data model where every node is referenced by a unique soul (identifier). Data propagates through a gossip protocol: when a peer writes data, it broadcasts the change to connected peers, which in turn forward it to their peers. Conflict resolution relies on a state-based CRDT using Hypothetical Amnesia Machine (HAM), which deterministically picks the correct value based on vector timestamps. Storage adapters (localStorage, IndexedDB, Radix on disk, S3) handle persistence at each peer, while relay servers provide NAT traversal and message forwarding without owning the data.

Self-Hosting & Configuration

• Run a relay peer with npx gun or deploy a Node.js server that instantiates GUN with file or Radix storage
• Configure peer connections by passing an array of relay URLs when initializing the GUN instance
• Enable the SEA module for user authentication and encrypted data by importing gun/sea
• Set up Radix Adapter (RAD) for efficient disk-based storage on relay servers handling large datasets
• Deploy multiple relay peers behind a load balancer for redundancy; each peer independently syncs the full graph

Key Features

• Fully decentralized with no single point of failure; any peer can join or leave without data loss
• Offline-first design with automatic sync and CRDT-based conflict resolution
• Sub-millisecond local reads with reactive subscriptions for real-time UI updates
• Built-in SEA module for user authentication, data signing, and end-to-end encryption
• Runs in browsers, Node.js, React Native, and Electron with the same API

Comparison with Similar Tools

• Firebase Realtime Database — centralized and proprietary; GUN is decentralized and open source
• CouchDB / PouchDB — document-oriented with sync; GUN uses a graph model and gossip-based replication
• Yjs — CRDT library for collaborative editing; GUN is a full database with persistence and auth
• OrbitDB — IPFS-based decentralized database; GUN uses its own gossip protocol and does not require IPFS
• Automerge — CRDT library focused on JSON documents; GUN provides a complete database layer with built-in networking

FAQ

Q: How large can a GUN database grow? A: Individual peers can store as much as their storage backend allows. The Radix adapter on Node.js handles datasets in the hundreds of gigabytes efficiently by partitioning data on disk.

Q: Is GUN suitable for production use? A: Yes. GUN has been used in production applications handling real-time collaboration, chat, and IoT data for several years.

Q: How does GUN handle authentication? A: The SEA module provides public-key cryptography for user accounts. Users create keypairs, and data can be signed and encrypted so only authorized peers can read or write specific nodes.

Q: Does GUN work without relay servers? A: GUN can work with direct peer-to-peer connections using WebRTC, but relay servers help with NAT traversal and act as always-on peers for data availability.

Sources

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