217 lines
7.0 KiB
Markdown
217 lines
7.0 KiB
Markdown
# OrbitDB
|
|
|
|
> Distributed, peer-to-peer database on IPFS.
|
|
|
|
[](https://circleci.com/gh/haadcode/orbit-db)
|
|
[](https://waffle.io/haadcode/orbit?source=haadcode%2Forbit-db,haadcode%2Forbit-db-counterstore,haadcode%2Forbit-db-eventstore,haadcode%2Forbit-db-feedstore,haadcode%2Forbit-db-kvstore,haadcode%2Forbit-db-store,haadcode%2Fipfs-log)
|
|
|
|
## Introduction
|
|
|
|
`orbit-db` is a distributed, peer-to-peer database for applications. You can use `orbit-db` for different data models: **Key-Value Store**, **Eventlog** (append-only log), **Feed** (add and remove log) and **Counters**. The database gets replicated automatically with peers who are connected to the same database.
|
|
|
|
This is the Javascript implementation and it works both in **Node.js** and **Browsers**.
|
|
|
|
- Client-side database to be embedded in Javascript applications
|
|
- Stores all data in IPFS
|
|
- Aggregation happens on client side and data is eventually consistent
|
|
- Designed to work offline first
|
|
|
|
Check out a visualization of the data flow at https://github.com/haadcode/proto2
|
|
|
|
Live demo: http://celebdil.benet.ai:8080/ipfs/Qmezm7g8mBpWyuPk6D84CNcfLKJwU6mpXuEN5GJZNkX3XK/
|
|
|
|
|
|
|
|
**NOTE: the README can be out of date, I'm working to get up to date. If you find a problem, please open an issue or a PR.**
|
|
|
|
_Currently requires [orbit-server](https://github.com/haadcode/orbit-server) for pubsub communication. This will change in the future as soon as IPFS provides pubsub._
|
|
|
|
## Install
|
|
```
|
|
npm install orbit-db
|
|
```
|
|
|
|
## Data stores
|
|
|
|
Currently available data stores:
|
|
|
|
- [orbit-db-kvstore](https://github.com/haadcode/orbit-db-kvstore)
|
|
- [orbit-db-eventstore](https://github.com/haadcode/orbit-db-eventstore)
|
|
- [orbit-db-feedstore](https://github.com/haadcode/orbit-db-feedstore)
|
|
- [orbit-db-counterstore](https://github.com/haadcode/orbit-db-counterstore)
|
|
|
|
## Usage
|
|
|
|
```javascript
|
|
const OrbitDB = require('orbit-db')
|
|
const IPFS = require('ipfs')
|
|
|
|
OrbitDB.connect('178.62.241.75:3333', 'tester', null, new IPFS(), { allowOffline: true })
|
|
.then((orbitdb) => {
|
|
const kvstore = orbitdb.kvstore('db name')
|
|
const events = orbitdb.eventlog('db name')
|
|
const feed = orbitdb.feed('db name')
|
|
const counters = orbitdb.counter('db name')
|
|
|
|
kvstore.put('key1', 'hello1')
|
|
.then(() => kvstore.get('key1'))
|
|
.then((value) => console.log(value)) // 'hello!'
|
|
})
|
|
```
|
|
|
|
Documentation for individual stores are WIP, please see each store's source code for available public methods.
|
|
|
|
## Examples
|
|
|
|
*To run the examples below, make sure to run a local [orbit-server](https://github.com/haadcode/orbit-server)*
|
|
|
|
### Browser examples
|
|
Build the examples:
|
|
```bash
|
|
npm install
|
|
npm run build:examples
|
|
```
|
|
|
|
Then open `examples/browser.html` or `examples/index.html`. See the full example [here](https://github.com/haadcode/orbit-db/blob/master/examples/browser/browser.html).
|
|
|
|
```html
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
</head>
|
|
<body>
|
|
<script type="text/javascript" src="../dist/orbitdb.min.js" charset="utf-8"></script>
|
|
<script type="text/javascript" src="../node_modules/logplease/dist/logplease.min.js" charset="utf-8"></script>
|
|
<script type="text/javascript" src="../node_modules/ipfs/dist/index.min.js" charset="utf-8"></script>
|
|
|
|
<script type="text/javascript">
|
|
const ipfs = window.Ipfs();
|
|
OrbitDB.connect('localhost:3333', 'user1', '', ipfs)
|
|
.then((orbit) => orbit.kvstore('test'))
|
|
.then((db) => db.put('hello', 'world'))
|
|
.then((res) => {
|
|
const result = db.get(key)
|
|
console.log(result)
|
|
})
|
|
</script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
### Node.js examples
|
|
|
|
Before running the examples, install dependencies with:
|
|
```
|
|
npm install
|
|
```
|
|
|
|
Key-Value store [example](https://github.com/haadcode/orbit-db/blob/master/examples/keyvalue.js):
|
|
```
|
|
node examples/keyvalue.js <host:port> <username> <channel> <key> <value>
|
|
```
|
|
|
|
Event log [example](https://github.com/haadcode/orbit-db/blob/master/examples/eventlog.js) (run several in separate shells):
|
|
```
|
|
node examples/eventlog.js <host:port> <username> <channel> <data> <interval in ms>
|
|
```
|
|
|
|
Benchmark writes:
|
|
```bash
|
|
node examples/benchmark.js <host:port> <username> <channel>;
|
|
```
|
|
|
|
## API
|
|
**NOTE: the API documentation is currently out of date. It will be updated soon!**
|
|
|
|
_See usage example below_
|
|
|
|
_OrbitDB calls its namespaces channels. A channel is similar to "table", "keyspace", "topic", "feed" or "collection" in other db systems._
|
|
|
|
connect(<host:port>, username, password)
|
|
|
|
channel(name, password)
|
|
|
|
.add(data: String) // Insert an event to a channel, returns <ipfs-hash> of the event
|
|
|
|
.iterator([options]) // Returns an iterator of events
|
|
|
|
// options : {
|
|
// gt: <ipfs-hash>, // Return events newer than <ipfs-hash>
|
|
// gte: <ipfs-hash>, // Return events newer then <ipfs-hash> (inclusive)
|
|
// lt: <ipfs-hash>, // Return events older than <ipfs-hash>
|
|
// lte: <ipfs-hash>, // Return events older than <ipfs-hash> (inclusive)
|
|
// limit: -1, // Number of events to return, -1 returns all, default 1
|
|
// reverse: true // Return items oldest first, default latest first
|
|
// }
|
|
|
|
.put(key, data: String) // Insert (key,value) to a channel
|
|
|
|
.get(key) // Retrieve value
|
|
|
|
.del({ key: <key or hash> }) // Remove entry
|
|
|
|
.delete() // Deletes the channel, all data will be "removed" (unassociated with the channel, actual data is not deleted from ipfs)
|
|
|
|
## Usage
|
|
```javascript
|
|
const async = require('asyncawait/async');
|
|
const ipfsAPI = require('ipfs-api');
|
|
const OrbitDB = require('orbit-db');
|
|
|
|
// local ipfs daemon
|
|
const ipfs = ipfsAPI();
|
|
|
|
async(() => {
|
|
// Connect
|
|
const orbit = await(OrbitClient.connect('localhost:3333', 'usernamne', '', ipfs));
|
|
|
|
/* Event Log */
|
|
const eventlog = orbit.eventlog('eventlog test');
|
|
const hash = await(eventlog.add('hello')); // <ipfs-hash>
|
|
|
|
// Remove event
|
|
await(eventlog.remove(hash));
|
|
|
|
// Iterator options
|
|
const options = { limit: -1 }; // fetch all messages
|
|
|
|
// Get events
|
|
const iter = eventlog.iterator(options); // Symbol.iterator
|
|
const next = iter.next(); // { value: <item>, done: false|true}
|
|
|
|
// OR:
|
|
// var all = iter.collect(); // returns all elements as an array
|
|
|
|
// OR:
|
|
// for(let i of iter)
|
|
// console.log(i.hash, i.item);
|
|
|
|
/* Delete database locally */
|
|
eventlog.delete();
|
|
|
|
/* KV Store */
|
|
const kvstore = orbit.kvstore('kv test');
|
|
await(kvstore.put('key1', 'hello world'));
|
|
kvstore.get('key1'); // returns "hello world"
|
|
await(kvstore.del('key1'));
|
|
})();
|
|
```
|
|
|
|
### Development
|
|
|
|
#### Run Tests
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Keep tests running while development:
|
|
```bash
|
|
mocha -w
|
|
```
|
|
|
|
#### Build distributables
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|