ADR 041: In-Place Store Migrations

​

变更记录

• 17.02.2021：初始草案

​

状态

​

摘要

​

背景

• 该流程耗时较长。运行 export 命令可能需要数小时，之后在新链上使用迁移后的 JSON 运行 InitChain 还可能额外耗费数小时。
• 导出的 JSON 文件可能非常庞大（约为 ~100MB-1GB），难以查看、编辑和传输，这又会带来额外工作去解决这些问题（例如 streaming genesis）。

​

决策

​

模块 ConsensusVersion

type AppModule interface {
    // --snip--
    ConsensusVersion() uint64
}

​

模块专属迁移函数

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.
    })
    // etc.
}

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

// Migrate1to2 migrates from version 1 to 2.
func (m Migrator) Migrate1to2(ctx sdk.Context) error {
    return v2bank.MigrateStore(ctx, m.keeper.storeKey) // v043bank is package `x/bank/migrations/v2`.
}

​

在 x/upgrade 中跟踪模块版本

0x2 | {bytes(module_name)} => BigEndian(module_consensus_version)

- type UpgradeHandler func(ctx sdk.Context, plan Plan)
+ type UpgradeHandler func(ctx sdk.Context, plan Plan, versionMap VersionMap) (VersionMap, error)

func (k UpgradeKeeper) ApplyUpgrade(ctx sdk.Context, plan types.Plan) {
    // --snip--
-   handler(ctx, plan)
+   updatedVM, err := handler(ctx, plan, k.GetModuleVersionMap(ctx)) // k.GetModuleVersionMap() fetches the VersionMap stored in state.
+   if err != nil {
+       return err
+   }
+
+   // Set the updated consensus versions to state
+   k.SetModuleVersionMap(ctx, updatedVM)
}

​

运行迁移

• 从其 VersionMap 参数中获取模块旧的 ConsensusVersion（记为 M）。
• 通过 AppModule 上的 ConsensusVersion() 方法获取模块新的 ConsensusVersion（记为 N）。
• 如果 N>M，则按顺序运行该模块所有已注册的迁移：M -> M+1 -> M+2...，直到 N。
  • 有一种特殊情况：如果该模块没有对应的 ConsensusVersion，说明该模块是在升级过程中新增的。此时不会运行任何迁移函数，而是将该模块当前的 ConsensusVersion 保存到 x/upgrade 的存储中。

app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgradetypes.Plan, vm module.VersionMap) (module.VersionMap, error) {
    return app.mm.RunMigrations(ctx, vm)
})

• 旧二进制会在开始区块 N 时于 BeginBlock 中停机。在其存储中，保存着旧二进制各模块的 ConsensusVersion。
• 新二进制会从区块 N 启动。UpgradeHandler 已在新二进制中设置，因此会在新二进制的 BeginBlock 中运行。在 x/upgrade 的 ApplyUpgrade 内部，将从存储（即旧二进制的存储）中取出 VersionMap，并传入 RunMigrations 函数，在各模块自己的 BeginBlock 运行前原地迁移所有模块的存储。

​

影响

​

向后兼容性

​

正面影响

• 执行链升级时无需再操作 JSON 文件。
• 虽然目前尚无基准测试，但原地存储迁移很可能比 JSON 迁移耗时更少。支持这一判断的主要原因是：旧二进制中的 simd export 命令和新二进制中的 InitChain 函数都将被跳过。

​

负面影响

• 模块开发者必须正确跟踪其模块中的破坏共识变更。如果某个模块引入了破坏共识的变更，却没有同步提升对应的 ConsensusVersion()，那么 RunMigrations 函数将无法检测到该迁移，链升级可能会失败。文档应当明确反映这一点。

​

中性影响

• Cosmos SDK 将继续通过现有的 simd export 和 simd genesis migrate 命令支持 JSON 迁移。
• 当前 ADR 不支持创建、重命名或删除存储，只支持修改现有存储键和值。Cosmos SDK 已经提供 StoreLoader 来执行这些操作。

