Die versionierte Dokumentation beginnt bei 2.0.1. Es gibt bewusst keine auf der Site gehostete Upgrade-Matrix für Versionen vor 2.0.1. Diese Seite beschreibt die betriebliche Checkliste zum Verlassen der 2.0.1-Basis; versionsspezifische Breaking Changes gehören in die Dokumentation der jeweiligen Zielversion.
Vor dem Wechsel der laufenden Version
- Aktuelles Deployment erfassen
Exakte hs-sql-agent-Version, Container-/Paketversion, Topologie, Admin-Datenbank-Provider und Shared-State-Provider dokumentieren.
- Control-Plane-Zustand sichern
Ein wiederherstellbares Backup der Admin-Datenbank erstellen, bevor ein neueres Binary persistenten Zustand verändern kann.
- Geschütztes Schlüsselmaterial erhalten
HMAC_KEY, JWT_KEY, Webhook-Secrets und das persistente Material unter DATA_PROTECTION_KEY_PATH für das aktualisierte Deployment verfügbar halten.
- Konfiguration vergleichen
Beispiele/Options der Zielversion mit der aktiven 2.0.1-Konfiguration vergleichen, statt ein neues Sample über Produktionswerte zu kopieren.
- Integrationen inventarisieren
MCP-Clients, Custom Tools, OIDC, SMTP, Webhooks/SIEM, Prometheus/OTLP, Redis/Shared State, Reverse Proxy und externe Admin-API-Nutzer erfassen.
Zustand, der nicht beiläufig neu erzeugt werden darf
HMAC- und JWT-Secrets
HMAC_KEY schützt die Prüfung von MCP-Schlüsseln; JWT_KEY signiert Admin-Authentifizierungstokens. Behandeln Sie Secret-Rotation als geplante Sicherheitsmigration und nicht als Nebeneffekt eines neuen Container-Images.
Data-Protection-Key-Ring
Wenn geschützter Identity-/MFA-Zustand ASP.NET Core Data Protection verwendet, muss DATA_PROTECTION_KEY_PATH auf persistentem Speicher liegen. Ein Austausch des Key Rings kann bereits geschützte Werte unlesbar machen.
Admin-Datenbank
Die Admin-Datenbank trägt die Steuerungsebene: Identitäten/Rollen, Datenbankregistrierungen, MCP-Key-Datensätze, Richtlinien, semantische Metadaten, Custom-Tool-Definitionen/-Revisionen, Audit-Daten und weiteren Betriebszustand. Sichern Sie sie vor einem Upgrade, das Persistenz verändern könnte, mit dem für SQLite oder PostgreSQL passenden Verfahren.
Checkliste für Konfigurationsunterschiede
Starten Sie nicht mit einer leeren neuen .env. Vergleichen Sie die Kategorien ausdrücklich:
- Application Host und öffentlicher MCP-Endpunkt;
- Admin-Datenbank-Provider/-Verbindung;
- HMAC/JWT und Identity-Einstellungen;
- Bootstrap-Konfiguration;
- OIDC/MFA/Data Protection;
- Audit-Aufbewahrung und ausgehende Zustellung;
- Rate Limiting und Security-Policy-Synchronisierung;
- Cache / SQL Concurrency / weitere Redis-basierte Koordination;
- Prometheus und OTLP.
Die 2.0.1-Basis steht in der Konfigurationsreferenz.
Nach dem Upgrade validieren
- Admin-Authentifizierung
Anmelden und erwartete Rollen/Berechtigungen prüfen; bei Aktivierung auch OIDC/MFA bestätigen.
- Datenbankverbindungen
Für jeden verwendeten Provider verwaltete Verbindungen und das Browsen der Schema-Metadaten prüfen.
- MCP-Key-Scope
Repräsentative Schlüssel prüfen: erwartete Datenbank, Tools, Tabellen-Whitelist und effektive Limits müssen unverändert aufgelöst werden.
- Read-only SQL
Repräsentative unterstützte Query-Formen ausführen und Compiler-/Ausgabeverhalten prüfen.
- Safe DML
Mit einem Nicht-Produktionsziel sowohl Decline- als auch Accept-Elicitation testen und Verhalten beim Commit prüfen.
- Betrieb
Audit, Health, Schlüsselnutzung, Telemetrie-Export und Zustand ausgehender Zustellungen prüfen.
Custom Tools und semantische Metadaten
Prüfen Sie jedes veröffentlichte Custom Tool gegen Compiler und Policy der Zielversion und bestätigen Sie, dass die beabsichtigte Datenbank-/Key-Sichtbarkeit weiterhin stimmt. Bei semantischen Metadaten müssen Tabellen-/Spaltenbeschreibungen, Beziehungen und Metriken in der Schema-Ermittlung weiterhin wie erwartet erscheinen.
API-Nutzer
Die Admin-Controller von 2.0.1 liegen nicht unter einem versionierten /v1-Vertrag. Wenn externe Automatisierung Admin-HTTP-Routen direkt aufruft, muss Route-/Request-/Response-Kompatibilität ausdrücklich Teil des Upgrade-Tests sein.
Siehe Admin HTTP API Referenz.
Rollback planen
Ein belastbarer Rollout hält alte Deployment-Artefakte/-Konfiguration, das Admin-Datenbank-Backup von vor dem Upgrade und geschütztes Schlüsselmaterial verfügbar, bis die neue Version funktionale und betriebliche Smoke Tests bestanden hat.