Substrate Migrations

A repository of Substrate runtime migrations.

Contributing

Feel free to open PRs to include your own examples of applying Substrate migrations and/or notes.

Links

Storage migrations knowledgebase article on the DevHub.
Substrate PRs including migration relevant code.

Relevant PRs

Run custom OnRuntimeUpgrade first (before frame_system)

FRAME Migrations

This lists PRs that include or induce storage migrations in FRAME pallets after Substrate 2.0 with some examples of how they were implemented in production chains.

`2021-09-17` Implement `pallet-bags-list` and its Interfaces with `pallet-staking`

paritytech/substrate#9507

Examples

Polkadot: paritytech/polkadot#3413

`2021-09-06` Remove State Rent in `pallet-contracts`

paritytech/substrate#9669

`2021-07-21` Move `PalletVersion` Away from Crate Version

Moves from using the Rust crate version to a dedicated version number for the pallet storage version.

paritytech/substrate#9165

See paritytech/substrate#9165 (comment) for how to execute the resulting storage migration.

Examples

Polkadot: paritytech/polkadot#3526

`2021-06-16` Add Control to Growth of the Staking Pallet

Introduces counts for the nominators and validators.

paritytech/substrate#8920

`2021-05-28` Simple `MaxBoundedLen` Implementations

Two potential reasons for migrations:

The assets and proxy pallets now use BoundedVec, so if the storage contains entries that overshoot the configured StringLimit for assets or MaxProxies for proxy they will need a migration.
The time delayed proxies migration function was removed.

paritytech/substrate#8793

`2021-05-13` Contracts: Move `Schedule` from Storage to `Config`

Removes the contracts pallet's schedule from storage and puts it in the pallet configuration instead.

paritytech/substrate#8773

`2021-05-03` Remove Offence Delay

paritytech/substrate#8414

`2021-03-20` Decouple Staking and Election - Part 2.1: Unleash Multi Phase

paritytech/substrate#8113

Examples

Polkadot: paritytech/polkadot#2432

`2021-03-12` Update Contracts Schedule to v3

paritytech/substrate#8231

`2021-03-10` Babe Epoch Configurations

paritytech/substrate#8072

Examples

Polkadot: paritytech/polkadot#2467

`2021-03-03` Self-Sufficient Ref-Counting

paritytech/substrate#8221

Required for: paritytech/substrate#8220

`2021-02-10` Substrate v3.0.0

`2021` Migrate FRAME Pallets to Procedural `#[pallet]` Macro

Using the procedural macro shifts the storage prefix from the decl_storage macro invocation to the pallet instantiation in the construct_runtime macro. As a result migrations to the new macro do not inherently require a migration, but might incidentally create the necessity if care is not taken to make sure that the prefix stays the same.

PRs porting pallets to the new procedural macro that were merged in 2021 are listed here:

`2021-01-20` Fix Phragmen and Proxy Issue

paritytech/substrate#7040

Examples

Polkadot: paritytech/polkadot#1719

`2021-01-20` Nominator Set Kicking & Blocking

paritytech/substrate#7930

`2020-10-21` Pallet Storage Versions

Should not require any manual code as the version is updated automatically on every on_runtime_upgrade.

paritytech/substrate#7208

`2020-09-24` Time-Delay Proxies Migration Fix

Note: If using the introduced migration function, you should use storage version guards to make sure it only runs once.

paritytech/substrate#7205

`2020-09-22` Substrate v2.0.0

Pre 2.0 Migrations

This lists PRs that include or induce storage migrations before Substrate 2.0 with some examples of how they were implemented in production chains.

`2020-09-22` Move Account Refcounts from `u8` to `u32`

paritytech/substrate#7164

`2020-09-22` Allow Specifying Fixed Index in `construct_runtime`

paritytech/substrate#6969

Examples

Polkadot: paritytech/polkadot#1692

`2020-08-23` Time-Delay Proxies

Warning: This migration is missing a storage guard so it might be applied more than once if included in more than one runtime uprade. Use the extracted migration from paritytech/substrate#7205 in combination with a storage guard if running this migration.

paritytech/substrate#6770