​

后续讨论

​

参考资料

• 初始讨论：Link
• ConsensusVersion 和 RunMigrations 的实现：Link
• 讨论 x/upgrade 设计的议题：Link

​

Changelog

• 17.02.2021: Initial Draft

​

Status

​

Abstract

​

Context

• The procedure takes time. It can take hours to run the export command, plus some additional hours to run InitChain on the fresh chain using the migrated JSON.
• The exported JSON file can be heavy (~100MB-1GB), making it difficult to view, edit and transfer, which in turn introduces additional work to solve these problems (such as streaming genesis).

​

Decision

​

Module ConsensusVersion

type AppModule interface {
    // --snip--
    ConsensusVersion()

uint64
}

​

Module-Specific Migration Functions

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.
})
    // etc.
}

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

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

Migrate1to2(ctx sdk.Context)

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

​

Tracking Module Versions in x/upgrade

0x2 | {bytes(module_name)} => BigEndian(module_consensus_version)

- type UpgradeHandler func(ctx sdk.Context, plan Plan)
+ type UpgradeHandler func(ctx sdk.Context, plan Plan, versionMap VersionMap) (VersionMap, error)

func (k UpgradeKeeper) ApplyUpgrade(ctx sdk.Context, plan types.Plan) {
    // --snip--
-   handler(ctx, plan)
+   updatedVM, err := handler(ctx, plan, k.GetModuleVersionMap(ctx)) // k.GetModuleVersionMap() fetches the VersionMap stored in state.
+   if err != nil {
+       return err
+   }
+
+   // Set the updated consensus versions to state
+   k.SetModuleVersionMap(ctx, updatedVM)
}

​

Running Migrations

• Get the old ConsensusVersion of the module from its VersionMap argument (let’s call it M).
• Fetch the new ConsensusVersion of the module from the ConsensusVersion() method on AppModule (call it N).
• If N>M, run all registered migrations for the module sequentially M -> M+1 -> M+2... until N.
  • There is a special case where there is no ConsensusVersion for the module, as this means that the module has been newly added during the upgrade. In this case, no migration function is run, and the module’s current ConsensusVersion is saved to x/upgrade’s store.

app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgradetypes.Plan, vm module.VersionMap)  (module.VersionMap, error) {
    return app.mm.RunMigrations(ctx, vm)
})

• the old binary will halt in BeginBlock when starting block N. In its store, the ConsensusVersions of the old binary’s modules are stored.
• the new binary will start at block N. The UpgradeHandler is set in the new binary, so will run at BeginBlock of the new binary. Inside x/upgrade’s ApplyUpgrade, the VersionMap will be retrieved from the (old binary’s) store, and passed into the RunMigrations functon, migrating all module stores in-place before the modules’ own BeginBlocks.

​

Consequences

​

Backwards Compatibility

​

Positive

• Perform chain upgrades without manipulating JSON files.
• While no benchmark has been made yet, it is probable that in-place store migrations will take less time than JSON migrations. The main reason supporting this claim is that both the simd export command on the old binary and the InitChain function on the new binary will be skipped.

​

Negative

• Module developers MUST correctly track consensus-breaking changes in their modules. If a consensus-breaking change is introduced in a module without its corresponding ConsensusVersion() bump, then the RunMigrations function won’t detect the migration, and the chain upgrade might be unsuccessful. Documentation should clearly reflect this.

​

Neutral

• The Cosmos SDK will continue to support JSON migrations via the existing simd export and simd genesis migrate commands.
• The current ADR does not allow creating, renaming or deleting stores, only modifying existing store keys and values. The Cosmos SDK already has the StoreLoader for those operations.

​

Further Discussions

​

References

• Initial discussion: Link
• Implementation of ConsensusVersion and RunMigrations: Link
• Issue discussing x/upgrade design: Link