Documentation versioning은 2.0.1부터 시작합니다. 사이트에는 2.0.1 이전 버전의 upgrade matrix를 의도적으로 제공하지 않습니다. 이 페이지는 2.0.1 baseline을 떠날 때의 운영 체크리스트이며 destination-specific breaking change는 해당 이후 버전 문서가 기준입니다.
실행 버전을 바꾸기 전에
- 현재 배포 기록
정확한 hs-sql-agent version, container/package version, topology, Admin database provider, shared-state provider를 기록합니다.
- 제어 평면 상태 백업
새 binary가 persistent state를 변경하기 전에 복구 가능한 Admin database backup을 만듭니다.
- 보호 key material 유지
HMAC_KEY, JWT_KEY, webhook secret, durable DATA_PROTECTION_KEY_PATH material을 업그레이드된 deployment에서도 사용할 수 있게 보존합니다.
- 설정 diff 확인
새 sample을 운영 값 위에 덮어쓰지 말고 destination release의 example/options를 현재 2.0.1 설정과 비교합니다.
- Integration inventory 작성
MCP client, Custom Tool, OIDC, SMTP, webhook/SIEM, Prometheus/OTLP, Redis/shared-state, reverse proxy, 외부 Admin API consumer를 목록화합니다.
가볍게 재생성하면 안 되는 상태
HMAC 및 JWT secret
HMAC_KEY는 MCP-key verification을 보호하고 JWT_KEY는 Admin authentication token을 서명합니다. Secret rotation은 새 image 배포의 부수 효과가 아니라 명시적인 security migration으로 다뤄야 합니다.
Data-protection key ring
보호된 identity/MFA state가 ASP.NET Core data protection을 사용한다면 DATA_PROTECTION_KEY_PATH를 durable storage에 유지하십시오. Key ring을 교체하면 이전에 보호된 값을 읽을 수 없게 될 수 있습니다.
Admin database
Admin database에는 identity/role, database registration, MCP key record, policy, semantic metadata, Custom Tool definition/revision, audit data 및 기타 운영 상태가 저장됩니다. Persistence를 바꿀 수 있는 upgrade 전에 SQLite 또는 PostgreSQL에 맞는 방식으로 백업하십시오.
설정 diff 체크리스트
빈 새 .env에서 다시 시작하지 말고 다음 category를 명시적으로 비교하십시오.
- application host 및 public MCP endpoint
- Admin database provider/connection
- HMAC/JWT 및 identity 설정
- bootstrap configuration
- 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은 설정 레퍼런스를 참고하십시오.
업그레이드 후 검증
- Admin authentication
로그인하고 expected role/permission을 확인하며 OIDC/MFA가 켜져 있다면 함께 검증합니다.
- 데이터베이스 연결
사용 중인 각 provider에서 managed connection과 schema metadata browsing을 확인합니다.
- MCP key scope
대표 key가 예상 database, tool, table whitelist, effective limit를 계속 해석하는지 확인합니다.
- Read-only SQL
대표적인 지원 Query 형태를 실행해 compiler/output behavior를 확인합니다.
- Safe DML
비운영 target에서 Decline과 Accept Elicitation을 모두 테스트하고 commit-time behavior를 확인합니다.
- Operations
audit, health, key usage, telemetry export, outbound-delivery state를 확인합니다.
Custom Tools와 semantic metadata
게시된 Custom Tool마다 destination compiler/policy 아래에서 계속 validate되는지, 의도한 database/key exposure가 유지되는지 확인하십시오. Semantic metadata는 table/column description, relationship, metric이 schema discovery에 예상대로 나타나는지 검증해야 합니다.
API consumer
2.0.1 Admin controller는 versioned /v1 contract 아래에 있지 않습니다. 외부 automation이 Admin HTTP route를 직접 호출한다면 route/request/response compatibility를 명시적인 upgrade test로 다루십시오.
자세한 내용은 Admin HTTP API 레퍼런스를 참고하십시오.
Rollback 계획
안전한 rollout은 새 버전이 기능 및 운영 smoke test를 통과할 때까지 이전 deployment artifact/configuration, pre-upgrade Admin database backup, 보호 key material을 유지합니다.