Cardano DB Sync best practices

This section outlines some best practices for using the Cardano DB Sync component.

Purpose of Cardano DB Sync

The cardano-db-sync component is designed to work with a locally running Cardano node. The purpose of Cardano DB Sync is to follow the Cardano chain and fetch information from the chain and an internally-maintained copy of ledger state. Data is then extracted from the chain and inserted into a PostgreSQL database. SQL queries can then be written directly against the database schema or as queries embedded in any language with libraries for interacting with an SQL database.

Here are some examples of what you can do with a Cardano DB Sync instance on a specific network:

  • Look up details of any block, transaction, address, or stake pool on that network, usually by the hash that identifies that item or the index into another table.
  • Get the balance of any stake address for a specific epoch.
  • Check the amount of ada that is delegated to each stake pool for a specific epoch.

For details of sample queries, see Sample Cardano DB Sync queries.

Recommended Hardware for Cardano DB Sync

We recommend the following hardware for cardano-db-sync (with both db-sync and the node running on the same machine):

  • A Linux distribution (for example: Debian, Ubuntu, RHEL, CentOS, Arch)
  • 8 Gigabytes of RAM
  • 2 CPU cores
  • 50 Gigabytes or more of disk storage

The recommended configuration is to have the db-sync and the PostgreSQL server on the same machine. During syncing (where historical data is retrieved from the blockchain) there is a huge amount of data traffic between db-sync and the database. Traffic to a local database is significantly faster than traffic to a database on the local area network (LAN) or remotely to another location.

To run cardano-db-sync, you first need to have a locally-running cardano-node. For more information, see the building and running instructions.

Sample Cardano DB Sync queries

We have compiled a list of sample SQL queries that can be run against the db-sync database.

These queries are run using the psql executable that is distributed with PostgreSQL. You can connect to the database from the cardano-db-sync git checkout using:

PGPASSFILE=config/pgpass-mainnet psql cexplorer

You can find a list of sample queries here.

© IOHK 2015 - 2021


Cardano Logo

Cardano is an open-source project.

Cardano is a software platform ONLY and does not conduct any independent diligence on, or substantive review of, any blockchain asset, digital currency, cryptocurrency or associated funds. You are fully and solely responsible for evaluating your investments, for determining whether you will exchange blockchain assets based on your own judgement, and for all your decisions as to whether to exchange blockchain assets with Cardano. In many cases, blockchain assets you exchange on the basis of your research may not increase in value, and may decrease in value. Similarly, blockchain assets you exchange on the basis of your research may fall or rise in value after your exchange.

Past performance is not indicative of future results. Any investment in blockchain assets involves the risk of loss of part or all of your investment. The value of the blockchain assets you exchange is subject to market and other investment risks