Struct frame_support::migrations::VersionedMigration

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

Handles storage migration pallet versioning.

VersionedMigration 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 UncheckedOnRuntimeUpgrade.
• Pallet: The Pallet being upgraded.
• Weight: The runtime’s RuntimeDbWeight implementation.

When a VersionedMigration 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 UncheckedOnRuntimeUpgrade 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.

By not bounding Inner with OnRuntimeUpgrade, we prevent developers from accidentally using the unchecked version of the migration in a runtime upgrade instead of VersionedMigration.

Examples

// In file defining migrations

/// Private module containing *version unchecked* migration logic.
///
/// Should only be used by the [`VersionedMigration`] type in this module to create something to
/// export.
///
/// We keep this private so the unversioned migration cannot accidentally be used in any runtimes.
///
/// For more about this pattern of keeping items private, see
/// - https://github.com/rust-lang/rust/issues/30905
/// - https://internals.rust-lang.org/t/lang-team-minutes-private-in-public-rules/4504/40
mod version_unchecked {
	use super::*;
	pub struct VersionUncheckedMigrateV5ToV6<T>(sp_std::marker::PhantomData<T>);
	impl<T: Config> UncheckedOnRuntimeUpgrade for VersionUncheckedMigrateV5ToV6<T> {
		// `UncheckedOnRuntimeUpgrade` implementation...
	}
}

pub type MigrateV5ToV6<T, I> =
	VersionedMigration<
		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...
	MigrateV5ToV6<T, ()>,
	// other migrations...
);

Trait Implementations

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

Implementation of the OnRuntimeUpgrade trait for VersionedMigration.

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 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.