Version: v1

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

You can install Cardano-db-sync using static binaries, Nix, building from source, or 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:

Open Docker Desktop
Wait until it shows “Docker is running”
Leave Docker Desktop open — do not try to run containers from the UI
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):

name: cardano-db-sync
version: '3.8'

services:
  postgres:
    image: postgres:17.2-alpine
    environment:
      - POSTGRES_LOGGING=true
      - POSTGRES_DB=cexplorer
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    networks:
      - postgres
    ports:
      - 5432:5432
    volumes:
      - postgres:/var/lib/postgresql/data
    restart: on-failure
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    command:
      - -c
      - maintenance_work_mem=1GB
      - -c
      - max_parallel_maintenance_workers=4
    logging:
      driver: "json-file"
      options:
        max-size: "200k"
        max-file: "10"

  cardano-node:
    image: ghcr.io/intersectmbo/cardano-node:10.6.1
    platform: linux/amd64
    environment:
      - NETWORK=${NETWORK:-preview}
    networks:
      - cardano-node
    volumes:
      - node-db:/data/db
      - node-ipc:/ipc
    restart: on-failure
    healthcheck:
      # Ping the EKG port to see if it responds.
      # Assuming if EKG isn't up then the rest of cardano-node isn't either.
      test: ["CMD-SHELL", "curl -f 127.0.0.1:12788 || exit 1"]
      interval: 60s
      timeout: 10s
      retries: 5
    logging:
      driver: "json-file"
      options:
        max-size: "200k"
        max-file: "10"

  cardano-db-sync:
    image: ghcr.io/intersectmbo/cardano-db-sync:13.7.0.1
    platform: linux/amd64
    environment:
      - NETWORK=${NETWORK:-preview}
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_DB=cexplorer
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    depends_on:
      # Depend on both services to be healthy before starting.
      cardano-node:
        condition: service_healthy
      postgres:
        condition: service_healthy
    networks:
      - cardano-node
      - postgres
    volumes:
      - db-sync-data:/var/lib/cexplorer
      - node-ipc:/node-ipc
    restart: on-failure
    logging:
      driver: "json-file"
      options:
        max-size: "200k"
        max-file: "10"

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

networks:
  cardano-node: {}
  postgres: {}
  cardano-db-sync: {}

Create environment file

Create a .env file in the same directory:

# Network: preview or preprod
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:

PostgreSQL client
Docker exec
Remote SSH query

Install the PostgreSQL client:

sudo apt-get install postgresql-client

Connect to the database:

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

docker compose exec postgres psql -U postgres -d cexplorer

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 98% or higher before starting your Midnight node. Running a Midnight node with an incomplete Cardano-db-sync connection will cause synchronization errors.

Next steps

With Cardano-db-sync fully synchronized, you can start your Midnight node. See the Set up full and archive nodes guide for more information.

System requirements​

Cardano-db-sync hardware requirements​

Combined FNO system requirements​

Installation​

Install Docker​

Verify Docker installation​

Set up Cardano-db-sync with Docker​

Create Docker Compose configuration​

Create environment file​

Start services​

Monitor synchronization progress​

Check synchronization status​

Run synchronization query​

Next steps​