Upgrades

This document covers how to roll forward (and back) between IdentityMesh releases without losing data or breaking running connectors.

What changes between releases

Pre-upgrade checklist

1. Take a SQL backup. See backup-and-restore.md. This is the only thing that lets you roll back if the upgrade goes sideways.
2. Snapshot the Connectors\ folder on every host (service + each relay) so you can roll a connector DLL back independently of the service version.
3. Note the running version by checking the file properties on %ProgramFiles%\IdentityMesh\*.exe or the Admin UI’s About page.
4. Stop active sync runs. Either pause schedules in the Admin UI or wait for in-progress runs to complete. Any sync running when the service is stopped is marked Interrupted; the next service start reconciles the bookkeeping automatically.

Upgrade procedure

Same-version connector upgrade only

Drop replacement DLLs into the Connectors\ folder and restart the service (or relay agent). Connectors are loaded on startup.

Service / API version upgrade

1. Pre-upgrade checklist above.
2. Stop services:

   sc stop IdentityMeshEngine
   sc stop IdentityMeshAdmin

3. Run the new MSI. It upgrades binaries in-place and preserves appsettings.json — file-copy rules are documented in installer.md.
4. Schema migrations are applied automatically by the installer’s database-setup step. The migration system is idempotent — running it on an already-current database is a no-op.
5. Start services:

   sc start IdentityMeshAdmin
   sc start IdentityMeshEngine

6. Smoke test: dashboard loads, license shows valid, run history queryable, kick off one sync.

Relay agent upgrade

Each relay agent is independently upgradeable. Order:

1. Upgrade the central API/service first (or at least confirm the API is at a version that still accepts the relay’s old protocol — see “Version skew” below).
2. For each relay host: stop the service, install the new MSI, start the service. The agent re-registers with the API on next connection.

Version skew

The relay protocol is conservative — older relays against newer APIs generally work, and newer relays against older APIs generally work, as long as no hub method has been removed or changed in incompatible ways.

For deployments with many relays that can’t be upgraded simultaneously: a staged rollout (one canary relay first) catches incompatibilities cheaply during the upgrade window.

Connector DLL versioning

Connectors are loaded by name from the Connectors\ folder. IM_ConnectorSchedules references each connector by type name.

• Adding a new connector: drop the DLL in Connectors\, restart. The new type registers as soon as the agent re-registers.
• Updating an existing connector: replace the DLL in place; type names must remain stable. Restart picks up the new code.
• Renaming a connector type: do not. It breaks every existing schedule that referenced the old name. If unavoidable, the release notes will call out the SQL migration that updates the affected rows.

Rollback

Binary rollback

1. Stop services.
2. Run the previous version’s MSI:

   msiexec /i previous.msi REINSTALL=ALL REINSTALLMODE=vomus

3. Roll back the schema if the upgrade applied any. The release notes for each version document whether down-migration is supported and what data, if any, is lost in the down direction. Test rollbacks in a staging copy of production data first.
4. Start services.

Schema-only rollback (binary stays at new version)

Don’t. Migrations are designed to be applied in order. A binary that expects a column the schema doesn’t have will throw at runtime. If the new binary version is broken in a way that requires reverting just the schema, the right move is to roll back the binary too.

Data-only rollback (revert to backup)

See backup-and-restore.md.

Upgrade frequency considerations

• Schema migrations are additive whenever possible (new nullable columns, new tables) so the previous binary version still runs against the new schema. This makes rolling deployments and partial rollback safe.
• Avoid renaming columns or tables. Renames mean every customer’s upgrade pays the migration cost; the release process prefers add-and-deprecate over rename.

Related

• installer.md — MSI build and install procedure.
• backup-and-restore.md — what to back up before upgrading.
• secrets-and-dpapi.md — secret re-provisioning if the upgrade involves a host migration.