OrbitDB: Peer-to-Peer Databases for the Decentralized Web

Introduction

OrbitDB is a serverless, distributed, peer-to-peer database that empowers developers to build applications for the decentralized web. It utilizes IPFS for robust data storage and Libp2p Pubsub to facilitate automatic synchronization across peers. At its core, OrbitDB is an eventually consistent database, employing Merkle-CRDTs to manage conflict-free database writes and merges. This architecture makes it particularly well-suited for p2p and decentralized applications, blockchain solutions, and local-first web experiences.

OrbitDB offers a variety of database types to cater to different data models and use cases:

Events: An immutable, append-only log with traversable history, ideal for "latest N" scenarios or message queues.
Documents: A document database for storing JSON documents, indexable by a specified key, useful for search indices or version control.
Key-Value: A straightforward key-value database.
Key-Value Indexed: A key-value database with data indexed in a Level key-value database.

All these databases are built upon OrbitDB's OpLog, an immutable, cryptographically verifiable, operation-based Conflict-Free Replicated Data Structure (CRDT) for distributed systems.

Installation

To get started with OrbitDB, install it and its dependencies using npm:

npm install @orbitdb/core helia

For browser environments, OrbitDB can also be loaded via a <script> tag, making OrbitDB available as a global namespace.

Examples

Here's a quick example demonstrating how to set up an IPFS instance with Libp2p and open an OrbitDB database:

import { createHelia } from 'helia'
import { createOrbitDB } from '@orbitdb/core'
import { gossipsub } from "@chainsafe/libp2p-gossipsub";
import { identify } from "@libp2p/identify";
import { createLibp2p } from 'libp2p'

const Libp2pOptions = {
  services: {
    pubsub: gossipsub({
      // neccessary to run a single peer
      allowPublishToZeroTopicPeers: true
    }),
    identify: identify()
  }
}

;(async function () {
  const libp2p = await createLibp2p({ ...Libp2pOptions })
  const ipfs = await createHelia({libp2p})
  const orbitdb = await createOrbitDB({ ipfs })

  // Create / Open a database. Defaults to db type "events".
  const db = await orbitdb.open("hello")
  
  const address = db.address
  console.log(address)
  // "/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To"
  // The above address can be used on another peer to open the same database

  // Listen for updates from peers
  db.events.on("update", async entry => {
    console.log(entry)
    const all = await db.all()
    console.log(all)
  })

  // Add an entry
  const hash = await db.add("world")
  console.log(hash)

  // Query
  for await (const record of db.iterator()) {
    console.log(record)
  }
  
  await db.close()
  await orbitdb.stop()
  await ipfs.stop()
})()

For more detailed examples and configurations, refer to the official @orbitdb/quickstart module.

Why Use OrbitDB?

OrbitDB stands out as a powerful solution for building decentralized applications due to several key features:

Decentralized and Serverless: Eliminates the need for a central server, making applications more resilient and censorship-resistant.
Peer-to-Peer Synchronization: Automatically syncs data between peers using Libp2p Pubsub, ensuring data availability and consistency across the network.
Conflict-Free Data Management: Leverages Merkle-CRDTs to handle concurrent writes and merges without conflicts, simplifying data management in distributed environments.
Flexible Data Models: Offers various database types, including event logs, document stores, and key-value stores, to suit diverse application requirements.
IPFS Integration: Utilizes IPFS for content-addressed data storage, providing robust and persistent data infrastructure.
Cross-Platform Compatibility: Works seamlessly in both browsers and Node.js environments, supporting Linux, OS X, and Windows.