diff --git a/docs/building-modules/upgrade.md b/docs/building-modules/upgrade.md index 53864fa58..2f9eaa98f 100644 --- a/docs/building-modules/upgrade.md +++ b/docs/building-modules/upgrade.md @@ -8,7 +8,7 @@ In-place store migrations allow your modules to upgrade to new versions that inc ## Prerequisite Readings -- [In-Place Store Migration](../core-concepts/upgrade.md) {prereq} +- [In-Place Store Migration](../core/upgrade.md) {prereq} ## Consensus Version diff --git a/docs/core/upgrade.md b/docs/core/upgrade.md index 4e48e10b9..c37d81387 100644 --- a/docs/core/upgrade.md +++ b/docs/core/upgrade.md @@ -82,6 +82,29 @@ To learn more about configuring migration scripts for your modules, see the [Mig You can introduce entirely new modules to the application during an upgrade. New modules are recognized because they have not yet been registered in `x/upgrade`'s `VersionMap` store. In this case, `RunMigrations` calls the `InitGenesis` function from the corresponding module to set up its initial state. +### Add StoreUpgrades for New Modules + +All chains preparing to run in-place store migrations will need to manually add store upgrades for new modules and then configure the store loader to apply those upgrades. This ensures that the new module's stores are added to the multistore before the migrations begin. + +```golang +upgradeInfo, err := app.UpgradeKeeper.ReadUpgradeInfoFromDisk() +if err != nil { + panic(err) +} + +if upgradeInfo.Name == "my-plan" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) { + storeUpgrades := storetypes.StoreUpgrades{ + // add store upgrades for new modules + // Example: + // Added: []string{"foo", "bar"}, + // ... + } + + // configure store loader that checks if version == upgradeHeight and applies store upgrades + app.SetStoreLoader(upgradetypes.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades)) +} +``` + ## Overwriting Genesis Functions The Cosmos SDK offers modules that the application developer can import in their app. These modules often have an `InitGenesis` function already defined.