Skip to main content
Version: v1
For the complete documentation index, see llms.txt

Set up Cardano-db-sync

이 가이드는 Midnight을 위한 Cardano-db-sync를 설정하는 단계별 방법을 안내합니다.

Prerequisites​

Cardano-db-sync를 설정하기 전에 다음 사항을 준비하세요:

  • 노드가 실행 중인 Cardano node 설정 완료.
  • 충분한 리소스(CPU, 메모리, 스토리지).

Create PostgreSQL database​

Cardano-db-sync는 blockchain 데이터를 관계형 스키마로 인덱싱하기 위해 PostgreSQL 백엔드가 필요합니다.

Install PostgreSQL​

다음 명령어를 실행해 PostgreSQL을 설치합니다:

sudo apt install curl ca-certificates -y
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -s -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
sudo sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
sudo apt update && sudo apt -y install postgresql-17 postgresql-server-dev-17

Configure roles and database​

PostgreSQL 셸을 시작합니다:

sudo -i -u postgres psql

사용자 midnight을 생성하고, midnight 사용자에게 알려진 비밀번호와 전체 권한을 부여합니다:

CREATE USER midnight WITH PASSWORD 'your_actual_password';
ALTER ROLE midnight WITH SUPERUSER CREATEDB;
CREATE DATABASE cexplorer;

이 명령어들은 관리자 권한으로 PostgreSQL에 안전하게 로그인하고, 사용자 midnight을 생성해 알려진 비밀번호와 전체 권한을 부여하며, 비어 있는 cexplorer 데이터베이스를 생성합니다.

Configure authentication​

Cardano-db-sync가 비밀번호를 직접 입력하지 않고 연결할 수 있도록 .pgpass 파일을 생성합니다:

# Set variable for postgres password
export POSTGRES_PASSWORD='your_actual_password'

# Set the variable to a hidden file in your home directory
export PGPASSFILE="${HOME}/.pgpass"
important

your_actual_password를 실제로 사용할 안전한 비밀번호로 바꾸세요.

연결 문자열을 .pgpass 파일에 기록합니다:

echo "/var/run/postgresql:5432:cexplorer:midnight:$POSTGRES_PASSWORD" > "$PGPASSFILE"

.pgpass 파일에 엄격한 권한을 설정합니다. 파일이 누구나 읽을 수 있는 상태이면 PostgreSQL은 해당 파일을 무시합니다:

chmod 0600 "$PGPASSFILE"

연결 테스트를 실행합니다:

psql -h /var/run/postgresql -U midnight -d cexplorer -c "SELECT current_user; SELECT now();"

결과 해석 방법은 다음과 같습니다:

  • Success: 성공하면 비밀번호를 묻지 않고 midnight과 현재 타임스탬프가 담긴 테이블을 반환합니다.
  • Password Prompt: 비밀번호를 묻는다면 .pgpass 파일이 올바르게 읽히지 않는 것입니다. 호스트, 포트, 데이터베이스 이름이 일치하지 않을 가능성이 높습니다.
  • Access Denied: database "cexplorer" does not exist가 나오면 데이터베이스를 먼저 생성해야 합니다.

.pgpass 파일이 존재하는지, 내용까지 확인합니다:

cat ~/.pgpass

출력 예시:

/var/run/postgresql:5432:cexplorer:midnight:YOUR_PASSWORD

~/.pgpass 파일은 psql, pg_dump 같은 PostgreSQL 클라이언트 도구가 비밀번호를 직접 입력하거나 스크립트에 하드코딩하지 않고 자동으로 가져오도록 하는 설정 파일입니다.

PostgreSQL 17 configuration tuning​

important

Mainnet을 대상으로 할 때는 PostgreSQL 튜닝이 필수입니다. 튜닝하지 않으면 Cardano-db-sync 동기화 완료까지 매우 오랜 시간이 걸립니다.

/etc/postgresql/17/main/postgresql.conf 파일을 수정합니다:

다음 항목을 찾아 값을 변경합니다. 주석 처리된 줄은 #을 제거해 활성화하세요:

ConfigurationDescription
shared_buffers = 16GBPostgreSQL이 Cardano ledger를 활성 메모리에 훨씬 많이 유지할 수 있게 합니다.
maintenance_work_mem = 4GB현재 "Building Index" 단계에서 가장 중요합니다. 인덱스 정렬 작업에 더 많은 여유 공간을 제공합니다.
max_parallel_maintenance_workers = 4하나의 인덱스를 만드는 데 4개의 CPU 코어가 함께 작업할 수 있게 합니다.
effective_cache_size = 48GBPostgreSQL 플래너가 캐싱에 활용할 수 있는 전체 RAM 양을 파악하도록 돕습니다.

Setup Cardano-db-sync​

이 섹션에서는 Cardano-db-sync 바이너리와 설정 파일을 다운로드해 설치하는 방법을 다룹니다.

important

Cardano-db-sync 13.7.1.0을 Cardano-node 11.0.1과 함께 사용하세요. Van Rossem 업그레이드 변경 사항 때문에, Cardano-db-sync 데이터베이스는 Cardano-node 11.0.1을 기준으로 다시 replay해야 합니다. 이 Cardano-db-sync 버전으로의 업그레이드는 단순한 바이너리 교체가 아닙니다. 기존 데이터베이스를 사용하려면 먼저 replay해야 합니다.

