From 84bc5a3b3ba8d92467218a28930764864136aea8 Mon Sep 17 00:00:00 2001 From: Artur Wieczorek Date: Tue, 23 Jun 2026 04:03:37 +0200 Subject: [PATCH 1/2] docs(schema): document epoch views and correct stale generator note (#2127) epoch is now a view (migration-2-0049), not a table: document it as the UNION of epoch_finalized + epoch_current, and add the new epoch_current view and epoch_finalized / epoch_sync_enabled tables. Also correct the header note - the schema-doc generator (BaseSchema.hs / gen-schema-docs) was removed in the Persistent->Hasql rewrite, so the file is now maintained manually. --- doc/schema.md | 47 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/doc/schema.md b/doc/schema.md index b8cbb478b..1e68d016d 100644 --- a/doc/schema.md +++ b/doc/schema.md @@ -1,6 +1,6 @@ # Schema Documentation for cardano-db-sync -**Note:** This file is auto-generated from the documentation in cardano-db/src/Cardano/Db/Schema/BaseSchema.hs by the command `cabal run -- gen-schema-docs doc/schema.md`. This document should only be updated during the release process and updated on the release branch. +**Note:** This file is maintained manually and should be updated on the release branch whenever the database schema changes. (It was previously auto-generated, but the generator was removed during the Persistent->Hasql migration.) ### `schema_version` @@ -179,7 +179,37 @@ A table containing metadata about the chain. There will probably only ever be on ### `epoch` -Aggregation of data within an epoch. +A view aggregating data within an epoch. As of schema stage-two v49 (migration-2-0049) `epoch` is a view, not a table: the `UNION ALL` of `epoch_finalized` (materialised past epochs) and `epoch_current` (the live, in-progress epoch). It returns rows only when epoch sync is enabled (see `epoch_sync_enabled`); otherwise it is empty. + +| Column name | Type | Description | +|-|-|-| +| `id` | integer (64) | | +| `out_sum` | numeric | The sum of the transaction output values (in Lovelace) in this epoch. | +| `fees` | numeric | The sum of the fees (in Lovelace) in this epoch. | +| `tx_count` | integer (64) | The number of transactions in this epoch. | +| `blk_count` | integer (64) | The number of blocks in this epoch. | +| `no` | integer (64) | The epoch number. | +| `start_time` | timestamp | The epoch start time. | +| `end_time` | timestamp | The epoch end time. | + +### `epoch_current` + +A view computing aggregates for the current (not-yet-finalized) epoch live from `block` and `tx`. Excludes any epoch already present in `epoch_finalized`, and returns rows only when epoch sync is enabled (see `epoch_sync_enabled`). + +| Column name | Type | Description | +|-|-|-| +| `id` | integer (64) | Synthetic id (epoch number + 1). | +| `out_sum` | numeric | The sum of the transaction output values (in Lovelace) in this epoch. | +| `fees` | numeric | The sum of the fees (in Lovelace) in this epoch. | +| `tx_count` | integer (64) | The number of transactions in this epoch. | +| `blk_count` | integer (64) | The number of blocks in this epoch. | +| `no` | integer (64) | The epoch number. | +| `start_time` | timestamp | The epoch start time. | +| `end_time` | timestamp | The epoch end time. | + +### `epoch_finalized` + +Materialised aggregates for finalized (completed) epochs. Together with `epoch_current` it backs the `epoch` view. * Primary Id: `id` @@ -190,10 +220,21 @@ Aggregation of data within an epoch. | `fees` | lovelace | The sum of the fees (in Lovelace) in this epoch. | | `tx_count` | word31type | The number of transactions in this epoch. | | `blk_count` | word31type | The number of blocks in this epoch. | -| `no` | word31type | The epoch number. | +| `no` | word31type | The epoch number (unique). | | `start_time` | timestamp | The epoch start time. | | `end_time` | timestamp | The epoch end time. | +### `epoch_sync_enabled` + +A single-row toggle controlling whether the `epoch` and `epoch_current` views return data. + +* Primary Id: `singleton` + +| Column name | Type | Description | +|-|-|-| +| `singleton` | boolean | Always `TRUE`; enforces a single row. | +| `enabled` | boolean | Whether epoch aggregation (the `epoch` / `epoch_current` views) is enabled. | + ### `ada_pots` A table with all the different types of total balances (Shelley only). From 964e5caea1d3bab42e50404b9732e8cbb878020f Mon Sep 17 00:00:00 2001 From: Artur Wieczorek Date: Thu, 25 Jun 2026 13:01:43 +0200 Subject: [PATCH 2/2] docs(schema): fix "nominator" typo in committee quorum_numerator description --- doc/schema.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/schema.md b/doc/schema.md index 1e68d016d..420fff8e8 100644 --- a/doc/schema.md +++ b/doc/schema.md @@ -933,7 +933,7 @@ A table for new committee proposed on a GovActionProposal. New in 13.2-Conway. |-|-|-| | `id` | integer (64) | | | `gov_action_proposal_id` | integer (64) | The GovActionProposal table index for this new committee. This can be null for genesis committees. | -| `quorum_numerator` | integer (64) | The proposed quorum nominator. | +| `quorum_numerator` | integer (64) | The proposed quorum numerator. | | `quorum_denominator` | integer (64) | The proposed quorum denominator. | ### `committee_member`