Sheriff Quadri Software engineer

CouchDB vs. LevelDB: Comparing state database options

4 min read 1190

LevelDB vs. CouchDB: Comparing state database options


Hyperledger Fabric is an open-source, permissioned blockchain framework that is used for developing enterprise blockchain solutions and applications. The Hyperledger Fabric project is one of the major blockchain projects within Hyperledger, a multi-project collaborative effort started in 2015 by the Linux Foundation to advance cross-industry blockchain technologies. Today, Hyperledger Fabric now has over 120,000 contributing organizations and over 15,000 engineer contributors working together to advance the project.

Hyperledger Fabric has a modular (plug-and-play) architecture and can reach transactions of over 1,000 transactions per second (TPS), which can be upgraded to reach 20,000 TPS. Hyperledger Fabric also provides a particular set of features that differentiates it from other blockchain technologies and allows for easier adoption by enterprises. These features are:

Hyperledger Fabric has seen a lot of implementation and is used widely in industries like banking and finance, international trade, and the Internet of Things. Hyperledger Fabric comprises a lot of components, such as endorsers, committers, and databases.

Options for interacting in a Hyperledger Fabric network

To interact in a Hyperledger Fabric network, chain codes (also known as smart contracts) are used. These smart contracts can be written in different programming languages, including Go, Node.js, and Java.

Hyperledger Fabric stores the state of transactions carried out by chain codes in databases. There are two main types of records stored by an Hyperledger Fabric network:

  • Transaction logs: This is the blockchain aspect of the Hyperledger Fabric network, which comprises a record of all transactions that resulted in the current state of the Hyperledger Fabric network. The data stored in the transaction log is immutable and is stored in a LevelDB database
  • World state: This is the current value of the ledger at a given point in time. The main database of the Fabric network, by default, is a LevelDB database and is only populated when a given transaction is completed; however, it can be replaced with a Couch DB database

In this article, we are going to discuss how to choose between CouchDB and LevelDB databases as your world state database, covering the following topics:


Why not use a database like PostgreSQL or MySQL?

Hyperledger Fabric only provides support for LevelDB and CouchDB and does not provide support for databases like PostgreSQL, MongoDB, or MySQL. A discussion in this Hyperledger forum states that, in order to provide support for pluggable databases, many changes would have to be made to the network and database itself. The project has been removed from Hyperledger’s development pipeline for the time being.

However, there are still ways to set up a database like PostgreSQL as your state database. You can fork the Fabric project and plugin a database like PostgreSQL, MySQL, or MongoDB by following these instructions. This example from IBM also shows a method you can use to set up PostgreSQL in your Hyperledger Fabric project.

What is LevelDB?

The LevelDB database is a fast database that allows you to store key-value pairs. The LevelDB database was written at Google by Sanjay Ghemawat and Jeff Dean, and is currently the only database used by Hyperledger Fabric for storing transaction logs. As previously mentioned, it is also the default database used for storing the world state in Hyperledger Fabric.

LevelDB key-value pairs are stored in arbitrary byte arrays. LevelDB provides support for only Key, Key range, and composite key queries, i.e., Put(key, value), GET(key, value), and Delete(key).

There is no support for SQL queries, indexes, or relational data models, as LevelDB is not a SQL database.

Advantages of LevelDB

  • LevelDB is a simple, fast database with less overhead compared to CouchDB
  • Data is stored and mapped with keys
    • You can perform simple operations, like Put(key, value), GET(Key, Value), and Delete(Key), which makes LevelDB less complex to use
  • LevelDB supports forward and backward iterations over the data, snapshots, and making changes in atomic batches

Limitations of LevelDB

  • No support for indices and queries
  • It only allows for simple operations, like Put(key, value), GET(key, value), and Delete(key)
  • None of the familiar features of a relational data model, as it is not a SQL database. Data can only be stored in key-value pairs
  • Querying large datasets from a LevelDB database is inefficient and complex, as complex queries and indices are not allowed

What is CouchDB?

The CouchDB database is an open-source, document-oriented database implemented in Erlang that collects and stores data in JSON format. Hyperledger Fabric users can replace their default LevelDB world state database with a CouchDB database, which is also the only available alternative.

CouchDB is a NoSQL database that allows for rich queries of the stored JSON content. The default query language in a CouchDB database is JavaScript, and the data can be stored without a set schema in JSON format.

CouchDB supports indices and pagination. You can also make queries based on keys, as with the LevelDB database.

Advantages of CouchDB

  • CouchDB allows for JSON queries and indices, which makes it easier to fulfill your Hyperledger Fabric network auditing and reporting requirements than in LevelDB
  • As a document-oriented database, CouchDB allows you to store data as arrays or dictionaries in the database
  • CouchDB data is exposed via an HTTP URI. This makes it possible to perform HTTP operations (GET, DELETE, PUT, POST) against your data
  • CouchDB makes querying large datasets of chain code more efficient and flexible with indices

Limitations of CouchDB

  • CouchDB runs as a separate database alongside the Hyperledger Fabric network
  • More commitment is needed in terms of database management, setup, configurations, etc. to run the network

Picking a state database for your next Hyperledger Fabric project

Before you choose a state database, you should know that you must decide on a database because Hyperledger Fabric doesn’t allow you to change the database after the Hyperledger Fabric network has been launched.

If you are running a simple Hyperledger Fabric project with a low volume of transactions, LevelDB’s ease of use and speed makes it very preferable to use.

However, for more complex projects, it is preferable to use a CouchDB database. CouchDB has all the features of the LevelDB database, such as getting and setting data based on keys, but also provides access to additional features, like storing data in a JSON format, indices, issuing queries, pagination, etc., all of which make working with data easier.

The features provided by CouchDB make it easier to manage a Hyperledger Fabric network with high volumes of transactions. CouchDB also makes it easier to complete the auditing and reporting requirements required in a modern organization running a Hyperledger Fabric network.


In this article, we talked about the world state database options available in Hyperledger Fabric, CouchDB and LevelDB. We explained the advantages and limitations of each database and we discussed how to pick a database for your next Hyperledger Fabric project.

Join organizations like Bitso and Coinsquare who use LogRocket to proactively monitor their Web3 apps

Client-side issues that impact users’ ability to activate and transact in your apps can drastically affect your bottom line. If you’re interested in monitoring UX issues, automatically surfacing JavaScript errors, and tracking slow network requests and component load time, try LogRocket.

LogRocket is like a DVR for web and mobile apps, recording everything that happens in your web app or site. Instead of guessing why problems happen, you can aggregate and report on key frontend performance metrics, replay user sessions along with application state, log network requests, and automatically surface all errors.

Modernize how you debug web and mobile apps — .

Sheriff Quadri Software engineer

Leave a Reply