Upgrading Modules

Synopsis In-Place Store Migrations allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality.

Pre-requisite Readings

• In-Place Store Migration

Consensus Version

Successful upgrades of existing modules require each AppModule to implement the function ConsensusVersion() uint64.

• The versions must be hard-coded by the module developer.
• The initial version must be set to 1.

Consensus versions serve as state-breaking versions of app modules and must be incremented when the module introduces breaking changes.

Registering Migrations

To register the functionality that takes place during a module upgrade, you must register which migrations you want to take place.

Migration registration takes place in the Configurator using the RegisterMigration method. The AppModule reference to the configurator is in the RegisterServices method.

You can register one or more migrations. If you register more than one migration script, list the migrations in increasing order and ensure there are enough migrations that lead to the desired consensus version. For example, to migrate to version 3 of a module, register separate migrations for version 1 and version 2 as shown in the following example:

func (am AppModule)

RegisterServices(cfg module.Configurator) {
    // --snip--
    cfg.RegisterMigration(types.ModuleName, 1, func(ctx sdk.Context)

error {
        // Perform in-place store migrations from ConsensusVersion 1 to 2.
})

cfg.RegisterMigration(types.ModuleName, 2, func(ctx sdk.Context)

error {
        // Perform in-place store migrations from ConsensusVersion 2 to 3.
})
}

Since these migrations are functions that need access to a Keeper’s store, use a wrapper around the keepers called Migrator as shown in this example:

package keeper

import (
    
	sdk "github.com/cosmos/cosmos-sdk/types"
    "github.com/cosmos/cosmos-sdk/x/bank/exported"
	v2 "github.com/cosmos/cosmos-sdk/x/bank/migrations/v2"
	v3 "github.com/cosmos/cosmos-sdk/x/bank/migrations/v3"
	v4 "github.com/cosmos/cosmos-sdk/x/bank/migrations/v4"
)

// Migrator is a struct for handling in-place store migrations.
type Migrator struct {
    keeper         BaseKeeper
	legacySubspace exported.Subspace
}

// NewMigrator returns a new Migrator.
func NewMigrator(keeper BaseKeeper, legacySubspace exported.Subspace)

Migrator {
    return Migrator{
    keeper: keeper, legacySubspace: legacySubspace
}
}

// Migrate1to2 migrates from version 1 to 2.
func (m Migrator)

Migrate1to2(ctx sdk.Context)

error {
    return v2.MigrateStore(ctx, m.keeper.storeKey, m.keeper.cdc)
}

// Migrate2to3 migrates x/bank storage from version 2 to 3.
func (m Migrator)

Migrate2to3(ctx sdk.Context)

error {
    return v3.MigrateStore(ctx, m.keeper.storeKey, m.keeper.cdc)
}

// Migrate3to4 migrates x/bank storage from version 3 to 4.
func (m Migrator)

Migrate3to4(ctx sdk.Context)

error {
    return v4.MigrateStore(ctx, m.keeper.storeKey, m.legacySubspace, m.keeper.cdc)
}

Writing Migration Scripts

To define the functionality that takes place during an upgrade, write a migration script and place the functions in a migrations/ directory. For example, to write migration scripts for the bank module, place the functions in x/bank/migrations/. Use the recommended naming convention for these functions. For example, v2bank is the script that migrates the package x/bank/migrations/v2:

// Migrating bank module from version 1 to 2
func (m Migrator)

Migrate1to2(ctx sdk.Context)

error {
    return v2bank.MigrateStore(ctx, m.keeper.storeKey) // v2bank is package `x/bank/migrations/v2`.
}

To see example code of changes that were implemented in a migration of balance keys, check out migrateBalanceKeys. For context, this code introduced migrations of the bank store that updated addresses to be prefixed by their length in bytes as outlined in ADR-028.