Set up Cardano-db-sync

As a Partner Chain, Midnight nodes require a persistent connection to the Cardano blockchain to track on-chain governance, cNIGHT token registrations, and permissioned candidate registrations. The Cardano-db-sync tool 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, enabling Midnight nodes to query Cardano state through SQL.

important

All Midnight nodes require a persistent connection to a Cardano-db-sync instance. Cardano-db-sync must be fully synchronized before starting your Midnight node, as the node depends on this connection to function properly.

System requirements

Operating System Requirements

Linux operating systems must be compatible with GLIBC version 2.39 or greater. Use one of the following:

• Ubuntu 24.04 or later
• Debian 13 or later

Verify your GLIBC version with: ldd --version

Cardano-db-sync hardware requirements

Requirement	Cardano Mainnet	Preview/Preprod Testnet
Operating System	64-bit Linux (Ubuntu 24.04 LTS recommended)	64-bit Linux (Ubuntu 24.04 LTS recommended)
Memory	32 GB or more	16 GB 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 GB NVMe SSD	40 GB NVMe SSD (minimum)
Network	Stable 100 Mbps or better	Stable 100 Mbps or better

Combined FNO system requirements

If you're running both Midnight node and Cardano-db-sync on the same instance (recommended for Federated Node Operators), use these specifications to prevent resource competition:

Component	Preprod (Testnet)	Mainnet (Minimum)	Mainnet (Recommended)
CPU	8-16 cores (≥2.5 GHz)	16-24 cores (≥3.0 GHz)	24-32 cores (≥3.0 GHz)
RAM	32-64 GB	128 GB	192-256 GB
Storage	300-500 GB NVMe SSD	2 TB NVMe SSD	4 TB NVMe SSD
IOPS	≥30,000	≥60,000	≥100,000
Network	≥100 Mbps, stable	500 Mbps-1 Gbps	1 Gbps, high uptime

Installation

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

note

For additional information, visit the official Cardano-db-sync repository: https://github.com/IntersectMBO/Cardano-db-sync

Install Docker

Install Docker Engine on Linux.

Docker Desktop users

Docker Desktop is a graphical app, but it cannot run commands such as docker --version. It only provides the background Docker engine. All Midnight commands must be run in your system terminal.

Before running any commands:

1. Open Docker Desktop
2. Wait until it shows “Docker is running”
3. Leave Docker Desktop open — do not try to run containers from the UI
4. Run all commands exactly as shown in this guide from your terminal

Verify Docker installation

• 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

Set up Cardano-db-sync with Docker

The official Cardano-db-sync supports Docker deployment for both Preview and Preprod networks.

Create Docker Compose configuration

Create a docker-compose.yml file with the following configuration (adjust for your target network):

version: "3.8"

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: cexplorer
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

  cardano-node:
    image: ghcr.io/intersectmbo/cardano-node:9.2.1
    environment:
      NETWORK: ${CARDANO_NETWORK:-preview}
    volumes:
      - cardano-node-data:/data
      - cardano-node-ipc:/ipc
    restart: unless-stopped

  cardano-db-sync:
    image: ghcr.io/intersectmbo/cardano-db-sync:13.5.0.2
    environment:
      NETWORK: ${CARDANO_NETWORK:-preview}
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DB: cexplorer
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      RESTORE_SNAPSHOT: ${RESTORE_SNAPSHOT:-}
    volumes:
      - cardano-db-sync-data:/var/lib/cexplorer
      - cardano-node-ipc:/node-ipc
    depends_on:
      - postgres
      - cardano-node
    restart: unless-stopped

volumes:
  postgres-data:
  cardano-node-data:
  cardano-node-ipc:
  cardano-db-sync-data:

Create environment file

Create a .env file in the same directory:

# Network: preview or preprod
CARDANO_NETWORK=preview

# Strong PostgreSQL password (change this!)
POSTGRES_PASSWORD=your_secure_password_here

# Optional: restore from snapshot for faster sync
# RESTORE_SNAPSHOT=https://update-cardano-mainnet.iohk.io/cardano-db-sync/index.html

security configuration

For production deployments:

• Use a strong PostgreSQL password (minimum 16 characters with mixed case, numbers, and symbols)
• Enable SSL/TLS for PostgreSQL connections in production
• Restrict PostgreSQL network access to localhost or specific IP addresses using firewall rules
• Never commit the .env file to version control

Start services

Start Cardano-db-sync and its dependencies:

docker compose up -d

Monitor synchronization progress

Cardano-db-sync must fully synchronize with the Cardano blockchain before starting your Midnight node. Depending on the network and hardware, initial synchronization can take several hours to days.

Check synchronization status

Choose one of the following methods to query synchronization progress:

Option 1: Using psql client directly

Install the PostgreSQL client:

sudo apt-get install postgresql-client

Connect to the database:

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

Option 2: Using Docker exec

docker exec postgres psql -U postgres -d cexplorer

Option 3: Remote SSH query

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

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;\""

Run synchronization query

Once connected to the PostgreSQL shell, run this query to check the current synchronization percentage:

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;

A result close to 100% indicates the database is fully synchronized with the Cardano blockchain.

tip

Wait for Cardano-db-sync to reach 100% synchronization before starting your Midnight node. Running a Midnight node with an incomplete Cardano-db-sync connection will cause synchronization errors.