42885b20a4
Use latest store modules from npm Update README Update docs Update examples Update benchmarks Update dependencies Add Getting Started guide Add new a screenshot Add a new live demo Add persistency tests for snapshot saving/loading and events Add network stress tests (but skip them by default as they're very heavy and lengthy) Add browser benchmarks Add log() alias for eventlog() database Add possibility to create database if it doesn't exist yet Add support for orbitdb addresses Add a test for starting replication when peers connect Add debug build Use IPFS nodeID as default user id Use ipfs-pubsub-room Handle closing of databases properly Handle cache errors Clean up tests, re-organize code files Clean up code style Support for CLI Remove obsolete scripts
orbit-db
A 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
- Log Database (append-only log)
- Feed (same as log database but entries can be removed)
- Document Store (store indexed JSON documents)
- Counters
This is the Javascript implementation and it works both in Node.js and Browsers.
To get started, try the OrbitDB CLI, read the Getting Started Guide or check Live demo 1 and Live demo 2!
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 -g
As a library
Install dependencies:
npm install orbit-db ipfs
Use it as a module:
const IPFS = require('ipfs')
const OrbitDB = require('orbit-db')
const ipfs = new IPFS()
ipfs.on('error', (e) => console.error(e))
ipfs.on('ready', async () => {
// Create a database
const orbitdb = new OrbitDB(ipfs)
const db = await orbitdb.log('database name')
// Add an entry to the database
const hash = await db.add('hello world')
// Get last 5 entries
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.
Examples
Install dependencies
git clone https://github.com/orbitdb/orbit-db.git
cd orbit-db
npm install
Browser example
npm run build
npm run examples: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
More examples at examples.
Development
Run Tests
npm test
Build
npm run build
Benchmark
node benchmarks/benchmark-add.js
Logging
To enable OrbitDB's logging output, set a global ENV variable called LOG to debug,warn or error:
LOG=debug node <file>
Background
OrbitDB uses an append-only log as its operations log, implemented in ipfs-log.
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/.
TODO:
- list of modules used
- orbit-db-pubsub
- crdts
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.
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 ©️ 2017 Haadcode