Crate ab_client_database

Client database.

High-level architecture overview

The database operates on ClientDatabaseStorageBackend, which is backed by AlignedPages that can be read or written. Pages contain StorageItems, one storage item can occupy one or more pages, but pages always belong to a single storage item. Pages are the smallest unit and align nicely with the hardware architecture of modern SSDs. Each page starts with a prefix that describes the contents of the page. StorageItem always starts at the multiple of the u128/16 bytes, allowing for direct memory mapping onto target data structures.

Individual pages are grouped into page groups (configurable via ClientDatabaseOptions). Page groups can be permanent and ephemeral. Permanent page groups store information that is never going to be deleted, like segment headers. Ephemeral page groups store the majority of the information about blocks, blockchain state and other things that are being created all the time. Once information in an ephemeral page group is too old and no longer needed, it can be repurposed for a new permanent or ephemeral page group. There are different kinds of page groups defined in PageGroupKind, and each variant has independent sequence numbers.

Page groups are append-only, there is only one active permanent and one ephemeral page group. They are appended with more pages containing storage items until there is no space to add a complete storage item, after which the next page group is started.

Ephemeral page groups can be freed only when they contain 100% outdated storage items. Individual pages can’t be freed.

Each storage item has a sequence number and checksums that help to define the global ordering and check whether a storage item was written fully. Upon restart, the page group containing the latest storage items is found, and the latest fully written storage item is identified to reconstruct the database state.

Each page group starts with a StorageItemPageGroupHeader storage item for easier identification.

The database is typically contained in a single file (though in principle could be contained in multiple if necessary). Before the database can be used, it needs to be formatted with a specific size (it is possible to increase the size afterward) before it can be used. It is expected (but depends on the storage backend) that the whole file size is pre-allocated on disk and no writes will fail due to lack of disk space (which could be the case with a sparse file).

Modules

storage_backend

Structs

ClientDatabase

Client database

ClientDatabaseFormatOptions

Options for ClientDatabase

ClientDatabaseOptions

Options for ClientDatabase

DatabaseId

Unique identifier for a database

GenesisBlockBuilderResult

Enums

ClientDatabaseError

ClientDatabaseFormatError

Error for ClientDatabase::format()