OrbitDB is a serverless, distributed, peer-to-peer database. OrbitDB uses IPFS as its data storage and IPFS Pubsub to automatically sync databases with peers. It's an eventually consistent database that uses CRDTs for conflict-free database merges making OrbitDB an excellent choice for decentralized apps (dApps), blockchain applications and offline-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:

log: an immutable (append-only) log with traversable history. Useful for "latest N" use cases or as a message queue.
feed: a mutable log with traversable history. Entries can be added and removed. Useful for *"shopping cart" type of use cases, or for example as a feed of blog posts or "tweets".
keyvalue: a key-value database just like your favourite key-value database.
docs: 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.
counter: Useful for counting events separate from log/feed data.

All databases are implemented on top of ipfs-log, an immutable, operation-based conflict-free replicated data structure (CRDT) for distributed systems.

Project status & support

This is the Javascript implementation and it works both in Browsers and Node.js with support for Linux and OS X (Windows is not supported yet). The minimum required version of Node.js is now 8.0.0. To use with older versions of Node.js, we provide an ES5-compatible build through the npm package, located in dist/es5/ when installed through npm.

Usage
API
Examples
Packages
Development
Contributing
License

Usage

Read the GETTING STARTED guide for a more in-depth tutorial and to understand how OrbitDB works.

CLI

For the CLI tool to manage orbit-db database, see OrbitDB CLI.

It can be installed from Npm with:

npm install orbit-db-cli -g

Module with IPFS Instance

If you're using orbitd-db to develop browser applications, use it as a module with the javascript instance of IPFS

Install dependencies:

npm install orbit-db ipfs

const IPFS = require('ipfs')
const OrbitDB = require('orbit-db')

// OrbitDB uses Pubsub which is an experimental feature
// and need to be turned on manually.
// Note that these options need to be passed to IPFS in
// all examples even if not specfied so.
const ipfsOptions = {
  EXPERIMENTAL: {
    pubsub: true
  }
}

// Create IPFS instance
const ipfs = new IPFS(ipfsOptions)

ipfs.on('error', (e) => console.error(e))
ipfs.on('ready', async () => {
  const orbitdb = new OrbitDB(ipfs)

  // Create / Open a database
  const db = await orbitdb.log('hello')
  await db.load()

  // Listen for updates from peers
  db.events.on('replicated', (address) => {
    console.log(db.iterator({ limit: -1 }).collect())
  })

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

  // Query
  const result = db.iterator({ limit: -1 }).collect()
  console.log(JSON.stringify(result, null, 2))
})

Module with IPFS Daemon

Alternatively, you can use ipfs-api to use orbit-db with a locally running IPFS daemon. Use this method if you're using orbitd-db to develop backend or desktop applications, eg. with Electron.

Install dependencies:

npm install orbit-db ipfs-api

const IpfsApi = require('ipfs-api')
const OrbitDB = require('orbit-db')

const ipfs = IpfsApi('localhost', '5001')
const orbitdb = new OrbitDB(ipfs)
const db = await orbitdb.log('hello')
...

API

See API.md for the full documentation.

constructor(ipfs, [directory], [options])

const orbitdb = new OrbitDB(ipfs)

Creates and returns an instance of OrbitDB. Use the optional directory argument to specify a path to be used for the database files (Default: './orbitdb'). In addition, you can use the optional options argument for further configuration. It is an object with any of these properties:

peerId (string): By default it uses the base58 string of the ipfs peer id.
keystore (Keystore Instance) : By default creates an instance of Keystore. A custom keystore instance can be used, see this for an example.

After creating an OrbitDB instance , you can access the different data stores. Creating a database instance, eg. with orbitdb.keyvalue(...), returns a Promise that resolves to a database instance.

For further details, see usage for kvstore, eventlog, feed, docstore and counter.

Custom Store Types

You can add custom store types to OrbitDB:

// define custom store type
class CustomStore extends DocumentStore {
  constructor (ipfs, id, dbname, options) {
    super(ipfs, id, dbname, options)
    this._type = CustomStore.type
  }

  static get type () {
    return 'custom'
  }
}

// add custom type to orbitdb
OrbitDB.addDatabaseType(CustomStore.type, CustomStore)

// instantiate custom store
let orbitdb = new OrbitDB(ipfs, dbPath)
let store = orbitdb.create(name, CustomStore.type)

Examples

Install dependencies

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

You'll also need babel and webpack, if you don't have them installed already:

npm install --global babel-cli
npm install --global webpack

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 && make

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

Browser example

In macOS:

npm run build
npm run examples:browser-macos

In Linux:

npm run build
npm run examples:browser-linux

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

More examples at examples.

Packages

OrbitDB uses the following modules:

OrbitDB Store Packages

To understand a little bit about the architecture, check out a visualization of the data flow at https://github.com/haadcode/proto2 or a live demo: http://celebdil.benet.ai:8080/ipfs/Qmezm7g8mBpWyuPk6D84CNcfLKJwU6mpXuEN5GJZNkX3XK/.

Development

Run Tests

npm 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>

Contributing

We would be happy to accept PRs! If you want to work on something, it'd be good to talk beforehand to make sure nobody else is working on it. You can reach us on IRC #orbitdb on Freenode, or in the comments of the issues section.

A good place to start are the issues labelled "help wanted" or the project's status board.

README.md

OrbitDB