Skip to main content

Developer documentation

dbsync follows a running Cardano node over a node-to-client (n2c) Unix socket and projects on-chain data into a PostgreSQL schema you control table by table via profiles.

This section is for contributors working on dbsync itself — writing extractors, extending the schema, evolving the phase machinery, or orienting in the codebase. If you only want to run dbsync against a node, head to the Users section instead.

The shape​

The hot path has four logical stages plus a phase-specific writer that swaps between bulk-load and chain-tip following. The COPY path drives the catch-up; the hasql path drives steady state. Both are in play across the lifetime of a sync.

The page that goes deep on this — pre-assigned IDs, the cross-phase Resolver/Writer interfaces, the side channels (ledger worker, off-chain fetcher, tx-out worker), boot decisions, threading — is Architecture.

The lifecycle​

dbsync moves through four phases as it catches up to the chain tip and stays there:

IngestChainHistory → PreparingForVolatileTail → FollowingVolatileTail ⇄ FollowingChainTip

The pipeline shape above is identical across the run; only the writer changes between phases, along with how row IDs are obtained. Sync phases covers the state machine and the transitions.

  • Architecture — full data flow, the cross-phase interfaces, boot, threading.
  • Repository layout — annotated module map of the workspace.
  • Sync phases — the four-phase state machine.
  • Extractors — how projections work and how to add one.
  • Schema layer — DDL generation, COPY encoders, hasql statements.
  • Workers — work that runs alongside the main pipeline.
  • Error handling — how errors are thrown, propagated, and rendered, and the rules that keep a crash log diagnosable.
  • Comparing databases — verify this dbsync stores the same data as the original cardano-db-sync.
  • Contributing — workflow and code conventions.