Upgrade Guide

Procedures for upgrading Shielda components.

---

Version Compatibility

Component Upgrade Path Notes Control Plane Any → latest Database migrations auto-apply Go Agent N-2 → latest Backward-compatible heartbeat MCP Server Any → latest Follows control plane API LSP Server Any → latest Follows control plane API CLI Any → latest Follows control plane API

Control Plane Upgrade

Prerequisites

Database backup exists (automatic via RDS) At least one healthy instance running during rolling deploy New container image built and pushed to ECR

Procedure

2. Update ECS service (rolling deploy) aws ecs update-service --cluster shielda --service control-plane --force-new-deployment

3. Monitor deployment aws ecs describe-services --cluster shielda --services control-plane \ --query 'services[0].deployments'

4. Verify health curl https://app.shielda.dev/api/health

Database Migrations

Migrations run automatically on startup. For manual control:

Apply migrations npx drizzle-kit push

Generate new migration (development) npx drizzle-kit generate

Rollback: restore from backup (no automatic rollback)

Migration Safety

All migrations are additive (add columns/tables, never drop) New columns have DEFAULT values to avoid breaking existing queries Index creation uses CREATE INDEX CONCURRENTLY where possible Large table migrations are split into batches

Go Agent Upgrade

Docker

Restart container docker compose down && docker compose up -d

SystemD

Restart service systemctl restart shielda-agent systemctl status shielda-agent

Kubernetes (Helm)

Verify rollout kubectl rollout status deployment/shielda-agent -n shielda

Version Verification

After upgrade, check agent version in dashboard: Dashboard → Agents → verify "Version" column Or check heartbeat: agent reports version on every heartbeat

MCP Server / LSP Server / CLI

These are NPM packages:

Or update via npx (always uses latest) npx @shielda/cli --version

Breaking Changes

Version Policy

Major (v2.0): Breaking API changes (rare, 6+ months notice) Minor (v1.x): New features, backward-compatible Patch (v1.x.y): Bug fixes, security patches

Migration Guides

When breaking changes occur, a migration guide will be published: docs/migrations/v2-migration.md (example) CHANGELOG.md will note breaking changes prominently

Rollback Procedures

Control Plane

If database migration was applied, restore from pre-upgrade backup aws rds restore-db-instance-to-point-in-time \ --source-db-instance-identifier shielda-prod \ --target-db-instance-identifier shielda-rollback \ --restore-time "<pre-upgrade-timestamp"

Agent

Binary: download specific version curl -L https://github.com/shielda/shielda/releases/download/v1.2.3/shielda-agent-linux-amd64 \ -o /usr/local/bin/shielda-agent systemctl restart shielda-agent