Migration and Upgrade Reference

This section describes how to move existing AgentWatch deployments between versions, between database backends, and across major release boundaries.

48.1 Versioning Policy

AgentWatch uses semantic versioning at the major.minor.patch level:

Bump	Triggers	Compatibility
Patch (2.0.43 → 2.0.105)	Bug fixes, small features, schema additions backfilled at boot	Drop-in rolling upgrade, zero downtime
Minor (2.0.x → 2.1.x)	New features, additive schema changes, default-on toggles	Drop-in within one minor; read the release notes for new env vars
Major (2.x → 3.x)	Breaking schema or API changes	Requires the version-skip matrix below

Forward compatibility window: AgentWatch supports rolling upgrades across one minor version at a time. Skipping multiple minor versions in a single jump is not tested and not supported — upgrade through the sequence (2.0.x → 2.1.x → 2.2.x, not 2.0.x → 2.2.x).

48.2 Standard Rolling Upgrade (Within 2.0.x)

For any 2.0.x → 2.0.y where y > x (e.g., 2.0.20 → 2.0.105):

Step	Action
1. Backup	Create a .agwbak archive via POST /api/admin/backup (§31) or take a database snapshot.
2. Drain a node	Behind HAProxy/ALB/NLB, mark one app replica as drain so existing in-flight requests complete (~5–15s for typical SSE streams).
3. Upgrade image	Pull the new container image: docker pull iterateai/agentwatch:2.0.105 (or helm upgrade agentwatch ./helm/agentwatch --set image.tag=2.0.105).
4. Restart node	New container starts, runs schema-sync at boot (handles SQLite ALTER backfills automatically; Postgres Prisma migrations run forward-only).
5. Verify health	GET /health returns 200; GET /metrics shows expected counters.
6. Return to pool	Re-add the node to the LB.
7. Roll the rest	Repeat for each replica.
8. Post-upgrade verify	Run the Postman smoke collection (AgentWatch_Test_Collection.postman_collection.json).

Downtime: zero for multi-instance deployments. ~15 seconds for single-instance (the SIGTERM → 15s grace shutdown window in §39).

Postgres migrations are backward-compatible across one minor version — old replicas can talk to the migrated schema during the rollout. SQLite uses schema-sync (src/enhanced/database/schema-sync.ts) which adds missing columns/tables idempotently at boot.

48.3 Version-Skip Matrix: 2.0.20 → 2.0.105

This is the matrix for partners or customers who’ve been on an older snapshot and want to know what’s in front of them.

