Documentation versioning begins at 2.0.1. There is intentionally no site-hosted pre-2.0.1 upgrade matrix. This page defines the operational checklist for leaving the 2.0.1 baseline; destination-specific breaking changes belong in the documentation for that later version.
Before changing the running version
- Record the current deployment
Capture the exact hs-sql-agent version, container/package version, topology, Admin database provider, and shared-state providers.
- Back up control-plane state
Create a recoverable backup of the Admin database before a newer binary can change persistent state.
- Preserve protected key material
Keep HMAC_KEY, JWT_KEY, webhook secrets, and the durable DATA_PROTECTION_KEY_PATH material available to the upgraded deployment.
- Diff configuration
Compare the destination release's example/options against the active 2.0.1 configuration rather than copying a new sample over production values.
- Inventory integrations
List MCP clients, Custom Tools, OIDC, SMTP, webhooks/SIEM, Prometheus/OTLP, Redis/shared-state, reverse proxy, and external Admin API consumers.
State that must not be casually regenerated
HMAC and JWT secrets
HMAC_KEY protects MCP-key verification and JWT_KEY signs Admin authentication tokens. Treat secret rotation as a deliberate security migration, not as a side effect of deploying a new image.
Data-protection key ring
When protected identity/MFA state uses ASP.NET Core data protection, keep DATA_PROTECTION_KEY_PATH on durable storage. Replacing the key ring can make previously protected values unreadable.
Admin database
The Admin database carries the control plane: identities/roles, database registrations, MCP key records, policies, semantic metadata, Custom Tool definitions/revisions, audit data, and other operational state. Back it up using the procedure appropriate to SQLite or PostgreSQL before an upgrade that may change persistence.
Configuration diff checklist
Do not start from an empty new .env. Compare categories explicitly:
- application host and public MCP endpoint;
- Admin database provider/connection;
- HMAC/JWT and identity settings;
- bootstrap configuration;
- OIDC/MFA/data protection;
- audit retention and outbound delivery;
- rate limiting and security-policy sync;
- cache / SQL concurrency / other Redis-backed coordination;
- Prometheus and OTLP.
See Configuration Reference for the 2.0.1 baseline.
Validate after upgrade
- Admin authentication
Sign in and verify expected roles/permissions; confirm OIDC/MFA if enabled.
- Database connectivity
Verify managed connections and schema metadata browsing for each provider you use.
- MCP key scope
Confirm representative keys still resolve the expected database, tools, table whitelist, and effective limits.
- Read-only SQL
Run representative supported query shapes and confirm compiler/output behavior.
- Safe DML
With a non-production target, test both Decline and Accept Elicitation paths and confirm commit-time behavior.
- Operations
Inspect audit, health, key usage, telemetry export, and outbound-delivery state.
Custom Tools and semantic metadata
For each published Custom Tool, verify it still validates under the destination compiler/policy and that its intended database/key exposure remains correct. For semantic metadata, verify table/column descriptions, relationships, and metrics still appear through schema discovery as expected.
API consumers
The 2.0.1 Admin controllers are not namespaced under a versioned /v1 contract. If external automation calls Admin HTTP routes directly, treat route/request/response compatibility as an explicit upgrade test.
Rollback planning
A useful rollout keeps the old deployment artifacts/configuration, the pre-upgrade Admin database backup, and protected key material available until the new version has passed functional and operational smoke tests.