Upgrading

How to upgrade the knowledge graph system to new versions.

Update vs Upgrade

Following the familiar Linux package manager pattern:

Command	What it does	Restarts?
`./operator.sh update`	Pull latest images	No
`./operator.sh upgrade`	Pull, migrate, restart	Yes

Check for updates first:

./operator.sh update          # Pull all images
./operator.sh update api      # Pull specific service only
./operator.sh update operator # Update operator (scripts/migrations)

Then apply them:

./operator.sh upgrade

Quick Upgrade

./operator.sh upgrade

This command: 1. Pulls latest images (if using GHCR) 2. Backs up the database 3. Stops application containers 4. Runs database migrations 5. Starts containers with new images 6. Verifies health

Upgrade Options

# See what would change without doing it
./operator.sh upgrade --dry-run

# Skip backup (faster, but risky)
./operator.sh upgrade --no-backup

# Upgrade to specific version
./operator.sh upgrade --version 0.5.0

Before Upgrading

Check the changelog for breaking changes
Backup your data:
```
./operator.sh backup
```
Note your current version:
```
cat VERSION
```

After Upgrading

Verify health:
```
./operator.sh status
```
Check logs for errors:
```
./operator.sh logs api
```
Test core functionality:
```
kg health
kg search "test"
```

Rolling Back

If something goes wrong:

Stop containers:
```
./operator.sh stop
```

Restore database:

./operator.sh restore /path/to/backup.sql

Use previous image version: Edit compose file to pin previous version tag, then:
```
./operator.sh start
```

Version Pinning

By default, GHCR deployments use :latest. To pin a specific version:

Edit docker-compose.prod.yml:

api:
  image: ghcr.io/aaronsb/knowledge-graph-system/kg-api:0.5.0

Migration Notes

Database migrations run automatically during upgrade. If a migration fails:

Check logs:
```
./operator.sh logs operator
```

Run manually:

./operator.sh shell
python -m api.database.migrate

If stuck, restore from backup and report the issue.