# OrbitDB — Peer-to-Peer Serverless Database on IPFS

> OrbitDB is a serverless, distributed, peer-to-peer database built on IPFS and CRDTs. It enables offline-first applications where data syncs automatically when peers connect without any central server.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# OrbitDB — Peer-to-Peer Serverless Database on IPFS

## Quick Use
```bash
npm install @orbitdb/core helia
# In your app:
import { createOrbitDB } from '@orbitdb/core'
const orbitdb = await createOrbitDB({ ipfs })
const db = await orbitdb.open('my-database', { type: 'documents' })
await db.put({ _id: '1', name: 'hello' })
```

## Introduction
OrbitDB is a peer-to-peer database that uses IPFS for data storage and libp2p for networking. It requires no central server — data replicates automatically between peers using CRDTs to resolve conflicts, making it ideal for decentralized and offline-first applications.

## What OrbitDB Does
- Provides multiple database types: key-value, documents, events log, and feed
- Replicates data peer-to-peer over IPFS without central coordination
- Resolves conflicts automatically using CRDTs (no manual merge needed)
- Works offline and syncs when connectivity is restored
- Supports access control via cryptographic identities

## Architecture Overview
OrbitDB stores data as an append-only operation log on IPFS. Each database is a CRDT that merges concurrent writes deterministically. The log entries reference each other via content-addressed IPFS hashes forming a DAG. Libp2p handles peer discovery and pub/sub messaging to notify peers of new entries. Each peer maintains a local copy and can reconstruct the full state from the operation log.

## Self-Hosting & Configuration
- Install via npm alongside a Helia (IPFS) node instance
- No server required — each application instance is a peer
- Configure IPFS swarm addresses for peer discovery on custom networks
- Set access controller to restrict who can write (default: creator only)
- Persist data locally using the default LevelDB-backed blockstore

## Key Features
- Fully decentralized with no single point of failure
- Offline-first: works without internet, syncs when peers reconnect
- Multiple database models cover common use cases (docs, KV, log)
- Content-addressed storage ensures data integrity via IPFS
- Identity-based access control using public key cryptography

## Comparison with Similar Tools
- **GunDB** — Also P2P but uses its own protocol; OrbitDB leverages the IPFS ecosystem
- **PouchDB/CouchDB** — Sync-capable but relies on a central CouchDB server for replication
- **Ceramic** — Decentralized data streams focused on identity; OrbitDB is general-purpose
- **Automerge** — CRDT library without built-in networking; OrbitDB bundles storage and sync

## FAQ
**Q: Do I need to run an IPFS node?**
A: Yes, OrbitDB requires a Helia (JS-IPFS) instance, but it runs in-process with your app.

**Q: How does access control work?**
A: Each database has an access controller that checks the writer's cryptographic identity before accepting writes.

**Q: Can OrbitDB scale to many peers?**
A: It works well for dozens to hundreds of peers. Very large networks may need topic sharding for pub/sub efficiency.

**Q: Is data encrypted?**
A: Data on IPFS is content-addressed but not encrypted by default. You can encrypt payloads at the application layer before writing.

## Sources
- https://github.com/orbitdb/orbitdb
- https://orbitdb.org

---
Source: https://tokrepo.com/en/workflows/orbitdb-peer-peer-serverless-database-ipfs-7cdd9273
Author: Script Depot