Enum DbFormatChange

pub enum DbFormatChange {
    Upgrade {
        older_disk_version: Version,
        newer_running_version: Version,
    },
    NewlyCreated {
        running_version: Version,
    },
    Downgrade {
        newer_disk_version: Version,
        older_running_version: Version,
    },
    CheckOpenCurrent {
        running_version: Version,
    },
    CheckNewBlocksCurrent {
        running_version: Version,
    },
}

The kind of database format change or validity check we’re performing.

Variants

Upgrade

Upgrade the format from older_disk_version to newer_running_version.

Until this upgrade is complete, the format is a mixture of both versions.

Fields

older_disk_version: Version

newer_running_version: Version

NewlyCreated

Mark the format as newly created by running_version.

Newly created databases are opened with no disk version. It is set to the running version by the format change code.

Fields

running_version: Version

Downgrade

Mark the format as downgraded from newer_disk_version to older_running_version.

Until the state is upgraded to newer_disk_version by a Zebra version with that state version (or greater), the format will be a mixture of both versions.

Fields

newer_disk_version: Version

older_running_version: Version

CheckOpenCurrent

Check that the database from a previous instance has the current running_version format.

Current version databases have a disk version that matches the running version. No upgrades are needed, so we just run a format check on the database. The data in that database was created or updated by a previous Zebra instance.

Fields

running_version: Version

CheckNewBlocksCurrent

Check that the database from this instance has the current running_version format.

The data in that database was created or updated by the currently running Zebra instance. So we periodically check for data bugs, which can happen if the upgrade and new block code produce different data. (They can also be caused by disk corruption.)

Fields

running_version: Version

Implementations

impl DbFormatChange

pub fn open_database( running_version: &Version, disk_version: Option<Version>, ) -> Self

Returns the format change for running_version code loading a disk_version database.

Also logs that change at info level.

If disk_version is None, Zebra is creating a new database.

pub fn check_new_blocks(db: &ZebraDb) -> Self

Returns a format check for newly added blocks in the currently running Zebra version. This check makes sure the upgrade and new block code produce the same data.

Also logs the check at info level.

pub fn is_upgrade(&self) -> bool

Returns true if this format change/check is an upgrade.

pub fn is_run_at_startup(&self) -> bool

Returns true if this format change/check happens at startup.

pub fn running_version(&self) -> Version

Returns the running version in this format change.

pub fn initial_disk_version(&self) -> Option<Version>

Returns the initial database version before this format change.

Returns None if the database was newly created.

pub fn spawn_format_change( self, db: ZebraDb, initial_tip_height: Option<Height>, ) -> DbFormatChangeThreadHandle

Launch a std::thread that applies this format change to the database, then continues running to perform periodic format checks.

initial_tip_height is the database height when it was opened, and db is the database instance to upgrade or check.

fn format_change_run_loop( self, db: ZebraDb, initial_tip_height: Option<Height>, cancel_receiver: Receiver<CancelFormatChange>, ) -> Result<(), CancelFormatChange>

Run the initial format change or check to the database. Under the default runtime config, this method returns after the format change or check.

But if runtime validity checks are enabled, this method periodically checks the format of newly added blocks matches the current format. It will run until it is cancelled or panics.

pub(crate) fn run_format_change_or_check( &self, db: &ZebraDb, initial_tip_height: Option<Height>, cancel_receiver: &Receiver<CancelFormatChange>, ) -> Result<(), CancelFormatChange>

Run a format change in the database, or check the format of the database once.

fn apply_format_upgrade( &self, db: &ZebraDb, initial_tip_height: Option<Height>, cancel_receiver: &Receiver<CancelFormatChange>, ) -> Result<(), CancelFormatChange>

Apply any required format updates to the database. Format changes should be launched in an independent std::thread.

If cancel_receiver gets a message, or its sender is dropped, the format change stops running early, and returns an error.

See the format upgrade design docs for more details: https://github.com/ZcashFoundation/zebra/blob/main/book/src/dev/state-db-upgrades.md#design

pub fn format_validity_checks_quick(db: &ZebraDb) -> Result<(), String>

Run quick checks that the current database format is valid.

pub fn format_validity_checks_detailed( db: &ZebraDb, cancel_receiver: &Receiver<CancelFormatChange>, ) -> Result<Result<(), String>, CancelFormatChange>

Run detailed checks that the current database format is valid.

fn check_for_duplicate_trees( db: &ZebraDb, cancel_receiver: &Receiver<CancelFormatChange>, ) -> Result<Result<(), String>, CancelFormatChange>

Check that note commitment trees were correctly de-duplicated.

fn mark_as_newly_created(db: &ZebraDb)

Mark a newly created database with the current format version.

This should be called when a newly created database is opened.

Concurrency

The version must only be updated while RocksDB is holding the database directory lock. This prevents multiple Zebra instances corrupting the version file.

Panics

If the format should not have been upgraded, because the database is not newly created.

fn mark_as_upgraded_to(db: &ZebraDb, format_upgrade_version: &Version)

Mark the database as upgraded to format_upgrade_version.

This should be called when an older database is opened by an older Zebra version, after each version upgrade is complete.

Concurrency

The version must only be updated while RocksDB is holding the database directory lock. This prevents multiple Zebra instances corrupting the version file.

Panics

If the format should not have been upgraded, because the running version is:

• older than the disk version (that’s a downgrade)
• the same as to the disk version (no upgrade needed)

If the format should not have been upgraded, because the format upgrade version is:

• older or the same as the disk version (multiple upgrades to the same version are not allowed)
• greater than the running version (that’s a logic bug)

fn mark_as_downgraded(db: &ZebraDb)

Mark the database as downgraded to the running database version. This should be called after a newer database is opened by an older Zebra version.

Concurrency

The version must only be updated while RocksDB is holding the database directory lock. This prevents multiple Zebra instances corrupting the version file.

Panics

If the format should have been upgraded, because the running version is newer. If the state is newly created, because the running version should be the same.

Multiple downgrades are allowed, because they all downgrade to the same running version.

Trait Implementations

impl Clone for DbFormatChange

fn clone(&self) -> DbFormatChange

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DbFormatChange

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for DbFormatChange

fn eq(&self, other: &DbFormatChange) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for DbFormatChange

impl StructuralPartialEq for DbFormatChange