Download Cardano-db-sync binaries​

네트워크를 "preview", "mainnet", "preprod" 중 하나로 설정합니다:

NETWORK="preprod"

Cardano-db-sync 바이너리를 다운로드해 임시 디렉토리에 압축을 풉니다:

mkdir -p ~/tmp
cd ~/tmp
curl -L -O https://github.com/IntersectMBO/cardano-db-sync/releases/download/13.7.1.0/cardano-db-sync-13.7.1.0-linux.tar.gz
tar -xzf cardano-db-sync-13.7.1.0-linux.tar.gz

Cardano-db-sync 바이너리를 로컬 bin 디렉토리로 옮깁니다:

mkdir -p ~/.local/bin
cp bin/* ~/.local/bin/
chmod +x ~/.local/bin/cardano-db-sync*

Cardano-db-sync 설치를 확인합니다:

cardano-db-sync --version
which cardano-db-sync

다운로드한 db-sync 스키마를 ~/cardano-data 디렉토리로 옮깁니다:

mkdir -p ~/cardano-data/
sudo mv ~/tmp/schema ~/cardano-data/

Cardano-db-sync config.json 파일을 다운로드합니다:

cd ~/cardano-data
curl -O https://book.world.dev.cardano.org/environments/$NETWORK/db-sync-config.json

Cardano-db-sync config.json 파일을 Cardano node 설정 파일 경로로 업데이트합니다:

sed -i "s|\"NodeConfigFile\": \"config.json\"|\"NodeConfigFile\": \"/home/midnight/.local/share/$NETWORK/config.json\"|" ~/cardano-data/db-sync-config.json

Cardano-db-sync 설치를 확인합니다:

cardano-db-sync --version
which cardano-db-sync

Run Cardano-db-sync​

important

Cardano node가 실행 중인지 확인하세요. Cardano-db-sync는 Cardano-node가 제공하는 Cardano 데이터베이스를 사용해 체인을 인덱싱합니다.

PostgreSQL 비밀번호 환경 변수를 설정합니다:

export PGPASSFILE="${HOME}/.pgpass"

셸에서 Cardano-db-sync를 대화형으로 시작합니다:

cardano-db-sync \
    --config /home/midnight/cardano-data/db-sync-config.json \
    --socket-path /home/midnight/cardano-data/db/node.socket \
    --schema-dir /home/midnight/cardano-data/schema \
    --state-dir /home/midnight/cardano-data/db-sync-state
info

Cardano-db-sync는 초기화 중에 5~20분 정도 지연될 수 있습니다. 정상적인 동작입니다.

cardano-db-sync의 최신 블록 높이를 확인합니다:

psql -d cexplorer -c "SELECT block_no, slot_no, time FROM block ORDER BY id DESC LIMIT 1;"

cardano-db-sync 동기화 비율을 확인합니다:

psql -d cexplorer -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;"

출력 예시:

sync_percent
------------
45.00
(1 row)

Cardano-db-sync가 45% 동기화됐다는 뜻입니다. 동기화 비율이 최소 99%에 도달할 때까지 기다린 뒤 다음 단계를 진행하세요.

info

더 유용한 SQL 쿼리는 Cardano-db-sync 저장소에서 확인하세요: https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/interesting-queries.md

Setup Cardano-db-sync systemd service​

Cardano-db-sync용 서비스 파일을 생성합니다:

sudo vim /etc/systemd/system/cardano-db-sync.service

서비스 파일에 다음 내용을 붙여넣습니다:

[Unit]
Description=Cardano DB Sync
# Ensures db-sync doesn't start until the node is ready
After=cardano-node.service
Requires=cardano-node.service

[Service]
User=midnight
Type=simple
# Crucial: Tells the tool where to find the Postgres password
Environment="PGPASSFILE=/home/midnight/.pgpass"
WorkingDirectory=/home/midnight/cardano-data
ExecStart=/home/midnight/.local/bin/cardano-db-sync \
    --config /home/midnight/cardano-data/db-sync-config.json \
    --socket-path /home/midnight/cardano-data/db/node.socket \
    --schema-dir /home/midnight/cardano-data/schema \
    --state-dir /home/midnight/cardano-data/db-sync-state
# SIGINT is the "clean" way to shut down to prevent database corruption
KillSignal=SIGINT
Restart=always
RestartSec=10
# Increases the limit for open files (important for high-throughput DBs)
LimitNOFILE=32768

[Install]
WantedBy=multi-user.target

Cardano-db-sync 서비스를 활성화하고 시작합니다:

# Reload systemd to recognize new files
sudo systemctl daemon-reload

# Enable services to start on boot
sudo systemctl enable cardano-db-sync

# Start the services
sudo systemctl start cardano-db-sync

Cardano-db-sync 서비스 상태를 확인합니다:

sudo systemctl status cardano-db-sync

실시간 로그를 확인합니다:

# Follow Cardano-db-sync logs
journalctl -u cardano-db-sync -f

Next steps​

Cardano-db-sync가 완전히 동기화되면 Midnight node를 시작할 수 있습니다. 자세한 내용은 Set up full node 가이드를 참고하세요.