Should I upgrade to SigNoz Schema Migrator to TelemetryStore Migrator Upgrade Path now?
Plan a safe self-hosted SigNoz upgrade after the migration mechanism changed, affecting rolling upgrade procedure and rollback expectations.
Blockers
- replaces: package/signoz-telemetrystore-migrator → package/signoz-schema-migrator
- breaking_change_in: package/signoz-schema-migrator → package/signoz-v0.113
- package/signoz-schema-migrator incompatible with package/signoz-v0.113
- requires_version: capability/self-hosted-upgrade → package/signoz-v0.86.0
Who this is for
- enterprise
- low-ops
- small-team
Candidates
Use the official v0.113+ path and treat the upgrade as migration-gated, not rolling
As of 2026-04-04, SigNoz v0.113 has already replaced the standalone "signoz-schema-migrator" with "signoz-telemetrystore-migrator". The new flow runs "bootstrap", "sync", and "async" migrations through "signoz-otel-collector", and otel-collector now performs "migrate sync check" at startup. Sync migrations must complete before the application starts, while async migrations are background data migrations. If you use the default Docker Compose files, the v0.113 guide says no manual changes are required beyond the standard upgrade flow.
When to choose
Use this when you run close to the stock self-hosted manifests and want the least-custom upgrade path. The decisive factor is whether you can accept a migration-gated rollout where collectors and app components may stay unready until the migrator finishes successfully.
Tradeoffs
This is the simplest supported path and removes the old Job-ordering problems, but it weakens assumptions behind true rolling upgrades because startup now depends on completed sync migrations.
Cautions
Validate that the migrator completed successfully before expecting otel-collector or SigNoz to become healthy. Official docs say image tags must match between the migrator and otel-collector, and old schema-migrator references must be removed.
For customized Compose or Helm installs, rewrite migration config first and stage through required upgrade stops
As of 2026-04-04, customized deployments need config changes before the version jump: Helm values using "schemaMigrator" must move to "telemetryStoreMigrator", while several old keys are deprecated and must be removed. The v0.113 guide also says the migrator job or container must use the same ClickHouse DSN, cluster, replication settings, and image tag as otel-collector. Separately, the v0.86.0 guide states that v0.86.0 is a mandatory stop for older installs because it includes important SQL migrations. SigNoz's upgrade docs also say skipped required stops can leave the system in an inconsistent state or cause upgrade failure.
When to choose
Use this when you have Helm overrides, HA ClickHouse, external ClickHouse, or older versions that may cross multiple required stops. The decisive factor is whether your deployment has enough customization that a direct manifest swap would likely fail on renamed keys, wrong migration settings, or skipped intermediate versions.
Tradeoffs
This is safer for bespoke environments and older clusters, but it requires more preflight work and a stricter version-by-version sequence.
Cautions
As of 2026-04-04, this migration mechanism change has already occurred. Official docs describe forward migration and validation steps, but they do not publish a downgrade procedure on these pages, so do not assume rollback will be symmetric after sync schema migrations run.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Should I upgrade to SigNoz Schema Migrator to TelemetryStore Migrator Upgrade Path now?"