Setting up Cardano-db-sync

As a Partner Chain, Midnight nodes need to track scripts on the Cardano blockchain. The Cardano-db-sync tool is used for this purpose; it follows the Cardano chain, extracting information from both the blockchain and an internally maintained ledger state. This data is then inserted into a PostgreSQL database. By providing a PostgreSQL interface, Cardano-db-sync enables Midnight nodes to follow and interact with the Cardano chain by allowing SQL queries to be executed directly against the database schema or through any language that has libraries for SQL database interactions.

Therefore, it is a requirement for Midnight nodes to have a persistant connection to a Cardano-db-sync instance.

System Requirements

Requirement	Cardano Mainnet	Preview Testnet
Operating System	Any well-known Linux distribution.	Any well-known Linux distribution.
Memory	32 G or more	16 G or more
CPU Cores	4 or more	4 or more
IOPS	60,000 IOPS or better. Lower ratings will lead to slower sync times and/or falling behind the chain tip.	30,000 IOPS or better. Lower ratings will lead to slower sync times.
Disk Storage	320 G, SSD	40 G (preferably SSD)

Installation

Installing Cardano-db-sync can be done via many methods such as, static binaries, Nix, building from source, and Docker. This documentation will focus on the Docker method.

note

If at any point visit the official Cardano-db-sync repository for more information: https://github.com/IntersectMBO/cardano-db-sync

Install Docker

• Install Docker Engine on Linux: https://docs.docker.com/engine/install/

Verify Docker is installed

• Check Docker version and installation path:

docker --version # return docker version
which docker # returns executable path

• Verify Docker daemon is running:

sudo systemctl status docker

If Docker is running, the output may look like:

● docker.service - Docker Application Container Engine
   Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2023-10-09 15:00:00 UTC; 1h 30min ago

Clone midnight-node-docker Repository:

The midnight-node-docker repo contains a Docker Compose file to easily start up a Cardano-db-sync/ PostgreSQL instance on Preview Testnet.

• Clone the repo and change directory into it:

git clone https://github.com/midnight-ntwrk/midnight-node-docker
cd midnight-node-docker

Configure Cardano-db-sync/ PostgreSQL

Cardano-db-sync and PostgreSQL services are described in compose-partner-chains.yml.

important

Set a unique username, password and port for Cardano-db-sync and PostgreSQL for better security.

• Open compose-partner-chains.yml in an editor, replace any default usernames, passwords, and ports with unique values that only you know.
• Comment out the Ogmios and Kupo services (unless you are a block producer who needs them for block production operations).
• Save compose-partner-chains.yml.

Start Cardano-db-sync/ PostgreSQL

• Start services described in compose-partner-chains.yml:

docker-compose -f compose-partner-chains.yml up -d

• Query Cardano-db-sync synchronization progress:

  • Using psql directy:

    sudo apt-get install postgresql-client # install psql client
    • Log into PostgreSQL shell using psql:

    psql -h localhost -U postgres -d cexplorer -p 5432

  • Optionally, log in to PostgreSQL shell using docker:

    docker exec -it db-sync-postgres psql -U postgres -d cexplorer

    Then, run the following query inside the PostgreSQL shell to check current synchronization status:

    SELECT 100 * (
        EXTRACT(EPOCH FROM (MAX(time) AT TIME ZONE 'UTC')) -
        EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))
    ) / (
        EXTRACT(EPOCH FROM (NOW() AT TIME ZONE 'UTC')) -
        EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))
    ) AS sync_percent
    FROM block;

  • Using ssh remotely:

    If you want to query remotely, run this command via SSH:

    ssh user@x.x.x.x -C "psql -d cexplorer -h localhost -p 5432 -U postgres -c \"SELECT 100 * (EXTRACT(EPOCH FROM (MAX(time) AT TIME ZONE 'UTC')) - EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))) / (EXTRACT(EPOCH FROM (NOW() AT TIME ZONE 'UTC')) - EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))) AS sync_percent FROM block;\""

    Replace user@x.x.x.x with your SSH username and server IP address.

tip

Cardano-db-sync must fully sync for Midnight nodes to operate.