{"id":13428311,"url":"https://github.com/IntersectMBO/cardano-db-sync","last_synced_at":"2025-03-16T01:32:21.459Z","repository":{"id":36991042,"uuid":"243388274","full_name":"IntersectMBO/cardano-db-sync","owner":"IntersectMBO","description":"A component that follows the Cardano chain and stores blocks and transactions in PostgreSQL","archived":false,"fork":false,"pushed_at":"2024-05-30T03:41:03.000Z","size":10776,"stargazers_count":283,"open_issues_count":122,"forks_count":156,"subscribers_count":47,"default_branch":"master","last_synced_at":"2024-05-30T13:07:54.190Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IntersectMBO.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-26T23:34:13.000Z","updated_at":"2024-05-30T13:08:01.206Z","dependencies_parsed_at":"2023-12-19T12:39:49.907Z","dependency_job_id":"26043a80-f8a9-40ad-9fbc-c8b3350d8557","html_url":"https://github.com/IntersectMBO/cardano-db-sync","commit_stats":null,"previous_names":["intersectmbo/cardano-db-sync","input-output-hk/cardano-db-sync"],"tags_count":81,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-db-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-db-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-db-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fcardano-db-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IntersectMBO","download_url":"https://codeload.github.com/IntersectMBO/cardano-db-sync/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243814900,"owners_count":20352037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T01:00:52.014Z","updated_at":"2025-03-16T01:32:21.437Z","avatar_url":"https://github.com/IntersectMBO.png","language":"Haskell","funding_links":[],"categories":["Uncategorized","Haskell","Smart Contract Platforms"],"sub_categories":["Uncategorized"],"readme":"[![Haskell CI](https://img.shields.io/github/actions/workflow/status/intersectmbo/cardano-db-sync/haskell.yml?branch=master\u0026style=for-the-badge)](https://github.com/intersectmbo/cardano-db-sync/actions/workflows/haskell.yml)\n[![Discord](https://img.shields.io/discord/1136727663583698984?style=for-the-badge\u0026color=blue)](https://discord.gg/GXrTvmzHQN)\n\n# Cardano DB Sync\n\n**Note:** Anyone wishing to build and run anything in this repository should avoid the `master` branch and build/run from the latest release tag.\n\n## Purpose\n\nThe purpose of Cardano DB Sync is to follow the Cardano chain and take information from the chain\nand an internally maintained copy of ledger state. Data is then extracted from the chain and\ninserted into a PostgreSQL database. SQL queries can then be written directly against the database\nschema or as queries embedded in any language with libraries for interacting with an SQL database.\n\nExamples of what someone would be able to do via an SQL query against a Cardano DB Sync\ninstance fully synced to a specific network is:\n\n* Look up any block, transaction, address, stake pool etc on that network, usually by the hash that\n  identifies that item or the index into another table.\n* Look up the balance of any stake address for any Shelley or later epoch.\n* Look up the amount of ADA delegated to each pool for any Shelley or later epoch.\n\n## Documentation\n\nThe [doc/](https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/Readme.md) directory,  offers essential resources for users, including guides for installation with and without Nix, configuration. Key files cover, Docker usage, PostgreSQL example queries, command-line options and database migrations. There's also a troubleshooting guide for common issues. These documents provide users with the necessary steps to effectively set up and maintain the Cardano DB Sync.\n\n## Architecture\n\nThe cardano-db-sync component consists of a set of components:\n\n* `cardano-db` which defines common data types and functions used by any application that needs\n  to interact with the data base from Haskell. In particular, it defines the database schema.\n* `cardano-db-tool` a tool used to manage the databases of cardano-db-sync (create\n  and run migrations, validate and analyse)\n* `cardano-db-sync` which acts as a Cardano node, following the chain and inserting\n  data from the chain into a PostgreSQL database.\n\nThe db-sync node is written in a highly modular fashion to allow it to be as flexible as possible.\n\nThe `cardano-db-sync` node connects to a locally running `cardano-node` (ie one connected to other\nnodes in the Cardano network over the internet with TCP/IP) using a Unix domain socket, retrieves\nblocks, updates its internal ledger state and stores parts of each block in a local PostgreSQL\ndatabase. The database does not store things like cryptographic signatures but does store enough\ninformation to follow the chain of blocks and look at the transactions within blocks.\n\nThe PostgreSQL database is designed to be accessed in a read-only fashion from other applications.\nThe database schema is highly normalised which helps prevent data inconsistencies (specifically\nwith the use of foreign keys from one table to another). More user friendly database queries can be\nimplemented using [Postgres Views][PostgresView] to implement joins between tables.\n\n## System Requirements\n\nThe system requirements for `cardano-db-sync` (with both `db-sync` and the `node` running\non the same machine are:\n\n* Any of the big well known Linux distributions (eg, Debian, Ubuntu, RHEL, CentOS, Arch\n  etc).\n* 32 Gigabytes of RAM or more.\n* 4 CPU cores or more.\n* Ensure that the machine has sufficient IOPS (Input/Output Operations per Second). Ie it should be\n  60k IOPS or better. Lower IOPS ratings will result in slower sync times and/or falling behind the\n  chain tip.\n* 320 Gigabytes or more of disk storage (preferably SSD which are 2-5 times faster than\n  electro-mechanical disks).\n\nThe recommended configuration is to have the `db-sync` and the PostgreSQL server on the same\nmachine. During syncing (getting historical data from the blockchain) there is a **HUGE** amount\nof data traffic between `db-sync` and the database. Traffic to a local database is significantly\nfaster than traffic to a database on the LAN or remotely to another location.\n\nWhen building an application that will be querying the database, remember that for fast queries,\nlow latency disk access is far more important than high throughput (assuming the minimal IOPS\nabove is met).\n\n## How to Contact the Cardano DB Sync Team\n\nYou can discuss development or find help at the following places:\n\n * Intersect Discord [#db-sync](https://discord.com/channels/1136727663583698984/1239888910537064468) channel, if new to server invite [here](https://discord.gg/GXrTvmzHQN)\n * [GitHub Issues](https://github.com/IntersectMBO/cardano-db-sync/issues)\n\n## Installation\n\nInstall db-sync with one of the following methods:\n\n * [Static Binaries](https://github.com/IntersectMBO/cardano-db-sync/releases/latest)\n * [Installing with Nix][InstallingNix]\n * [Installing from Source][Installing]\n * [Docker][Docker]\n\nOnce installed, start db-sync by following the [Running Guide][Running].\n\n## Troubleshooting\n\nIf you have any issues with this project, consult the [Troubleshooting][Troubleshooting] page for\npossible solutions.\n\n## Further Reading\n\n* [BuildingRunning][BuildingRunning]: Building and running the db-sync node.\n* [Docker][Docker]: Instruction for docker-compose, and building the images using nix.\n* [ERD][ERD]: The entity relationship diagram.\n* [Example SQL queries][ExampleQueries]: Some example SQL and Haskell/Esqueleto queries.\n* [OffChainPoolData][OffChainPoolData]: Explanation of how stake pool offchain data is retried.\n* [Schema Documentation][Schema Documentation]: The database schema documentation.\n* [Schema Management][Schema Management]: How the database schema is managed and modified.\n* [StateSnapshot][StateSnapshot]: Document the creation and restoration of state snapshot files.\n* [Upgrading PostgreSQL][UpgradingPostgres]\n* [Validation][Validation]: Explanation of validation done by the db-sync node and assumptions made.\n\n[InstallingNix]: doc/installing-with-nix.md\n[Installing]: doc/installing.md\n[BuildingRunning]: doc/building-running.md\n[Docker]: doc/docker.md\n[Running]: doc/running.md\n[ERD]: doc/ERD.png\n[ExampleQueries]: doc/interesting-queries.md\n[PostgresView]: https://www.postgresql.org/docs/current/sql-createview.html\n[OffChainPoolData]: doc/pool-offchain-data.md\n[Schema Documentation]: doc/schema.md\n[Schema Management]: doc/schema-management.md\n[StateSnapshot]: doc/state-snapshot.md\n[Troubleshooting]: doc/troubleshooting.md\n[UpgradingPostgres]: doc/upgrading-postgresql.md\n[Validation]: doc/validation.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntersectMBO%2Fcardano-db-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIntersectMBO%2Fcardano-db-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntersectMBO%2Fcardano-db-sync/lists"}