08. Updating an IPM Module (IPM v0.10.4 )

Availability: IPM v0.10.4+

Backwards Compatibility: install/load of a module to newer version than currently installed will be blocked by default if newer version of module has the UpdatePackage element defined in module.xml.

Note: Logging, rollback, and mirroring support will be added in future versions.

IPM v0.10.4+ adds a native, in-place module update flow. This page covers:

• What zpm "update" does
• How to adopt the update framework in your module
• Best practices for writing update steps

What does update do?

zpm "update <module> [<new version>]" resolves the target version, then runs your module’s registered update steps (see Adopt the framework in your module below). If <new version> is omitted, the latest available version in configured repositories is used.

Adopt the framework in your module

1. Declare an update package in module.xml. Add <UpdatePackage> pointing at the package that will contain your update classes (see example below).

2. Create a version class that extends the base. For each major version you’ll update to, add V<major target version> in your update package and extend %IPM.General.Update.VersionBase.

3. Order your steps. Implement ClassMethod GetOrderedMethods() As %Library.DynamicArray returning update method names to run, in order.

Example: module.xml

<UpdatePackage>MyApp.Update</UpdatePackage>

Example: Versioned update class

Class MyApp.Update.V1 Extends %IPM.General.Update.VersionBase
{
    ClassMethod GetOrderedMethods() As %Library.DynamicArray
    {
        // Run in this order
        return ["MigrateData", "RebuildIndexes", "RefreshProduction"];
    }

    /// Idempotent; throw on error (do NOT return %Status)
    ClassMethod MigrateData()
    {
        // ... data migration logic
    }

    ClassMethod RebuildIndexes()
    {
        // ... index rebuild logic
    }

    ClassMethod RefreshProduction()
    {
        // ... production refresh logic
    }
}

Best practices

• Idempotent steps. Reruns shouldn't cause side effects.

• Throw errors, don't return %Status. The framework handles errors centrally.

• Name steps by intent, not order. e.g., MigratePolicyTables, UpdateWebApps.

• Major vs. minor/patch. Put new minor/patch steps in the existing V<major version> class; add V2, V3, ... for new majors.

See also

IPM Manifest (module.xml) – add <UpdatePackage>

CLI commands – update command