Skip to content

Commit 17e6be2

Browse files
CmdvCmdv
committed
update docmentation for db-tool for address table schema
1 parent 1b5b4fa commit 17e6be2

File tree

6 files changed

+135
-57
lines changed

6 files changed

+135
-57
lines changed

‎cardano-db/app/gen-schema-docs.hs

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
{-# LANGUAGE OverloadedStrings #-}
22

33
import Cardano.Db (schemaDocs)
4+
import Cardano.Db.Schema.Core.TxOut (schemaDocsTxOutCore)
5+
import Cardano.Db.Schema.Variant.TxOut (schemaDocsTxOutVariant)
46
import Data.Text (Text)
57
import qualified Data.Text as Text
68
import qualified Data.Text.IO as Text
@@ -67,10 +69,18 @@ docHeader branchName =
6769
]
6870

6971
docBody :: Text
70-
docBody =
71-
Text.replace "ID:" "Id:"
72-
. Text.replace "#" "###"
73-
$ render markdownTableRenderer schemaDocs
72+
docBody = do
73+
coreDocBody <> variantDivider <> variantDocBody
74+
where
75+
coreDocBody = cleanUp $ render markdownTableRenderer (schemaDocs <> schemaDocsTxOutCore)
76+
variantDocBody = cleanUp $ render markdownTableRenderer schemaDocsTxOutVariant
77+
cleanUp = Text.replace "ID:" "Id:" . Text.replace "#" "###"
78+
variantDivider =
79+
mconcat
80+
[ "# Variant Schema\n\n"
81+
, "When using the `use_address_table` [configuration](https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/configuration.md#tx-out), the `tx_out` table is split into two tables: `tx_out` and `address`.\n"
82+
, "Bellow are the table documentation for this variaton. \n\n"
83+
]
7484

7585
readGitBranch :: IO Text
7686
readGitBranch = do

‎cardano-db/src/Cardano/Db/Operations/Other/ConsumedTxOut.hs

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -101,17 +101,19 @@ runExtraMigrations trce txOutTableType blockNoDiff pcm = do
101101
ems <- queryAllExtraMigrations
102102
isTxOutNull <- queryTxOutIsNull txOutTableType
103103
let migrationValues = processMigrationValues ems pcm
104+
isTxOutVariant = isTxOutVariantAddress txOutTableType
105+
isTxOutAddressSet = isTxOutAddressPreviouslySet migrationValues
104106

105-
-- can only run "use_address_table" on a non populated database
106-
when (isTxOutVariantAddress txOutTableType && not isTxOutNull) $
107+
-- can only run "use_address_table" on a non populated database but don't throw if the migration was previously set
108+
when (isTxOutVariant && not isTxOutNull && not isTxOutAddressSet) $
107109
throw $
108-
DBExtraMigration "runExtraMigrations: The use the config 'tx_out.use_address_table' can only be caried out on a non populated database."
110+
DBExtraMigration "runExtraMigrations: The use of the config 'tx_out.use_address_table' can only be caried out on a non populated database."
109111
-- Make sure the config "use_address_table" is there if the migration wasn't previously set in the past
110-
when (not (isTxOutVariantAddress txOutTableType) && isTxOutAddressPreviouslySet migrationValues) $
112+
when (not isTxOutVariant && isTxOutAddressSet) $
111113
throw $
112114
DBExtraMigration "runExtraMigrations: The configuration option 'tx_out.use_address_table' was previously set and the database updated. Unfortunately reverting this isn't possible."
113115
-- Has the user given txout address config && the migration wasn't previously set
114-
when (isTxOutVariantAddress txOutTableType && not (isTxOutAddressPreviouslySet migrationValues)) $ do
116+
when (isTxOutVariant && not isTxOutAddressSet) $ do
115117
updateTxOutAndCreateAddress
116118
insertExtraMigration TxOutAddressPreviouslySet
117119
-- first check if pruneTxOut flag is missing and it has previously been used

‎cardano-db/src/Cardano/Db/Schema/Core/TxOut.hs

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ import Database.Persist.TH
3030
share
3131
[ mkPersist sqlSettings
3232
, mkMigrate "migrateCoreTxOutCardanoDb"
33-
, mkEntityDefList "entityDefs"
33+
, mkEntityDefList "entityDefsTxOutCore"
3434
, deriveShowFields
3535
]
3636
[persistLowerCase|
@@ -62,13 +62,14 @@ share
6262

6363
|]
6464

