Le versionnement de la documentation commence en 2.0.1. Il n’existe volontairement pas de matrice de migration hébergée sur le site pour les versions antérieures. Cette page définit la liste de contrôle opérationnelle pour quitter la base 2.0.1 ; les changements incompatibles propres à une destination appartiennent à la documentation de cette version ultérieure.
Avant de changer la version en cours d’exécution
- Consigner le déploiement actuel
Notez la version exacte de hs-sql-agent, la version container/package, la topologie, le provider de la base Admin et les providers d’état partagé.
- Sauvegarder le plan de contrôle
Créez une sauvegarde récupérable de la base Admin avant qu’un binaire plus récent puisse modifier l’état persistant.
- Préserver le matériel cryptographique
Conservez HMAC_KEY, JWT_KEY, secrets webhook et le contenu durable de DATA_PROTECTION_KEY_PATH pour le déploiement mis à niveau.
- Comparer la configuration
Comparez les exemples/options de la version cible à la configuration 2.0.1 active au lieu d’écraser les valeurs de production avec un nouvel exemple.
- Inventorier les intégrations
Recensez clients MCP, Custom Tools, OIDC, SMTP, webhooks/SIEM, Prometheus/OTLP, Redis/état partagé, reverse proxy et consommateurs externes de l’Admin API.
État à ne pas régénérer sans intention
Secrets HMAC et JWT
HMAC_KEY protège la vérification des clés MCP et JWT_KEY signe les tokens d’authentification Admin. Traitez leur rotation comme une migration de sécurité volontaire, pas comme un effet secondaire du déploiement d’une nouvelle image.
Trousseau data protection
Lorsque l’état protégé d’identité/MFA utilise ASP.NET Core data protection, conservez DATA_PROTECTION_KEY_PATH sur un stockage durable. Remplacer le trousseau peut rendre illisibles les valeurs déjà protégées.
Base Admin
La base Admin porte le plan de contrôle : identités/rôles, enregistrements de bases, clés MCP, politiques, métadonnées sémantiques, définitions/révisions de Custom Tools, données d’audit et autres états opérationnels. Sauvegardez-la selon la procédure adaptée à SQLite ou PostgreSQL avant toute mise à niveau susceptible de modifier la persistance.
Liste de contrôle de comparaison de configuration
Ne repartez pas d’un nouveau .env vide. Comparez explicitement :
- host applicatif et endpoint MCP public ;
- provider/connexion de la base Admin ;
- HMAC/JWT et paramètres d’identité ;
- configuration bootstrap ;
- OIDC/MFA/data protection ;
- rétention d’audit et livraisons sortantes ;
- limitation de débit et synchronisation de politique ;
- cache / concurrence SQL / autres coordinations via Redis ;
- Prometheus et OTLP.
Consultez Référence de configuration pour la base 2.0.1.
Valider après la mise à niveau
- Authentification Admin
Connectez-vous et vérifiez les rôles/permissions attendus ; vérifiez aussi OIDC/MFA s’ils sont activés.
- Connectivité des bases
Vérifiez les connexions gérées et la navigation dans les métadonnées de schéma pour chaque provider utilisé.
- Périmètre des clés MCP
Confirmez que des clés représentatives résolvent toujours la base, les outils, la liste blanche de tables et les limites effectives attendus.
- SQL en lecture
Exécutez des formes de requêtes prises en charge représentatives et vérifiez le comportement du compilateur et des résultats.
- Safe DML
Sur une cible hors production, testez les parcours Decline et Accept d’Elicitation et vérifiez le comportement au moment du commit.
- Exploitation
Inspectez audit, santé, usage des clés, export de télémétrie et état des livraisons sortantes.
Custom Tools et métadonnées sémantiques
Pour chaque Custom Tool publié, vérifiez qu’il reste valide sous le compiler/policy de destination et que son exposition prévue par base/clé reste correcte. Pour les métadonnées sémantiques, vérifiez que descriptions de tables/colonnes, relations et métriques continuent d’apparaître comme prévu dans la découverte de schéma.
Consommateurs API
Les contrôleurs Admin 2.0.1 ne sont pas placés sous un contrat versionné /v1. Si une automatisation externe appelle directement les routes HTTP Admin, traitez la compatibilité route/request/response comme un test explicite de mise à niveau.
Consultez Référence de l’API HTTP Admin.
Préparer le rollback
Un déploiement prudent conserve les artefacts/configurations précédents, la sauvegarde de la base Admin avant mise à niveau et le matériel cryptographique protégé jusqu’à ce que la nouvelle version ait passé les smoke tests fonctionnels et opérationnels.