Repository files navigation

OrbitDB is aserverless, distributed, peer-to-peer database. OrbitDB usesIPFS as its data storage andLibp2p Pubsub to automatically sync databases with peers. It's an eventually consistent database that usesMerkle-CRDTs for conflict-free database writes and merges making OrbitDB an excellent choice for p2p and decentralized apps, blockchain applications andlocal-first web applications.

OrbitDB provides various types of databases for different data models and use cases:

• events: an immutable (append-only) log with traversable history. Useful for"latest N" use cases or as a message queue.
• documents: 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.
• keyvalue: a key-value database just like your favourite key-value database.
• keyvalue-indexed: key-value data indexed in a Level key-value database.

All databases areimplemented on top of OrbitDB'sOpLog, an immutable, cryptographically verifiable, operation-based conflict-free replicated data structure (CRDT) for distributed systems. OpLog is formalized in the paperMerkle-CRDTs. You can also easily extend OrbitDB byimplementing and using a custom data model benefitting from the same properties as the default data models provided by the underlying Merkle-CRDTs.

This is the Javascript implementation and it works both inBrowsers andNode.js with support for Linux, OS X, and Windows.

A Go implementation is developed and maintained by theBerty project atberty/go-orbit-db.

Install OrbitDB and its dependencies:

npm install @orbitdb/core helia

OrbitDB can be loaded in the browser using the distributed js file with the<script/> tag. OrbitDB is the global namespace and all external functions are available via this namespace:

<script>/path/to/orbitdb.min.js</script>

If you want to get up and running with OrbitDB quickly, install and follow the instructions in the@orbitdb/quickstart module.

If you're using@orbitdb/core to developbrowser orNode.js applications, use it as a module with the javascript instance of IPFS.

import{createHelia}from'helia'import{createOrbitDB}from'@orbitdb/core'import{gossipsub}from"@chainsafe/libp2p-gossipsub";import{identify}from"@libp2p/identify";import{createLibp2p}from'libp2p'constLibp2pOptions={services:{pubsub:gossipsub({// neccessary to run a single peerallowPublishToZeroTopicPeers:true}),identify:identify()}};(asyncfunction(){constlibp2p=awaitcreateLibp2p({ ...Libp2pOptions})constipfs=awaitcreateHelia({libp2p})constorbitdb=awaitcreateOrbitDB({ ipfs})// Create / Open a database. Defaults to db type "events".constdb=awaitorbitdb.open("hello")constaddress=db.addressconsole.log(address)// "/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To"// The above address can be used on another peer to open the same database// Listen for updates from peersdb.events.on("update",asyncentry=>{console.log(entry)constall=awaitdb.all()console.log(all)})// Add an entryconsthash=awaitdb.add("world")console.log(hash)// Queryforawait(constrecordofdb.iterator()){console.log(record)}awaitdb.close()awaitorbitdb.stop()awaitipfs.stop()})()

To configure yourIPFS instance for persistency andLibp2p to connect to peers, seeCreating a Helia instance and theDefault Libp2p Configurations in@orbitdb/quickstart for examples.

Use theGetting Started guide for an initial introduction to OrbitDB.

You can find more advanced topics in ourdocs covering:

• Databases
• Storage
• Identities
• Access Controllers
• Connecting Peers
• Replication
• Oplog
• Encryption

Seehttps://api.orbitdb.org for the full API documentation.

npm runtest

npm run build

node benchmarks/orbitdb-events.js

Seebenchmarks/ for more benchmarks.

To build the API documentation, run:

npm run build:docs

Documentation is output to ./docs/api.

• Golang:berty/go-orbit-db
• Python:orbitdb/py-orbit-db-http-client

If you know of any other repos that ought to be included in this section, please open a PR and add them.

Take a look at our organization-wideContributing Guide. You'll find most of your questions answered there.

If you want to code but don't know where to start, check out the issues labelled"help wanted".

The development of OrbitDB has been sponsored by:

• Protocol Labs
• Haja Networks
• Maintainer Mountaineer
• OrbitDB Open Collective

If you want to sponsor developers to work on OrbitDB, please donate to ourOrbitDB Open Collective or reach out to@haadcode.

MIT © 2015-2023 Protocol Labs Inc., Haja Networks Oy, OrbitDB Community