Extend and fix schema docs

Author: kderme

cardano-db/src/Cardano/Db/Schema.hs

@@ -559,7 +559,7 @@ share
     UniqueCostModel     hash
 
   PoolStat
-    poolHashId          PoolHashId
+    poolHashId          PoolHashId          noreference
     epochNo             Word64              sqltype=word31type
     numberOfBlocks      Word64              sqltype=word31type
     numberOfDelegators  Word64              sqltype=word31type
@@ -1034,7 +1034,7 @@ schemaDocs =
       WithdrawalRedeemerId # "The Redeemer table index that is related with this withdrawal."
 
     EpochStake --^ do
-      "A table containing the epoch stake distribution for each epoch. This is inserted incrementally in the first blocks of the epoch.\
+      "A table containing the epoch stake distribution for each epoch. This is inserted incrementally in the first blocks of the previous epoch.\
       \ The stake distribution is extracted from the `set` snapshot of the ledger. See Shelley specs Sec. 11.2 for more details."
       EpochStakeAddrId # "The StakeAddress table index for the stake address for this EpochStake entry."
       EpochStakePoolId # "The PoolHash table index for the pool this entry is delegated to."
@@ -1259,6 +1259,22 @@ schemaDocs =
       CostModelHash # "The hash of cost model. It ensures uniqueness of entries. New in v13."
       CostModelCosts # "The actual costs formatted as json."
 
+    PoolStat --^ do
+      "Stats per pool and per epoch."
+      PoolStatPoolHashId # "The pool_hash_id reference."
+      PoolStatEpochNo # "The epoch number."
+      PoolStatNumberOfBlocks # "Number of blocks created on the previous epoch."
+      PoolStatNumberOfDelegators # "Number of delegators in the mark snapshot."
+      PoolStatStake # "Total stake in the mark snapshot."
+      PoolStatVotingPower # "Voting power of the SPO."
+
+    EpochState --^ do
+      "Table with governance (and in the future other) stats per epoch."
+      EpochStateCommitteeId # "The reference to the current committee."
+      EpochStateNoConfidenceId # "The reference to the current gov_action_proposal of no confidence. TODO: This remains NULL."
+      EpochStateConstitutionId # "The reference to the current constitution. Should never be null."
+      EpochStateEpochNo # "The epoch in question."
+
     ExtraMigrations --^ do
       "Extra optional migrations. New in 13.2."
       ExtraMigrationsDescription # "A description of the migration"

doc/schema.md

@@ -1,5 +1,6 @@
 # Schema Documentation for cardano-db-sync
 
+Schema version: 13.3.0.0 (from branch **kderme/prepare-release-13.3** which may not accurately reflect the version number)
 **Note:** This file is auto-generated from the documentation in cardano-db/src/Cardano/Db/Schema.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.
 
 ### `schema_version`
@@ -441,7 +442,7 @@ A table for withdrawals from a reward account.
 
 ### `epoch_stake`
 
-A table containing the epoch stake distribution for each epoch. This is inserted incrementally in the first blocks of the epoch. The stake distribution is extracted from the `set` snapshot of the ledger. See Shelley specs Sec. 11.2 for more details.
+A table containing the epoch stake distribution for each epoch. This is inserted incrementally in the first blocks of the previous epoch. The stake distribution is extracted from the `set` snapshot of the ledger. See Shelley specs Sec. 11.2 for more details.
 
 * Primary Id: `id`
 
@@ -773,6 +774,22 @@ CostModel for EpochParam and ParamProposal.
 | `hash` | hash32type | The hash of cost model. It ensures uniqueness of entries. New in v13. |
 | `costs` | jsonb | The actual costs formatted as json. |
 
+### `pool_stat`
+
+Stats per pool and per epoch.
+
+* Primary Id: `id`
+
+| Column name | Type | Description |
+|-|-|-|
+| `id` | integer (64) |  |
+| `pool_hash_id` | integer (64) | The pool_hash_id reference. |
+| `epoch_no` | word31type | The epoch number. |
+| `number_of_blocks` | word31type | Number of blocks created on the previous epoch. |
+| `number_of_delegators` | word31type | Number of delegators in the mark snapshot. |
+| `stake` | word31type | Total stake in the mark snapshot. |
+| `voting_power` | word31type | Voting power of the SPO. |
+
 ### `extra_migrations`
 
 Extra optional migrations. New in 13.2.
@@ -993,15 +1010,17 @@ The table for the distribution of voting power per DRep per. Currently this has
 
 ### `epoch_state`
 
+Table with governance (and in the future other) stats per epoch.
+
 * Primary Id: `id`
 
 | Column name | Type | Description |
 |-|-|-|
 | `id` | integer (64) |  |
-| `committee_id` | integer (64) |  |
-| `no_confidence_id` | integer (64) |  |
-| `constitution_id` | integer (64) |  |
-| `epoch_no` | word31type |  |
+| `committee_id` | integer (64) | The reference to the current committee. |
+| `no_confidence_id` | integer (64) | The reference to the current gov_action_proposal of no confidence. TODO: This remains NULL. |
+| `constitution_id` | integer (64) | The reference to the current constitution. Should never be null. |
+| `epoch_no` | word31type | The epoch in question. |
 
 ### `off_chain_pool_data`
 

schema/migration-2-0041-20240711.sql

@@ -0,0 +1,19 @@
+-- Persistent generated migration.
+
+CREATE FUNCTION migrate() RETURNS void AS $$
+DECLARE
+  next_version int ;
+BEGIN
+  SELECT stage_two + 1 INTO next_version FROM schema_version ;
+  IF next_version = 41 THEN
+    EXECUTE 'CREATe TABLE "pool_stat"("id" SERIAL8  PRIMARY KEY UNIQUE,"pool_hash_id" INT8 NOT NULL,"epoch_no" word31type NOT NULL,"number_of_blocks" word31type NOT NULL,"number_of_delegators" word31type NOT NULL,"stake" word31type NOT NULL,"voting_power" word31type NULL)' ;
+    -- Hand written SQL statements can be added here.
+    UPDATE schema_version SET stage_two = next_version ;
+    RAISE NOTICE 'DB has been migrated to stage_two version %', next_version ;
+  END IF ;
+END ;
+$$ LANGUAGE plpgsql ;
+
+SELECT migrate() ;
+
+DROP FUNCTION migrate() ;