OrbitDB - Peer to Peer, Serverless, Distributed Database for Blockchain Applications.

OrbitDB - Peer to Peer, Serverless, Distributed Database for Blockchain Applications.

Ernest Obot's photo
Ernest Obot
·Nov 30, 2021·

7 min read

Subscribe to my newsletter and never miss my upcoming articles

Table of contents

  • What is OrbitDB

Hello World!

Today you are going to learn something new in the world of blockchain. We are going to learn about OrbitDb. Perhaps you have been developing your dApps and storing data on ethereum, well that's fine. I don't dispute that fact. What if you wanted to store a large data or group of data or collection of data on ethereum dApps, you will see that it will cost a lot of gas. That is when OrbotDb comes into rescue.

Another problem is, what if you want to build a dApps (e.g Decentralize Mail Software, blogs, eCommerce applications, etc ) that requires big data or huge data storage and processing, storing your data on ethereum blockchain might not be suitable as it will cost you expensive gas price.

What is OrbitDB

Here’s the definition according to the OrbitDB project page:

“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.”

That’s a very technical definition, isn’t it? Well, let’s break it down further to understand better:

  • OrbitDB is serverless, which means you don’t need to maintain a database server when using OrbitDB, unlike other database software. It’s provided as a module for various programming languages.

  • OrbitDB is distributed; it is designed as a peer-to-peer database with no centralized server.

  • OrbitDB uses IPFS as a storage system. OrbitDB acts as a layer between the IPFS and programming interface.

  • OrbitDB is a peer-to-peer database, and to synchronize the changes in the peer to other peers, it uses IPFS publish/subscribe system to communicate with other peers.

  • OrbitDB uses the eventual consistency model; it’s the consistency model in which the latest updated version of the data item is returned to the user, maintaining the availability and consistency of data. To achieve this eventual consistency, OrbitDB uses Conflict-free Replicated Data Types (CRDTs).

  • OrbitDB is packaged as a Node.js library. JavaScript was chosen because of its popularity and ubiquity in the programming community, and for its interoperability with the JavaScript implementation of IPFS, called js-ipfs.

Installing OrbitDB

OrbitDB is a serverless application, so you do not need to run a server as we do for other databases like MySQL. However, we require IPFS in our system to use OrbitDB because IPFS is used as a file system to store records.

Let’s install OrbitDB in our application. Here’s the command to install OrbitDB and IPFS in our project:

npm install orbit-dbipfs-api

You can perform this installation in your dApp project.

Once installed, you can use the following code to connect to the IPFS and create an OrbitDB data store:

const IPFS = require('ipfs-api');
const OrbitDB = require('orbit-db');
const ipfsOptions = {host: ‘localhost’, port: '5001'};

async function main() {

// Create IPFS instance
const ipfs = new IPFS(ipfsOptions);

console.log('Connected to IPFS');
const orbitdb = await OrbitDB.createInstance(ipfs)
     console.log('OrbitDB instance created.')


Upon execution of the preceding program, you should get the following output:

$ node app.js
$ Connected to IPFS
$ OrbitDB instance created.

Awesome! Now, we can create a new database or load an existing database and use it to build our decentralized application.

Before you start building your dApps, you should learn the data models offered by OrbitDB.

OrbitDB Data Models

OrbitDB provides various types of databases for different types of data models; here are the following data models:

  • Log
  • Feed
  • Key-value
  • Docs
  • Counter

Let’s look at each data model in brief.


It’s an immutable data model used to store traversable records. One of the use cases for such types of data models is a message queue where messages are stored in the order and traversed back to the starting index, record by record.

The log is an immutable data store, so data cannot be altered once it is written.

To create a log store, refer to the following code:

constdb = await orbitdb.eventlog('users');
const hash = await db.add({name: 'Ernest Obot'});

// to return all logs
const allRecords = db.iterator({limit: -1}).collect().map((e) =>e.payload.value);

console.log(allRecords); // prints all the logs

// return only specific record
const record = db.get(hash).map((e) =>e.payload.value);

console.log(record); // prints specific log

Let’s look over the next data model—Feed.


This is a mutable version of the log data model. In the feed data model, you can store the record and traverse back to it just like we were doing in the log data model.

We can alter the records in the Feed data store. Let’s look at an example:

constdb = await orbitdb.feed('users');

// add new record in the data model
const hash = await db.add({name: 'Ernest Obot');
const singleUserData = db.get(hash).map((e) =>e.payload.value);

console.log(singleUserData); // print single record

// remove records using the hash
const hash = await db.remove(hash)
const allRecords = db.iterator({limit: -1}).collect().map((e) =>e.payload.value);

console.log(allRecords); // prints all the record

The feed data model can be used for a variety of purposes, such as shopping carts, blogs, tweets, or any application that requires user-generated feed of data with a feature to traverse the records.

Let’s look at the next data model—the key-value data model.


The key-value store, as the name suggests, lets you store data in the key-value format. The usage of the key-value data store is vast and can be used in the range of applications.

Let’s look at an example:

const db = await orbitdb.keyvalue('users');

// add new key value data
const hash = await db.put('1' {name: ‘Ernest Obot’});

// You can also do the above operation using a set() function
const hash = await db.set('1', {name: 'Shahid'});

// fetch the information using the key
const value = db.get('1');

console.log(value); // prints the data i.e {name: 'Ernest Obot'}

// delete the data using the key
const hash = await db.del('1');

Let’s look at the next and one of the most commonly used data models—Docs.

As the name suggests, it’s a document-based data model where we can store custom documents and index it using custom fields. If you are familiar with _MongoDB _or ElasticSearch, this data model will be very useful for you.

You can use the Docs data mode to build custom database applications, blogs, eCommerce applications, and so on.

Let’s look at the example code:

const db = await orbitdb.docs(‘db.users’);

// add new record
const hash = await db.put({_id: ‘hash of the record’, name: ‘Ernest Obot’, followers: 500, following:120, profilePicture: ‘hash of the image probably IPFS’});

// fetch the record
const profile = db.get(‘hash of the record’);

// delete the record
const hash = await db.del(‘hash of the record’);

// fetch all the record
const allProfiles = db.get('');

By default, the index is on the _id field of the document; you can change it by specifying the index. Check out the following example:

constdb = await orbitdb.docs(‘db.users’, {indexBy: ‘name’});

You can run the custom query to fetch the documents, just like we do in other databases.

Check out the following example:

const all = db.query((doc) =>doc.followers>= 500);
// should returns all the users who have followers equal to or more than 500

The docs data model is quite useful and generic and can be shaped to support any application.

Let’s learn about the last data model—Counter.


This data model, as the name suggests, is useful for datastore where numeric count records are required such as queues, and so on.

Let’s consider an example to understand better:

const counter = await orbitdb.counter(‘db.user.counter’);

// print counter value

//increment counter value
counter.inc(); // increment by 1
counter.inc(5); // increment by 5

It’s as simple as this. Create a data store and increment the value.

OrbitDb Use Cases

There are many industry sectors and organizations that can directly benefit from OrbitDb features. In this section, we will cover a few OrbitDb use cases.

  • Decentralize Email Application
  • Blog
  • e-Commerce
  • Applications that require data-intensive storage

So guys this brings this to our end of OrbitDb, i hope you learnt something great today. In our future post we will create some dApps using OrbitDb.

Would you like to buy me a coffee, You can do it here.

Visit my blog and subscribe to my newsletter to get posts right to your mailbox. Megtrix Publications

My Website

Share this