65-
schemaDocs :: [EntityDef]
66-
schemaDocs =
67-
document entityDefs $ do
65+
schemaDocsTxOutCore :: [EntityDef]
66+
schemaDocsTxOutCore =
67+
document entityDefsTxOutCore $ do
6868
TxOut --^ do
6969
"A table for transaction outputs."
7070
TxOutAddress # "The human readable encoding of the output address. Will be Base58 for Byron era addresses and Bech32 for Shelley era."
7171
TxOutAddressHasScript # "Flag which shows if this address is locked by a script."
72+
TxOutConsumedByTxId # "The Tx table index of the transaction that consumes this transaction output. Not populated by default, can be activated via tx-out configs."
7273
TxOutDataHash # "The hash of the transaction output datum. (NULL for Txs without scripts)."
7374
TxOutIndex # "The index of this transaction output with the transaction."
7475
TxOutInlineDatumId # "The inline datum of the output, if it has one. New in v13."

‎cardano-db/src/Cardano/Db/Schema/Variant/TxOut.hs

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ import Database.Persist.TH
3030
share
3131
[ mkPersist sqlSettings
3232
, mkMigrate "migrateVariantAddressCardanoDb"
33-
, mkEntityDefList "entityDefs"
33+
, mkEntityDefList "entityDefsTxOutVariant"
3434
, deriveShowFields
3535
]
3636
[persistLowerCase|
@@ -65,12 +65,13 @@ share
6565
deriving Show
6666
|]
6767

68-
schemaDocs :: [EntityDef]
69-
schemaDocs =
70-
document entityDefs $ do
68+
schemaDocsTxOutVariant :: [EntityDef]
69+
schemaDocsTxOutVariant =
70+
document entityDefsTxOutVariant $ do
7171
TxOut --^ do
7272
"A table for transaction outputs."
7373
TxOutAddressId # "The human readable encoding of the output address. It is Base58 for Byron era addresses and Bech32 for Shelley era."
74+
TxOutConsumedByTxId # "The Tx table index of the transaction that consumes this transaction output. Not populated by default, can be activated via tx-out configs."
7475
TxOutDataHash # "The hash of the transaction output datum. (NULL for Txs without scripts)."
7576
TxOutIndex # "The index of this transaction output with the transaction."
7677
TxOutInlineDatumId # "The inline datum of the output, if it has one. New in v13."

‎doc/schema-management.md

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,11 @@ indexes during syncing slows down db-sync and so they are added later. Index
1515
creation is idempotent and the `schema_version.stage_tree` field is ignored.
1616
These files cannot be modified but they can be extended, in case users want to
1717
introduce their own indexes from the begining.
18-
- `stage 4`: introduces all the other indexes. By default these are the indexes
19-
that were created by previous db-sync versions. This stage is executed when
20-
db-sync has reached 30mins before the tip of the chain. It is advised to increase
21-
the `maintenance_work_mem` from Postgres config to 0.5GB - 1GB to speed this
22-
process (default is 64MB). Also use the default (2) or higher
23-
`max_parallel_maintenance_workers`. These files can be modified or extended
24-
by users.
18+
- `stage 4`: introduces all the other indexes. By default these are the indexes that were created by previous db-sync versions. This stage is executed when
19+
db-sync has reached 30mins before the tip of the chain. It is advised to increase the `maintenance_work_mem` from Postgres config to 0.5GB - 1GB to speed this
20+
process (default is 64MB).
21+
Also use the default (2) or higher `max_parallel_maintenance_workers`. These files can be modified or extended
22+
by users.
2523

2624
All of the schema migrations in these three stages are written to be idempotent (so that they
2725
"know" if they have already been applied).
@@ -34,6 +32,11 @@ where the `1` denotes "stage 1" of the SQL migration, the `0000` is the migratio
3432
last number is the date. Listing the directory containing the schema and sorting the list will
3533
order them in the correct order for applying to the database.
3634

