Upgrade Safety

[abishekve]

Title

v1.1 Upgrade Safety Automation: pre-upgrade backup, auto-rollback on failed health check, in-app update notifications, and audit logging[1]

Background

ThingConnect Pulse currently applies EF Core database migrations on service startup while the installer only manages stop/replace/start of the Windows service without touching data, which means upgrades proceed but lack automatic pre-upgrade backups and orchestrated rollback on failed post-upgrade health checks.[2][3]
Data and configuration live under ProgramData with a stable layout, enabling a reliable pre-upgrade snapshot that can be restored if validation fails after service start.[4]

Objective

Deliver automated pre-upgrade backups, post-upgrade health validation with automatic rollback on failure, in-app update notifications, and structured audit logging of all upgrade and rollback actions for v1.1.[1]

Scope

• Implement a pre-upgrade backup that archives ProgramData (config, versions, logs, and SQLite database) before replacing binaries, using the documented directory conventions.[5][4]
• Run post-upgrade validation: service start, schema verification, and health check against GET api/status/live; if validation fails, restore the last backup and restart service.[6][2]
• Surface in-app update notifications with direct download link as documented in the update management plan.[1]
• Capture a complete audit trail for backup, upgrade, validation, and rollback steps, with durable logs and event entries.[1]

Out of scope

• Centralized multi-site rollout controls and staged deployments are deferred to later milestones.[1]
• Rolling upgrades and silent auto-approval are reserved for future versions.[1]

Implementation plan

• Installer/Ops
  • Add a pre-install backup step in the Inno Setup flow (CurStepChanged/BeforeInstall or [Run]) to zip C:\ProgramData\ThingConnect.Pulse before copying binaries.[3][4]
  • After installation, start the service, run schema verification, and call GET api/status/live; on failure, execute a rollback script to restore the archived snapshot and restart the service.[2][6]
• Backend
  • Provide a lightweight schema check command and ensure clear fatal logging if migrations fail, retaining EF Core’s idempotent apply-on-start behavior.[2]
  • Add structured logging for upgrade and rollback actions with versionFrom/versionTo, backup path, and outcomes.[1]
• Frontend
  • Implement in-app update notifications per the update strategy, linking to the release download.[1]

Tasks

• Pre-upgrade backup
  • Implement PowerShell helper invoked by the installer to archive ProgramData\ThingConnect.Pulse (config, versions, logs, data\pulse.db) into versions<timestamp>.zip.[3][4]
  • Wire the helper into setup.iss to run before file replacement and service start.[3]
• Post-upgrade validation and rollback
  • Start service, run schema check, and call GET api/status/live to validate health.[6][2]
  • On failure, stop service, restore the last backup archive, and restart service; log all steps.[4][1]
• In-app update notifications
  • Add notification UI per update plan with a direct link to the latest release.[1]
• Audit logging
  • Emit structured JSON lines for backup, upgrade, health-check result, rollback, and final status, and write entries to the Windows Event Log.[1]

Acceptance criteria

• A timestamped archive is created automatically before every upgrade containing config, version history, logs, and SQLite database files.[4]
• If schema verification or api/status/live fails after upgrade, the system restores from the latest backup and restarts, returning the service to a healthy state.[6][2]
• In-app update notifications appear when a newer version is available, with a direct download link.[1]
• All upgrade and rollback operations are durably logged with clear timestamps, versions, and outcomes.[1]

Affected files

• Installer/Ops
  • setup.iss (invoke backup, post-install validation, and rollback on failure).[3]
  • New PowerShell backup/restore helpers referenced by the installer flow.[5]
• Backend
  • Maintain EF Core apply-on-start and add a schema check and improved error logging during startup.[2]
• Frontend
  • thingconnect.pulse.client: UI to show available update notification per update plan.[1]

Risks and mitigations

• Risk: Backup increases install time on large datasets.[1]
  • Mitigation: Compression with retention policy, and progress indication in logs or UI.[1]
• Risk: Rollback fails due to partial archive or disk issues.[4]
  • Mitigation: Verify archive integrity before upgrade and check free disk space thresholds.[5]

Test plan

• Automated tests to simulate upgrade with successful health checks and verify no rollback occurs.[1]
• Automated tests to simulate upgrade with forced schema or health failure and verify automatic rollback restores prior state.[2]
• Manual validation on Windows: confirm backup archive creation, post-install validation behavior, and restoration workflow including service health after rollback.[5]

Rollout

• Ship in v1.1 with release notes explaining automatic backup and rollback behavior and how to access archives for support.[1]
• Keep EF Core migrations on startup to remain idempotent and simple for operators while moving safety orchestration into the installer plus helper scripts.[3][2]