Module fedimint_core::db
source · Expand description
Core Fedimint database traits and types
Isolation of database transactions
Fedimint requires that the database implementation implement Snapshot Isolation. Snapshot Isolation is a database isolation level that guarantees consistent reads from the time that the snapshot was created (at transaction creation time). Transactions with Snapshot Isolation level will only commit if there has been no write to the modified keys since the snapshot (i.e. write-write conflicts are prevented).
Specifically, Fedimint expects the database implementation to prevent the following anomalies:
Non-Readable Write: TX1 writes (K1, V1) at time t but cannot read (K1, V1) at time (t + i)
Dirty Read: TX1 is able to read TX2’s uncommitted writes.
Non-Repeatable Read: TX1 reads (K1, V1) at time t and retrieves (K1, V2) at time (t + i) where V1 != V2.
Phantom Record: TX1 retrieves X number of records for a prefix at time t and retrieves Y number of records for the same prefix at time (t + i).
Lost Writes: TX1 writes (K1, V1) at the same time as TX2 writes (K1, V2). V2 overwrites V1 as the value for K1 (write-write conflict).
| Type | Non-Readable Write | Dirty Read | Non-Repeatable Read | Phantom Record | Lost Writes | | –––– | —————— | ––––– | —————–– | ––––––– | ———– | | MemoryDB | Prevented | Prevented | Prevented | Prevented | Possible | | RocksDB | Prevented | Prevented | Prevented | Prevented | Prevented | | Sqlite | Prevented | Prevented | Prevented | Prevented | Prevented |
Modules
Structs
- Session type for
DatabaseTransaction
that is allowed to commit - A public-facing newtype over
IDatabase
- A high level database transaction handle
- An iterator over the variants of Self
- Session type for a
DatabaseTransaction
that is not allowed to commit
Enums
- Error returned when the autocommit function fails
Constants
Traits
DatabaseKey
that represents the lookup structure for retrieving key/value pairs from the database.- Marker trait for
DatabaseKey
s whereNOTIFY
is true - A key that can be used to query one or more
DatabaseRecord
ExtendsDatabaseKeyPrefix
to prepend the key’s prefix. - A key + value pair in the database with a unique prefix Extends
DatabaseKeyPrefix
to prepend the key’s prefix. DatabaseValue
that represents the value structure of database records.- A database that on top of a raw database operation, implements key notification system.
- Fedimint database transaction
- Additional operations (only some) database transactions expose, on top of
IDatabaseTransactionOpsCore
- Core raw a operations database transactions supports
- Like
IDatabaseTransactionOpsCore
, but typed - Raw database implementation
- An extension trait with convenience operations on
IRawDatabase
- Raw database transaction (e.g. rocksdb implementation)
- A database type that has decoders, which allows it to implement
IDatabaseTransactionOpsCoreTyped
Functions
apply_migrations
iterates from the on disk database version for the module up totarget_db_version
and executes all of the migrations that exist in theMigrationMap
. Each migration inMigrationMap
updates the database to have the correct on-disk structures that the code is expecting. The entire migration process is atomic (i.e migration from 0->1 and 1->2 happen atomically). This function is called before the module is initialized and as long as the correct migrations are supplied inMigrationMap
, the module will be able to read and write from the database successfully.
Type Aliases
- MigrationMap is a BTreeMap that maps DatabaseVersions to async functions. These functions are expected to “migrate” the database from the keyed DatabaseVersion to DatabaseVersion + 1.
- Just ignore this type, it’s only there to make compiler happy