Skip to content

Commit ecd2a9d

Browse files
IanoNjugunaIanoNjuguna
authored
Merge branch 'IntersectMBO:main' into iano-sessions_folder
2 parents 96b831f + 9fdf94d commit ecd2a9d

File tree

8 files changed

+934
-1
lines changed

8 files changed

+934
-1
lines changed

‎website/docs/how-to-guide/advanced/cardano-db-sync.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# cardano-db-sync
2+
3+
## Overview
4+
`cardano-db-sync` ingests data from a running Cardano node and writes it to PostgreSQL. It provides a queryable, normalized database for analytics, explorers, reporting, and downstream services.
5+
6+
## Repository
7+
https://github.com/IntersectMBO/cardano-db-sync
8+
9+
## What It Does
10+
- Follows the chain via the node's local state query and chain-sync protocols
11+
- Normalizes blocks, transactions, metadata, stake data, and Plutus script info into PostgreSQL
12+
- Exposes schemas used by explorers, reporting tools, and integrations
13+
14+
## When to Use It
15+
Use `cardano-db-sync` if you need a reliable on-chain data source for:
16+
- Explorers and dashboards
17+
- Analytics, BI, or data science pipelines
18+
- Integrations needing SQL access to on-chain state
19+
- Off-chain services that track transactions, stake, or governance data
20+
21+
## Key Components
22+
| Component | Purpose |
23+
|-----------|---------|
24+
| `cardano-db-sync` | Main service ingesting chain data into PostgreSQL |
25+
| `cardano-smash` | Optional pool metadata aggregation service |
26+
| PostgreSQL schema | Normalized tables for chain data and metadata |
27+
| `cardano-node` dependency | Requires a synced node and socket to follow the chain |
28+
29+
## Technical Details
30+
| Aspect | Details |
31+
|--------|---------|
32+
| Language | Haskell |
33+
| Database | PostgreSQL |
34+
| Build | Cabal / Nix |
35+
| Network | Connects to a local `cardano-node` socket |
36+
37+
## Prerequisites
38+
- Running `cardano-node` (matching network and era)
39+
- PostgreSQL instance with sufficient disk and I/O
40+
- Nix or Cabal toolchain for building the service
41+
42+
## Setup (High Level)
43+
1. Clone the repo
44+
```bash
45+
git clone https://github.com/IntersectMBO/cardano-db-sync.git
46+
cd cardano-db-sync
47+
```
48+
2. Prepare PostgreSQL
49+
- Create database and user; set connection URI in config
50+
3. Configure service
51+
- Point to node socket, network magic, and DB connection
52+
4. Run migrations
53+
```bash
54+
cabal run db-tool -- migrate
55+
```
56+
5. Start sync
57+
```bash
58+
cabal run cardano-db-sync -- \
59+
--config config/mainnet-config.yaml \
60+
--socket-path /path/to/node.socket \
61+
--state-dir ./state \
62+
--schema-dir schema
63+
```
64+
65+
## Best Practices
66+
- Keep node and db-sync on the same network and era
67+
- Monitor slot lag and DB health; ensure sufficient disk/IO
68+
- Run regular PostgreSQL maintenance (VACUUM/ANALYZE)
69+
- Back up the database before upgrading schemas
70+
- Use testnet for development before mainnet
71+
72+
## Common Uses
73+
| Need | How db-sync helps |
74+
|------|-------------------|
75+
| Explorer data | Query blocks, transactions, metadata via SQL |
76+
| Analytics | Join chain data with business data in BI tools |
77+
| Wallet/ops monitoring | Track UTxOs, stake, delegations, rewards |
78+
| Governance | Inspect proposals, votes, and on-chain events |
79+
80+
## When NOT to Use
81+
- If you only need light queries or cannot run a node/DB: use hosted APIs (Blockfrost, Koios, Cardano GraphQL).
82+
- For direct wallet operations without full DB: use `cardano-api` or `cardano-cli` with a node.
83+
84+
## Links
85+
- Repo: https://github.com/IntersectMBO/cardano-db-sync
86+
- Issues: https://github.com/IntersectMBO/cardano-db-sync/issues
87+
- Releases: https://github.com/IntersectMBO/cardano-db-sync/releases
88+
- Docs (README): see repository for network-specific configs and schema details.

‎website/docs/working-group/q1-2025/sessions/04-essential-links/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Session 04: Essential Links in Cardano",
3+
"position": 4
4+
}

‎website/docs/working-group/q1-2025/sessions/04-essential-links/recordings/readme.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Session 04 Recording
3+
sidebar_label: Recordings
4+
slug: /working-group/q1-2025/sessions/04-essential-links/recordings
5+
---
6+
# Session Recordings
7+
8+
## Recording 1 (2025/11/13 5:00 PM UTC)
9+
10+
🎥 **Essential Links in Cardano**
11+
12+
# Coming soon...
13+
14+
## Recording 2 (2025/11/19 07:00 AM UTC)
15+
16+
🎥 **Essential Links in Cardano**
17+
18+
# Coming soon...
19+
<!-- <iframe
20+
src="https://drive.google.com/file/d/RECORDING_ID_HERE/preview"
21+
title="Session 04: Essential Links in Cardano"
22+
width="100%"
23+
height="480"
24+
allow="autoplay"
25+
allowfullscreen
26+
style={{border: 0, borderRadius: '12px', boxShadow: '0 16px 40px rgba(1, 40, 170, 0.18)'}}
27+
/>
28+
29+
- **Status**: Recording available above.
30+
- **Highlights**:
31+
- Core repositories walkthrough
32+
- Official documentation resources
33+
- APIs and data services overview
34+
- Block explorers and community forums
35+
- Development tools showcase -->
36+
37+
For additional sessions, check the [Working Group Session Recordings](../../../media/session-recordings/readme.md) hub.
38+
39+
---
40+
41+
*This recording belongs to the Q1 2025 Developer Experience Working Group: "Laying the Foundations".*

0 commit comments

Comments
 (0)