Layer	What changes between 2.0.20 and 2.0.105	Action required
Database schema	5 new tables (LdapProvider, LdapOrgRoutingRule, SsoGroupMapping, ScimConfig, ScimToken) + new columns on OAuth2Provider, Users, etc.	None — schema-sync handles SQLite; Prisma migrate deploy handles Postgres.
Authentication	Native SAML 2.0, LDAP, SCIM-per-org, unified group-to-team mapping all added. OAuth2/OIDC unchanged for existing setups.	Existing OIDC providers keep working. Re-test your SSO flow post-upgrade; if you adopt LDAP/SAML, configure via the Unified Auth Wizard (§16.2).
API key format	Unified to ak_… prefix as the sole user-key format. Pre-existing keys keep working; new provisions and rotations use ak_….	None for existing keys. Audit any hardcoded sk_user_ prefix expectations in client code.
Default plan limits	maxApiCallsPerMonth=0 now means unlimited (was incorrectly treated as “zero calls allowed” in 2.0.20).	If you were relying on the buggy behavior to block all calls, switch to enabled=false or a real numeric cap.
Endpoint agent (Connect)	v1.0.66 → v1.0.77. New egress tunnel, curl-impersonate-chrome bundled, CRL Distribution Point, AV-blocked tray banner, Windows NSSM reliability fixes.	Re-distribute the v1.0.77+ installer to endpoints. Older clients keep working with reduced web-chat coverage.
Runtime	Bun 1.1 → Bun 1.3.14. bcryptjs replaces native bcrypt (Bun 1.3 + Node 24 ABI compatibility).	None — runtime is bundled in the Docker image. If you self-compile, follow the new build script.
Default proxy listener	https.createServer → Bun.serve (HTTP/1.1 + HTTP/3).	None. Set AGENTWATCH_PROXY_BUNSERVE=0 to opt back into HTTP/1.1-only if a regression hits.
Anthropic / OpenAI models	41 new model definitions across Claude 4.x family, GPT-5 family, o1/o3 series, Gemini 2.x/3.x.	None — auto-populated. Existing model configs still work.
HTTP/3 hardening	Alt-Svc + Alternate-Protocol stripped from upstream responses (Section 30.3).	None. Browser clients that were relying on HTTP/3 to bypass the MITM will now stay on TCP.
DLP fullName pattern	Tuned to no longer false-positive on factual queries (“what is the name of X”).	None — pure quality fix.
Chat history UI	Renders clean text (no raw JSON, no truncation surprises).	None — pure UX fix.
SQLite drift backfills	All schema drift across the version range is auto-healed at boot.	None — the upgrade just works on SQLite.
URL routing (2.0.64+)	Bare-slug scheme — auth APIs at root /api/auth/*, tenants at /<slug>/…, /platform/* for super-admin. Legacy /o/<slug>/ paths 301/410-redirect.	If you have bookmarks, reverse-proxy rules, or scripts hardcoding /o/<slug>/… or old auth paths, update them to the bare-slug scheme.
Sub-path deployment (2.0.64+)	BASE_PATH now routes chat/gateway/MCP/SSE/WebSocket/UI through a sub-path; Helm chart wires it into the container env + health probes.	None by default (BASE_PATH empty = root). To serve under a sub-path, set BASE_PATH and the matching ingress path (§42.11).
A2A protocol (2.0.64+)	Core A2A shipped — registry, agent-card discovery, JSON-RPC dispatch, X-A2A-Key + JWT auth. New A2AAgent / A2AMessage tables.	None — additive. Schema-sync/Prisma handle the new tables.
DLP redaction (2.0.64+)	False-positive tuning + tool-level redaction fix (resolves benign-prompt 403s); riskScore recorded on redacted requests.	None — quality fix. Re-test any custom thresholds you tuned to work around the old over-blocking.
User provisioning (2.0.64+)	Every user-creation path ensures a Tenant + api_key; platform models stamped with the platform org id (no hardcoded shared org).	None — additive correctness fix.
Protobuf (2.0.64+)	Updated to 7.5.6 (NPM vulnerability).	None — dependency fix.

For more detail: see §42 (“What’s New in 2.0.21–2.0.105”) for the chronological feature log.

48.4 Database Backend Migration (SQLite → PostgreSQL)

When a small-tier deployment outgrows SQLite (typically > 300 users or > 100 RPS sustained), migrate to PostgreSQL 14+.

Step	Action
1. Snapshot	Take a .agwbak backup (full DB + /data/).
2. Stand up Postgres	Managed Postgres 14+ (RDS / Cloud SQL / Azure DB / Supabase). Apply the Prisma schema: npx prisma migrate deploy --schema ./prisma/schema.prisma.
3. Export data	Use dump_db.sh to export each table to CSV/JSON.
4. Import	Use import_db.sh to load CSV/JSON into Postgres in dependency order (organizations → users → teams → tenants → providers → keys → usage → audit).
5. Update DATABASE_URL	Point at the new Postgres instance (postgresql://user:pass@host:5432/agentwatch).
6. Restart	Schema-sync verifies all tables/columns; restart the app.
7. Verify	Run the Postman smoke collection. Spot-check tenant counts, audit row counts, model catalog.
8. Decommission SQLite	Archive the old SQLite file; keep the .agwbak for 30 days.

Reverse direction (Postgres → SQLite) works the same way but is rarely useful — only for shrinking back to an edge deployment.

48.5 Client Agent (AgentWatch Connect) Compatibility Matrix

Server version	Compatible client agent	Notes
2.0.105	v1.0.66 – v1.0.94	v1.0.94 is the recommended pairing (signed installers, Firefox ImportEnterpriseRoots for the AgentWatch CA on macOS + Windows, fixed Linux fail-open on EACCES /etc/hosts, multi-agent-per-API-key fleet record fix). Older clients (< 1.0.73) lack bundled curl-impersonate — falls back to native node:http2 for upstream egress (reduced ChatGPT/Claude.ai coverage).
2.0.44 – 2.0.63	v1.0.66 – v1.0.93	v1.0.93 recommended for this range.
2.0.30 – 2.0.43	v1.0.65 – v1.0.74	LDAP + SCIM features require server ≥ 2.0.40.
2.0.20 – 2.0.29	v1.0.60 – v1.0.66	Egress tunnel introduced in v1.0.71; clients older than that can’t capture chatgpt.com / claude.ai traffic.

Roll-forward policy: server-then-clients. Upgrade the server first; older clients keep talking to the new server until they’re rolled. Reverse (older server, newer client) is not supported — newer clients send headers the older server can’t parse.

48.6 Rollback Procedure

If a rollout shows regressions:

1. Drain the upgraded replicas at the LB.
2. Restore image tag to the previous version: docker pull iterateai/agentwatch:2.0.43 (or helm rollback agentwatch).
3. Postgres: the previous app version can read the migrated schema if you stayed within one minor (forward-compatible by design). SQLite: schema-sync is forward-only — if you can’t simply re-run the older version, restore from the pre-upgrade .agwbak archive.
4. Verify health + smoke test.
5. File a bug report with the version-skip context (AGENTWATCH_VERSION env, Postgres / SQLite indicator, replica count, the specific symptom).

Rollback budget: keep one stable previous image tagged + one pre-upgrade .agwbak for at least 7 days after any production upgrade.

48.7 Pre-Upgrade Checklist

• Current version recorded (visible at GET /health and GET /api/version)
• Target version’s release notes reviewed for new env vars and feature flags
• Backup created (.agwbak archive + Postgres snapshot if applicable)
• Maintenance window scheduled (zero downtime for HA deployments; ~15s for single-instance)
• Rollback image tag confirmed available
• LB drain procedure documented
• Client agent fleet inventory taken (which agent versions are deployed)
• Smoke-test Postman collection ready to run post-upgrade

---