Documentation versioning 從 2.0.1 開始，本站刻意不提供更早版本的 upgrade matrix。這頁定義的是「離開 2.0.1 baseline」時的 operational checklist；真正 destination-specific breaking changes 應由後續版本自己的文件說明。
切換 running version 前
- 記錄目前 deployment
保存精確 hs-sql-agent/container/package version、topology、Admin DB provider 與 shared-state providers。
- 備份 control-plane state
在新 binary 有機會改 persistent state 前，先建立可還原的 Admin database backup。
- 保存 protected key material
確保 HMAC_KEY、JWT_KEY、webhook secrets 與 durable DATA_PROTECTION_KEY_PATH material 能被新 deployment 延續使用。
- Diff configuration
拿 target release 的 example/options 跟目前 2.0.1 production config 比對，不要用新 sample 直接蓋掉 production values。
- 盤點 integrations
列出 MCP clients、Custom Tools、OIDC、SMTP、webhooks/SIEM、Prometheus/OTLP、Redis/shared state、reverse proxy 與 external Admin API consumers。
不應隨便重新產生的 state
HMAC / JWT secrets
HMAC_KEY 參與 MCP-key verification，JWT_KEY 用於 Admin authentication token。Secret rotation 應該是明確的 security migration，不應只是部署新 image 時的副作用。
Data-protection key ring
Protected identity/MFA state 使用 ASP.NET Core data protection 時，DATA_PROTECTION_KEY_PATH 必須放 durable storage。若 key ring 被替換，先前 protected values 可能無法再讀取。
Admin database
Admin database 是 control plane，保存 identities/roles、database registrations、MCP key records、policies、semantic metadata、Custom Tool definitions/revisions、audit data 與其他 operational state。任何可能改 persistence 的 upgrade 前，都要依 SQLite/PostgreSQL topology 做正式 backup。
Configuration diff checklist
不要從空白新 .env 重建 production config，逐組比對：
- application host / public MCP endpoint；
- Admin database provider/connection；
- HMAC/JWT / identity；
- bootstrap；
- OIDC/MFA/data protection；
- audit retention / outbound delivery；
- rate limiting / security-policy sync；
- cache / SQL concurrency / Redis-backed coordination；
- Prometheus / OTLP。
2.0.1 baseline 請見 Configuration Reference。
Upgrade 後驗證
- Admin authentication
登入並確認 expected roles/permissions；有啟用時也驗證 OIDC/MFA。
- Database connectivity
對實際使用的 providers 驗證 managed connections 與 schema metadata browsing。
- MCP key scope
確認代表性 keys 仍解析到正確 database、tools、table whitelist 與 effective limits。
- Read-only SQL
跑代表性的 supported query shapes，確認 compiler/output behavior。
- Safe DML
用非 production target 同時測 Decline/Accept Elicitation，確認 commit-time behavior。
- Operations
檢查 audit、health、key usage、telemetry export 與 outbound-delivery state。
Custom Tools / semantic metadata
對每個 published Custom Tool，確認 target compiler/policy 仍能 validate，且 database/key exposure 沒有漂移。Semantic metadata 則確認 table/column descriptions、relationships、metrics 仍能如預期出現在 schema discovery。
API consumers
2.0.1 Admin controllers 沒有放在 versioned /v1 contract 下。外部 automation 若直接呼叫 Admin HTTP routes，route/request/response compatibility 必須列入 upgrade test。
Rollback planning
實際 rollout 應保留舊 deployment artifacts/configuration、pre-upgrade Admin DB backup 與 protected key material，直到新版本完成 functional / operational smoke test。