Module db

Database handling 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

• mem_impl
• notifications

Structs

• Committable
  Session type for DatabaseTransaction that is allowed to commit
• Database
  A public-facing newtype over IDatabase
• DatabaseTransaction
  A high level database transaction handle
• DatabaseVersion
• DatabaseVersionKey
• DatabaseVersionKeyV0
  Deprecated: Use DatabaseVersionKey(ModuleInstanceId) instead.
• DbKeyPrefixIter
  An iterator over the variants of DbKeyPrefix
• MigrationContext
• NonCommittable
  Session type for a DatabaseTransaction that is not allowed to commit

Enums

• AutocommitError
  Error returned when the autocommit function fails
• DbKeyPrefix
• DecodingError
• TestDbKeyPrefix

Constants

• MODULE_GLOBAL_PREFIX

Traits

• DatabaseKey
  DatabaseKey that represents the lookup structure for retrieving key/value pairs from the database.
• DatabaseKeyPrefix
• DatabaseKeyWithNotify
  Marker trait for DatabaseKeys where NOTIFY is true
• DatabaseLookup
  A key that can be used to query one or more DatabaseRecord Extends DatabaseKeyPrefix to prepend the key’s prefix.
• DatabaseRecord
  A key + value pair in the database with a unique prefix Extends DatabaseKeyPrefix to prepend the key’s prefix.
• DatabaseValue
  DatabaseValue that represents the value structure of database records.
• IDatabase
  A database that on top of a raw database operation, implements key notification system.
• IDatabaseTransaction
  Fedimint database transaction
• IDatabaseTransactionOps
  Additional operations (only some) database transactions expose, on top of IDatabaseTransactionOpsCore
• IDatabaseTransactionOpsCore
  Core raw a operations database transactions supports
• IDatabaseTransactionOpsCoreTyped
  Like IDatabaseTransactionOpsCore, but typed
• IRawDatabase
  Raw database implementation
• IRawDatabaseExt
  An extension trait with convenience operations on IRawDatabase
• IRawDatabaseTransaction
  Raw database transaction (e.g. rocksdb implementation)
• WithDecoders
  A database type that has decoders, which allows it to implement IDatabaseTransactionOpsCoreTyped

Functions

• apply_migrations
  apply_migrations iterates from the on disk database version for the module up to target_db_version and executes all of the migrations that exist in the migrations map. Each migration in migrations map 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 in the migrations map, the module will be able to read and write from the database successfully.
• apply_migrations_server
  Applies the database migrations to a non-isolated database.
• create_database_version
  Creates the DatabaseVersion inside the database if it does not exist. If necessary, this function will migrate the legacy database version to the expected DatabaseVersionKey.
• expect_write_conflict
• find_by_prefix_sorted_descending
• future_returns_shortly
• verify_commit
• verify_find_by_prefix
• verify_insert_elements
• verify_module_db
• verify_module_prefix
• verify_phantom_entry
• verify_prevent_dirty_reads
• verify_prevent_nonrepeatable_reads
• verify_read_own_writes
• verify_remove_by_prefix
• verify_remove_existing
• verify_remove_nonexisting
• verify_rollback_to_savepoint
• verify_snapshot_isolation
• verify_string_prefix

Type Aliases

• CoreMigrationFn
  CoreMigrationFn that modules can implement to “migrate” the database to the next database version.
• PhantomBound
  Just ignore this type, it’s only there to make compiler happy
• PrefixStream