orbitdbOrbitDB
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. If none of the OrbitDB database types match your needs and/or you need case-specific functionality, you can easily implement and use a custom database store of your own.
Project status & support
Status: in active development
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 and OS X (Windows is not supported yet). The minimum required version of Node.js is now 8.6.0 due to the usage of ... spread syntax. LTS versions (even numbered versions 8, 10, etc) are preferred.
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.
Community Calls
We also have regular community calls, which we announce in the issues in the @orbitdb welcome repository. Join us!
Table of Contents
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 -gModule with IPFS Instance
If you're using orbitd-db to develop browser or Node.js applications, use it as a module with the javascript instance of IPFS
Install dependencies:
npm install orbit-db ipfsconst 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 specified 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 = await OrbitDB.createInstance(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-http-clientconst IpfsClient = require('ipfs-http-client')
const OrbitDB = require('orbit-db')
const ipfs = IpfsClient('localhost', '5001')
const orbitdb = await OrbitDB.createInstance(ipfs)
const db = await orbitdb.log('hello')
// Do something with your db.
// Of course, you may want to wrap these in an async function.API
See API.md for the full documentation.
Examples
Install dependencies
git clone https://github.com/orbitdb/orbit-db.git
cd orbit-db
npm installYou'll also need babel and webpack, if you don't have them installed already:
npm install --global babel-cli
npm install --global webpackSome 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 && maketo redo the local package-lock.json with working native dependencies.
Browser example
In macOS:
npm run build
npm run examples:browser-macosIn 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.jsMore examples at examples.
Packages
OrbitDB uses the following modules:
- ipfs
- ipfs-log
- ipfs-pubsub-room
- crdts
- orbit-db-cache
- orbit-db-pubsub
- orbit-db-identity-provider
- orbit-db-access-controllers
OrbitDB Store Packages
- orbit-db-store
- orbit-db-eventstore
- orbit-db-feedstore
- orbit-db-kvstore
- orbit-db-docstore
- orbit-db-counterstore
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/.
Community-maintained Typescript typings are available here: https://github.com/orbitdb/orbit-db-types
Development
Run Tests
npm testBuild
npm run buildBenchmark
node benchmarks/benchmark-add.jsSee 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.
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.
As far as code goes, 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 Gitter, or in the issues section.
We also have regular community calls, which we announce in the issues in the @orbitdb welcome repository. Join us!
If you want to code but don't know where to start, check out the issues labelled "help wanted".
Please note that we have a Code of Conduct, and that all activity in the @orbitdb organization falls under it. Read it when you get the chance, as being part of this community means that you agree to abide by it. Thanks.
Sponsors
The development of OrbitDB has been sponsored by:
If you want to sponsor developers to work on OrbitDB, please reach out to @haadcode.
License
MIT © 2015-2018 Protocol Labs Inc., Haja Networks Oy
