mirror of
https://github.com/orbitdb/orbitdb.git
synced 2025-05-23 15:26:36 +00:00
132 lines
4.0 KiB
Markdown
132 lines
4.0 KiB
Markdown
# orbit-db
|
|
|
|
> Distributed, peer-to-peer database on IPFS.
|
|
|
|
`orbit-db` is a serverless, distributed, peer-to-peer database. `orbit-db` uses [IPFS](https://ipfs.io) as its data storage and [IPFS Pubsub](https://github.com/ipfs/go-ipfs/blob/master/core/commands/pubsub.go) to automatically sync databases with peers. It's an eventually consistent database that uses [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type) 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)
|
|
- **Counters**
|
|
|
|
This is the Javascript implementation and it works both in **Node.js** and **Browsers**.
|
|
|
|
[](https://badge.fury.io/js/orbit-db)
|
|
[](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)
|
|
|
|
## Usage
|
|
```
|
|
npm install orbit-db ipfs-api
|
|
```
|
|
|
|
```javascript
|
|
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](https://github.com/haadcode/orbit-db/blob/master/API.md) for the full documentation.
|
|
|
|
- [Getting Started](https://github.com/haadcode/orbit-db/blob/master/API.md#getting-started)
|
|
- [orbitdb](https://github.com/haadcode/orbit-db/blob/master/API.md#orbitdb)
|
|
- [kvstore(name)](https://github.com/haadcode/orbit-db/blob/master/API.md#kvstorename)
|
|
- [eventlog(name)](https://github.com/haadcode/orbit-db/blob/master/API.md#eventlogname)
|
|
- [feed(name)](https://github.com/haadcode/orbit-db/blob/master/API.md#feedname)
|
|
- [counter(name)](https://github.com/haadcode/orbit-db/blob/master/API.md#countername)
|
|
- [disconnect()](https://github.com/haadcode/orbit-db/blob/master/API.md#disconnect)
|
|
- [events](https://github.com/haadcode/orbit-db/blob/master/API.md#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
|
|
```
|
|
|
|
<img src="https://raw.githubusercontent.com/haadcode/orbit-db/feat/ipfs-pubsub/screenshots/orbit-db-demo1.gif" width="33%">
|
|
|
|
Check the code in [examples/browser/index.js](https://github.com/haadcode/orbit-db/blob/master/examples/browser/index.js).
|
|
|
|
### Node.js example
|
|
|
|
```
|
|
npm run examples:node
|
|
```
|
|
|
|
<img src="https://raw.githubusercontent.com/haadcode/orbit-db/feat/ipfs-pubsub/screenshots/orbit-db-demo3.gif" width="66%">
|
|
|
|
**Eventlog**
|
|
|
|
Check the code in [examples/eventlog.js](https://github.com/haadcode/orbit-db/blob/master/examples/eventlog.js) and run it with:
|
|
```
|
|
LOG=debug node examples/eventlog.js
|
|
```
|
|
|
|
**Key-Value**
|
|
|
|
Check the code in [examples/keyvalue.js](https://github.com/haadcode/orbit-db/blob/master/examples/keystore.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
|