doc(katana): db table layout

[kariy]

Initial effort in improving documentations for katana. This adds an ER diagram loosely representing the logical model of katana's DB table schema using mermaid diagram so it can be easily embedded in markdown.

---

Disclaimer: This is my first ERD in a long time, so I'm definitely not sure whether it is correctly visualizing the tables relations with one another.

[kariy]

erDiagram
Headers {
    KEY BlockNumber
    VALUE Header 
}
BlockHashes {
    KEY BlockNumber
    VALUE BlockHash
}
BlockNumbers {
    KEY BlockHash
    VALUE BlockNumber
}
BlockStatusses {
    KEY BlockNumber
    VALUE FinalityStatus
}
BlockBodyIndices {
    KEY BlockNumber
    VALUE StoredBlockBodyIndices
}
TxNumbers {
    KEY TxHash
    VALUE TxNumber
}
TxHashes {
    KEY TxNumber
    VALUE TxHash
}
Transactions {
    KEY TxNumber
    VALUE Tx
}
TxBlocks {
    KEY TxNumber
    VALUE BlockNumber
}
Receipts {
    KEY TxNumber
    VALUE Receipt
}
CompiledClassHashes {
    KEY ClassHash
    VALUE CompiledClassHash
}
CompiledContractClasses {
    KEY ClassHash
    VALUE StoredContractClass
}
SierraClasses {
    KEY ClassHash
    VALUE FlattenedSierraClass
}
ContractInfo {
    KEY ContractAddress
    VALUE GenericContractInfo
}
ContractStorage {
    KEY ContractAddress
    DUP_KEY StorageKey
    VALUE StorageEntry
}
ClassDeclarationBlock {
    KEY ClassHash
    VALUE BlockNumber
}
ClassDeclarations {
    KEY BlockNumber
    DUP_KEY ClassHash
    VALUE ClassHash
}
ContractInfoChangeSet {
    KEY ContractAddress
    VALUE ContractInfoChangeList
}
NonceChanges {
    KEY BlockNumber
    DUP_KEY ContractAddress
    VALUE ContractNonceChange
}
ContractClassChanges {
    KEY BlockNumber
    DUP_KEY ContractAddress
    VALUE ContractClassChange
}
StorageChangeSet {
    KEY ContractAddress
    DUP_KEY StorageKey
    VALUE StorageEntryChangeList
}
StorageChanges {
    KEY BlockNumber
    DUP_KEY ContractStorageKey
    VALUE ContractStorageEntry
}
BlockHashes ||--|| BlockNumbers : "block id"
BlockNumbers ||--|| BlockBodyIndices : "has"
BlockNumbers ||--|| Headers : "has"
BlockNumbers ||--|| BlockStatusses : "has"
BlockBodyIndices ||--o{ Transactions : "block txs"
TxHashes ||--|| TxNumbers : "tx id"
TxNumbers ||--|| Transactions : "has"
TxBlocks ||--|{ Transactions : "tx block"
Transactions ||--|| Receipts : "each tx must have a receipt"
CompiledClassHashes ||--|| CompiledContractClasses : "has"
CompiledClassHashes ||--|| SierraClasses : "has"
SierraClasses |o--|| CompiledContractClasses : "has"
ContractInfo ||--o{ ContractStorage : "a contract storage slots"
ContractInfo ||--|| CompiledClassHashes : "has"
ContractInfo }|--|{ ContractInfoChangeSet : "has"
ContractStorage }|--|{ StorageChangeSet : "has"
ContractInfoChangeSet }|--|{ NonceChanges : "has"
ContractInfoChangeSet }|--|{ ContractClassChanges : "has"
CompiledClassHashes ||--|| ClassDeclarationBlock : "has"
ClassDeclarationBlock ||--|| ClassDeclarations : "has"
BlockNumbers ||--|| ClassDeclarations : ""
StorageChangeSet }|--|{ StorageChanges : "has"

Loading

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (87599f9) 67.62% compared to head (f78115c) 67.62%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1442   +/-   ##
=======================================
  Coverage   67.62%   67.62%           
=======================================
  Files         218      218           
  Lines       21060    21060           
=======================================
  Hits        14242    14242           
  Misses       6818     6818           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[glihm]

Thanks for this effort, it gaves a good graphical overview of the work done on the database.

1. I suggest to homogenize the entity names (and this tables name) at singular instead of plural.
2. For the relationship same thing, ensuring we've a verb and consistent way to describe them. BlockHash to BlockNumber may be something like "Maps to" for instance.

[kariy]

1. I suggest to homogenize the entity names (and this tables name) at singular instead of plural.

The entity names are the actual table names. Unless you're suggesting that we should update the table names as well, I don't think the entity names should be different than what it's trying to represent as the diagram it just trying to explain logically how the table data are related. Lmk what you think on this.

2. For the relationship same thing, ensuring we've a verb and consistent way to describe them. BlockHash to BlockNumber may be something like "Maps to" for instance.

Make sense. I had no idea what to put so just wrote has everywhere but agree on having more descriptive relationship labels would make understanding the diagram easier. Will try to update on this.

[glihm]

The entity names are the actual table names. Unless you're suggesting that we should update the table names as well, I don't think the entity names should be different than what it's trying to represent as the diagram it just trying to explain logically how the table data are related. Lmk what you think on this.

Yep I'll be supportive of rewording yes, but that can be done in a code refacto in subsequent work as it's also code related as you mentioned.

[kariy]

Yep I'll be supportive of rewording yes, but that can be done in a code refacto in subsequent work as it's also code related as you mentioned.

singularizing the table names would be sorta conflicting with some of the primitive types that are used as the tables' value (eg BlockNumber, TxNumber, Receipt etc) especially in the provider impl where both the table and primitive types are used.

I think having plural name for db tables is a pretty common convention. It is also a convention used by torii sql db. So I'm not keen on changing it to singular form.

[glihm]

Yep I'll be supportive of rewording yes, but that can be done in a code refacto in subsequent work as it's also code related as you mentioned.

singularizing the table names would be sorta conflicting with some of the primitive types that are used as the tables' value (eg BlockNumber, TxNumber, Receipt etc) especially in the provider impl where both the table and primitive types are used.

I think having plural name for db tables is a pretty common convention. It is also a convention used by torii sql db. So I'm not keen on changing it to singular form.

Thanks for the feedback and context, good point.