35+
Since the introduction of `use_address_table` [config](https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/configuration.md#tx-out). The file `migration-4-001-*` when indexing will not be ran when the this configuration is active.
36+
37+
There is also a flag you can use in cardano-db-tool `--use-tx-out-address` which handles the alternate variation of the schema, one might be using.
38+
39+
3740
## Creating a Migration
3841

3942
Whenever the Haskell schema definition in `Cardano.Db.Schema` is updated, a schema migration will need to be migrated.
@@ -52,6 +55,12 @@ cabal run cardano-db-tool -- create-migration --mdir schema/
5255
```
5356
This will generate a migration if one is needed.
5457

58+
There is an alternate way to create/run a migration when using the `use_txout_address` configuration as previously mentioned, this uses a different variation of the schema.
59+
To do this, you simply add the flag `--use-tx-out-address` like so:
60+
```
61+
PGPASSFILE=config/pgpass-mainnet cabal run cardano-db-tool -- create-migration --use-tx-out-address --mdir schema/
62+
```
63+
5564
Once this has completed it's good practice to rebuild `cardano-db-sync` due to how it caches schema files when built, this can be done using the following documentation [Build and Install](./installing.md#build-and-install)
5665

5766
**Note:** For extra reassurance one can run the test suite to check that the new migration hasn't broken any tests:

‎doc/schema.md

Lines changed: 88 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Schema Documentation for cardano-db-sync
22

3+
Schema version: 13.5.0.2 (from branch **1333-new-AddressDetail-table** which may not accurately reflect the version number)
4+
**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.
5+
36
### `schema_version`
47

58
The version of the database schema. Schema versioning is split into three stages as detailed below. This table should only ever have a single row.
@@ -122,26 +125,6 @@ A table of unique stake addresses. Can be an actual address or a script hash. T
122125
| `view` | string | The Bech32 encoded version of the stake address. |
123126
| `script_hash` | hash28type | The script hash, in case this address is locked by a script. |
124127

125-
### `tx_out`
126-
127-
A table for transaction outputs.
128-
129-
* Primary Id: `id`
130-
131-
| Column name | Type | Description |
132-
|-|-|-|
133-
| `id` | integer (64) | |
134-
| `tx_id` | integer (64) | The Tx table index of the transaction that contains this transaction output. |
135-
| `index` | txindex | The index of this transaction output with the transaction. |
136-
| `address` | string | The human readable encoding of the output address. Will be Base58 for Byron era addresses and Bech32 for Shelley era. |
137-
| `address_has_script` | boolean | Flag which shows if this address is locked by a script. |
138-
| `payment_cred` | hash28type | The payment credential part of the Shelley address. (NULL for Byron addresses). For a script-locked address, this is the script hash. |
139-
| `stake_address_id` | integer (64) | The StakeAddress table index for the stake address part of the Shelley address. (NULL for Byron addresses). |
140-
| `value` | lovelace | The output value (in Lovelace) of the transaction output. |
141-
| `data_hash` | hash32type | The hash of the transaction output datum. (NULL for Txs without scripts). |
142-
| `inline_datum_id` | integer (64) | The inline datum of the output, if it has one. New in v13. |
143-
| `reference_script_id` | integer (64) | The reference script of the output, if it has one. New in v13. |
144-
145128
### `collateral_tx_out`
146129

147130
A table for transaction collateral outputs. New in v13.
@@ -545,19 +528,6 @@ A table containing Multi-Asset mint events.
545528
| `quantity` | int65type | The amount of the Multi Asset to mint (can be negative to "burn" assets). |
546529
| `tx_id` | integer (64) | The Tx table index for the transaction that contains this minting event. |
547530

548-
### `ma_tx_out`
549-
550-
A table containing Multi-Asset transaction outputs.
551-
552-
* Primary Id: `id`
553-
554-
| Column name | Type | Description |
555-
|-|-|-|
556-
| `id` | integer (64) | |
557-
| `ident` | integer (64) | The MultiAsset table index specifying the asset. |
558-
| `quantity` | word64type | The Multi Asset transaction output amount (denominated in the Multi Asset). |
559-
| `tx_out_id` | integer (64) | The TxOut table index for the transaction that this Multi Asset transaction output. |
560-
561531
### `redeemer`
562532

563533
A table containing redeemers. A redeemer is provided for all items that are validated by a script.
@@ -1196,4 +1166,89 @@ A table containing pools that have been delisted.
11961166
| `id` | integer (64) | |
11971167
| `hash_raw` | hash28type | The pool hash |
11981168

1169+
### `tx_out`
1170+
1171+
A table for transaction outputs.
1172+
1173+
* Primary Id: `id`
1174+
1175+
| Column name | Type | Description |
1176+
|-|-|-|
1177+
| `id` | integer (64) | |
1178+
| `address` | string | The human readable encoding of the output address. Will be Base58 for Byron era addresses and Bech32 for Shelley era. |
1179+
| `address_has_script` | boolean | Flag which shows if this address is locked by a script. |
1180+
| `data_hash` | hash32type | The hash of the transaction output datum. (NULL for Txs without scripts). |
1181+
| `consumed_by_tx_id` | integer (64) | The Tx table index of the transaction that consumes this transaction output. Not populated by default, can be activated via tx-out configs. |
1182+
| `index` | txindex | The index of this transaction output with the transaction. |
1183+
| `inline_datum_id` | integer (64) | The inline datum of the output, if it has one. New in v13. |
1184+
| `payment_cred` | hash28type | The payment credential part of the Shelley address. (NULL for Byron addresses). For a script-locked address, this is the script hash. |
1185+
| `reference_script_id` | integer (64) | The reference script of the output, if it has one. New in v13. |
1186+
| `stake_address_id` | integer (64) | The StakeAddress table index for the stake address part of the Shelley address. (NULL for Byron addresses). |
1187+
| `tx_id` | integer (64) | The Tx table index of the transaction that contains this transaction output. |
1188+
| `value` | lovelace | The output value (in Lovelace) of the transaction output. |
1189+
1190+
### `ma_tx_out`
1191+
1192+
A table containing Multi-Asset transaction outputs.
1193+
1194+
* Primary Id: `id`
1195+
1196+
| Column name | Type | Description |
1197+
|-|-|-|
1198+
| `id` | integer (64) | |
1199+
| `ident` | integer (64) | The MultiAsset table index specifying the asset. |
1200+
| `quantity` | word64type | The Multi Asset transaction output amount (denominated in the Multi Asset). |
1201+
| `tx_out_id` | integer (64) | The TxOut table index for the transaction that this Multi Asset transaction output. |
1202+
1203+
# Variant Schema
1204+
1205+
When using the `use_address_table` [configuration](https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/configuration.md#tx-out), the `tx_out` table is split into two tables: `tx_out` and `address`.
1206+
Bellow are the table documentation for this variaton.
1207+
1208+
### `tx_out`
1209+
1210+
A table for transaction outputs.
1211+
1212+
* Primary Id: `id`
1213+
1214+
| Column name | Type | Description |
1215+
|-|-|-|
1216+
| `id` | integer (64) | |
1217+
| `address_id` | integer (64) | The human readable encoding of the output address. It is Base58 for Byron era addresses and Bech32 for Shelley era. |
1218+
| `consumed_by_tx_id` | integer (64) | The Tx table index of the transaction that consumes this transaction output. Not populated by default, can be activated via tx-out configs. |
1219+
| `data_hash` | hash32type | The hash of the transaction output datum. (NULL for Txs without scripts). |
1220+
| `index` | txindex | The index of this transaction output with the transaction. |
1221+
| `inline_datum_id` | integer (64) | The inline datum of the output, if it has one. New in v13. |
1222+
| `reference_script_id` | integer (64) | The reference script of the output, if it has one. New in v13. |
1223+
| `tx_id` | integer (64) | The Tx table index of the transaction that contains this transaction output. |
1224+
| `value` | lovelace | The output value (in Lovelace) of the transaction output. |
1225+
1226+
### `address`
1227+
1228+
A table for addresses that appear in outputs.
1229+
1230+
* Primary Id: `id`
1231+
1232+
| Column name | Type | Description |
1233+
|-|-|-|
1234+
| `id` | integer (64) | |
1235+
| `address` | string | The human readable encoding of the output address. Will be Base58 for Byron era addresses and Bech32 for Shelley era. |
1236+
| `raw` | blob | The raw binary address. |
1237+
| `has_script` | boolean | Flag which shows if this address is locked by a script. |
1238+
| `payment_cred` | hash28type | The payment credential part of the Shelley address. (NULL for Byron addresses). For a script-locked address, this is the script hash. |
1239+
| `stake_address_id` | integer (64) | The StakeAddress table index for the stake address part of the Shelley address. (NULL for Byron addresses). |
1240+
1241+
### `ma_tx_out`
1242+
1243+
A table containing Multi-Asset transaction outputs.
1244+
1245+
* Primary Id: `id`
1246+
1247+
| Column name | Type | Description |
1248+
|-|-|-|
1249+
| `id` | integer (64) | |
1250+
| `ident` | integer (64) | The MultiAsset table index specifying the asset. |
1251+
| `quantity` | word64type | The Multi Asset transaction output amount (denominated in the Multi Asset). |
1252+
| `tx_out_id` | integer (64) | The TxOut table index for the transaction that this Multi Asset transaction output. |
1253+
11991254

0 commit comments

Comments
 (0)