orbit-db/README.md

orbit-db

Distributed, peer-to-peer database on IPFS.

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.

Table of Contents

• Usage
• API
• Examples
  • Install dependencies
  • Browser example
  • Node.js example
• Development
  • Run Tests
  • Build
  • Benchmark
• Background
• Contributing
• License

Usage

npm install orbit-db ipfs-api@https://github.com/haadcode/js-ipfs-api.git

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

const ipfs = IpfsApi('localhost', '5001')
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(latest.join("\n"))
  })

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/haadcode/orbit-db.git
cd orbit-db
npm install

Browser example

npm run build:examples
npm run examples:browser

Check the code in examples/browser/index.js.

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 or a live demo: http://celebdil.benet.ai:8080/ipfs/Qmezm7g8mBpWyuPk6D84CNcfLKJwU6mpXuEN5GJZNkX3XK/.

TODO

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

Contributing

Issues, comments, feedback, feature requests and PRs highly welcome!

License

MIT ©️ 2016 Haadcode