I am working on Substrate-based node upgrades.

I stick to Polkadot releases and start from polkadot-v0.8.25 to the latest versions. While upgrading I need to make sure that I don’t miss any storage migrations. I’ve tried this algorithm:

  1. Find migration code in the Substrate repository.
  2. Find the location of the migration execution in the Substrate repository.
  3. If the execution location isn’t found in the Substrate repository and is found in the Polkadot repository, I consider adding this migration to my node.

But this approach is very time consuming so I’m looking for some optimisations. I’ve checked couple of releases along with a bunch of PRs with “E1-runtimemigration” label and it looks like there are two ways to execute a migration:

  1. From a pallet itself via onRuntimeUpgrade hook (or some other handlers) and decl_storage!. Looks like I don’t need to execute this type of migration on my own.
  2. From runtime/polkadot/src/lib.rs -> frame_executive::Executive.

The questions:

  1. Can someone confirm that I should care only about the migrations executed from runtime/polkadot/src/lib.rs -> frame_executive::Executive?
  2. If I am wrong, what are the other places to execute the migrations and how to identify them?

2 Answers 2


As far as I understood from your explanations you are running a custom node based on polkadot release tags from the substrate repo. In which case you should indeed follow the migrations found in Polkadot runtime, but only for the pallets you have attached to the runtime.

There are some other migrations that could be executed automatically when you upgrade to the next release, if the pallet implements OnRuntimeUpgrade, however most if not all of the pallets come with migrations that you need to manually supply in the runtime, for more fine-grained control over the sequence.

Unfortunately, there’s currently no better way to list all the necessary migrations than checking out this tag in substrate and this one in polkadot repo.


It is not clear from your description if you are making changes to storage that later need to be applied to an already running Production chain or if you are just developing and change storage.

If it is the former I would suggest that you very carefully consider what the final storage will look like and just build that. Although technically it can be changed later, there are many risks for a production environment, so storage versions are important to consider.

If it is the latter, you never need to do this! Just purge your chain data which clears all the storage and start with new data.

  • I'll try to explain explain in more detail. 1. I have a Production chain based on release Polkadot release v0.8.25 (for each Polkadot release there is a branch or tag in Substrate repo). 2. I need functionality from Polkadot v0.9.19 release. 3. To have it, I need to apply all node upgrades from v0.8.25 to v0.9.19 one by one. 4. Some of the releases contain storage migrations. In Polkadot repo they are all applied but in Substrate repo there is only migration code. 5. So I'm looking for an optimal way to identify all required migrations to apply during the upgrades. Commented Nov 21, 2022 at 7:39
  • If you are running a Polkadot node and it is sync'd to the current block - you do not need to do anything at all. Simply clone and compile the more recent version of polkadot, and run it - no migration necessary. Why are you making this more complicated?
    – T9b
    Commented Dec 6, 2022 at 22:13

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.