OrbitDB

OrbitDB is a serverless, distributed, peer-to-peer database. OrbitDB uses IPFS as its data storage and Libp2p Pubsub to automatically sync databases with peers. It's an eventually consistent database that uses Merkle-CRDTs for conflict-free database writes and merges making OrbitDB an excellent choice for p2p and decentralized apps, blockchain applications and local-first web applications.

Test it live at Live demo 1, Live demo 2, or P2P TodoMVC app!

OrbitDB provides various types of databases for different data models and use cases:

• events: an immutable (append-only) log with traversable history. Useful for "latest N" use cases or as a message queue.
• documents: a document database to which JSON documents can be stored and indexed by a specified key. Useful for building search indices or version controlling documents and data.
• keyvalue: a key-value database just like your favourite key-value database.
• keyvalue-indexed: key-value data indexed in a Level key-value database.

All databases are implemented on top of ipfs-log, an immutable, cryptographically verifiable, operation-based conflict-free replicated data structure (CRDT) for distributed systems. ipfs-log is formalized in the paper Merkle-CRDTs. You can also easily extend OrbitDB by implementing and using a custom data model benefitting from the same properties as the default data models provided by the underlying Merkle-CRDTs.

Project status & support

• Status: in active development
• Compatible with ipfs-core versions >= 0.18.0

NOTE! js-ipfs and related packages are now superseded by IPFS's Helia project and are no longer being maintained. As part of this migration, OrbitDB will be switching to Helia.

NOTE! OrbitDB is alpha-stage software. It means OrbitDB hasn't been security audited and programming APIs and data formats can still change. We encourage you to reach out to the maintainers if you plan to use OrbitDB in mission critical systems.

This is the Javascript implementation and it works both in Browsers and Node.js with support for Linux, OS X, and Windows. Node version 16 is supported.

A Go implementation is developed and maintained by the Berty project at berty/go-orbit-db.

Table of Contents

• Installation
• Usage
• API
• Database browser UI
• Examples
  • Install dependencies
  • Browser example
  • Node.js example
• Development
  • Run Tests
  • Build
  • Benchmark
  • Logging
• Frequently Asked Questions
  • Are there implementations in other languages?
• Contributing
• Sponsors
• License

Installation

npm install orbit-db

Usage

If you're using orbit-db to develop browser or Node.js applications, use it as a module with the javascript instance of IPFS.

import IPFS from 'ipfs-core'
import OrbitDB from 'orbit-db'

;(async function () {
  const ipfs = await IPFS.create()
  const orbitdb = await OrbitDB({ ipfs })

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

  // Listen for updates from peers
  db.events.on("update", 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()
})()

Use the Getting Started guide for an initial introduction to OrbitDB and you can find more advanced topics covered in our docs.

API

See API.md for the full documentation.

Examples

Install dependencies

git clone https://github.com/orbitdb/orbit-db.git
cd orbit-db
npm install

Some dependencies depend on native addon modules, so you'll also need to meet node-gyp's installation prerequisites. Therefore, Linux users may need to

make clean-dependencies && make deps

to redo the local package-lock.json with working native dependencies.

Browser example

npm install # if not yet installed
make build
npm run examples:browser # if browser isn't opening, open examples/browser/browser.html in your browser

Using Webpack:

npm install # if not yet installed
make build
npm run examples:browser-webpack # if browser isn't opening, open examples/browser/browser-webpack-example/index.html in your browser

Check the code in examples/browser/browser.html and try the live example.

Node.js example

npm run examples:node

Eventlog

See the code in examples/eventlog.js and run it with:

node examples/eventlog.js

Development

Run Tests

npm run test

Build

npm run build

Benchmark

node benchmarks/benchmark-add.js

See benchmarks/ for more benchmarks.

Logging

To enable OrbitDB's logging output, set a global ENV variable called LOG to debug,warn or error:

LOG=debug node <file>

Frequently Asked Questions

We have an FAQ! Go take a look at it. If a question isn't there, open an issue and suggest adding it. We can work on the best answer together.

Are there implementations in other languages?

Yes! Take a look at these implementations:

• Golang: berty/go-orbit-db
• Python: orbitdb/py-orbit-db-http-client

The best place to find out what is out there and what is being actively worked on is likely by asking in the Matrix. If you know of any other repos that ought to be included in this section, please open a PR and add them.

Contributing

Take a look at our organization-wide Contributing Guide. You'll find most of your questions answered there. Some questions may be answered in the FAQ, as well.

If you want to code but don't know where to start, check out the issues labelled "help wanted".

Sponsors

The development of OrbitDB has been sponsored by:

• Protocol Labs
• Haja Networks
• Maintainer Mountaineer
• OrbitDB Open Collective

If you want to sponsor developers to work on OrbitDB, please reach out to @haadcode.

License

MIT © 2015-2023 Protocol Labs Inc., Haja Networks Oy, OrbitDB Community