Struct frame_support::migrations::VersionedRuntimeUpgrade

pub struct VersionedRuntimeUpgrade<const FROM: u16, const TO: u16, Inner, Pallet, Weight> { /* private fields */ }

EXPERIMENTAL: The API of this feature may change.

Make it easier to write versioned runtime upgrades.

VersionedRuntimeUpgrade allows developers to write migrations without worrying about checking and setting storage versions. Instead, the developer wraps their migration in this struct which takes care of version handling using best practices.

It takes 5 type parameters:

• From: The version being upgraded from.
• To: The version being upgraded to.
• Inner: An implementation of OnRuntimeUpgrade.
• Pallet: The Pallet being upgraded.
• Weight: The runtime’s RuntimeDbWeight implementation.

When a VersionedRuntimeUpgrade on_runtime_upgrade, pre_upgrade, or post_upgrade method is called, the on-chain version of the pallet is compared to From. If they match, the Inner equivalent is called and the pallets on-chain version is set to To after the migration. Otherwise, a warning is logged notifying the developer that the upgrade was a noop and should probably be removed.

Examples

// In file defining migrations
pub struct VersionUncheckedMigrateV5ToV6<T>(sp_std::marker::PhantomData<T>);
impl<T: Config> OnRuntimeUpgrade for VersionUncheckedMigrateV5ToV6<T> {
	// OnRuntimeUpgrade implementation...
}

pub type VersionCheckedMigrateV5ToV6<T, I> =
	VersionedRuntimeUpgrade<
		5,
		6,
		VersionUncheckedMigrateV5ToV6<T, I>,
		crate::pallet::Pallet<T, I>,
		<T as frame_system::Config>::DbWeight
	>;

// Migrations tuple to pass to the Executive pallet:
pub type Migrations = (
	// other migrations...
	VersionCheckedMigrateV5ToV6<T, ()>,
	// other migrations...
);

Trait Implementations

impl<const FROM: u16, const TO: u16, Inner: OnRuntimeUpgrade, Pallet: GetStorageVersion<CurrentStorageVersion = StorageVersion> + PalletInfoAccess, DbWeight: Get<RuntimeDbWeight>> OnRuntimeUpgrade for VersionedRuntimeUpgrade<FROM, TO, Inner, Pallet, DbWeight>

Implementation of the OnRuntimeUpgrade trait for VersionedRuntimeUpgrade.

Its main function is to perform the runtime upgrade in on_runtime_upgrade only if the on-chain version of the pallets storage matches From, and after the upgrade set the on-chain storage to To. If the versions do not match, it writes a log notifying the developer that the migration is a noop.

fn pre_upgrade() -> Result<Vec<u8>, TryRuntimeError>

Executes pre_upgrade if the migration will run, and wraps the pre_upgrade bytes in VersionedPostUpgradeData before passing them to post_upgrade, so it knows whether the migration ran or not.

fn on_runtime_upgrade() -> Weight

Executes the versioned runtime upgrade.

First checks if the pallets on-chain storage version matches the version of this upgrade. If it matches, it calls Inner::on_runtime_upgrade, updates the on-chain version, and returns the weight. If it does not match, it writes a log notifying the developer that the migration is a noop.

fn post_upgrade( versioned_post_upgrade_data_bytes: Vec<u8> ) -> Result<(), TryRuntimeError>

Executes Inner::post_upgrade if the migration just ran.

pre_upgrade passes VersionedPostUpgradeData::MigrationExecuted to post_upgrade if the migration ran, and VersionedPostUpgradeData::Noop otherwise.

fn try_on_runtime_upgrade(checks: bool) -> Result<Weight, TryRuntimeError>

The expected and default behavior of this method is to handle executing pre_upgrade -> on_runtime_upgrade -> post_upgrade hooks for a migration.