orbit-db/README.md

orbit-db

Distributed, peer-to-peer database for the decentralized web.

orbit-db is a serverless, distributed, peer-to-peer database. orbit-db 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 orbit-db and excellent choice for offline-first applications.

Data in orbit-db can be stored in a

• Key-Value Store
• Eventlog (append-only log)
• Feed (add and remove log)
• Documents (indexed by custom fields)
• Counters

This is the Javascript implementation and it works both in Node.js and Browsers.

To get started, try out the OrbitDB CLI or check the live demo!

Table of Contents

• Usage
• API
• Examples
• Development
• Background
• Contributing
• License

Usage

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

Library

orbit-db can be used in your Javascript programs as a module. This works both in Node.js as well as in the browsers.

To start, install the module with:

npm install orbit-db ipfs-daemon

const IPFS = require('ipfs-daemon/src/ipfs-node-daemon')
const OrbitDB = require('orbit-db')

const ipfs = new IPFS()

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

  const db = orbitdb.eventlog("feed name")

  db.add("hello world")
    .then(() => {
      const latest = db.iterator({ limit: 5 }).collect()
      console.log(JSON.stringify(latest, null, 2))
    })  
})

For more details, see examples for kvstore, eventlog, feed, docstore and counter.

API

See API documentation for the full documentation.

• Getting Started
• orbitdb
  • kvstore(name)
  • eventlog(name)
  • feed(name)
  • docstore(name, options)
  • counter(name)
  • disconnect()
  • events

Examples

Install dependencies

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

Browser example

npm run build:examples
npm run examples:browser

Check the code in examples/browser/browser.html.

Node.js example

npm run examples:node

Eventlog

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

LOG=debug node examples/eventlog.js

Key-Value

Check the code in examples/keyvalue.js and run it with:

LOG=debug node examples/keyvalue.js

Development

Run Tests

npm test

Build

npm run build

Benchmark

node examples/benchmark.js

Background

Check out a visualization of the data flow at https://github.com/haadcode/proto2.

TODO

• list of modules used
• orbit-db-pubsub
• crdts
• ipfs-log

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.

License

MIT ©️ 2016 Haadcode