Upgrading and Downgrading Hatchet

This guide covers how to safely upgrade and downgrade self-hosted Hatchet instances, with strategies for production-critical workloads.

Overview

For production-critical deployments, we recommend the following workflow:

1. Snapshot your database before upgrading
2. Upgrade the Hatchet engine to the new version
3. Verify the upgrade is working as expected
4. If something goes wrong, downgrade by restoring the snapshot or running down migrations

Step 1: Take a Database Snapshot

Before any version change, create a point-in-time snapshot of your database. This gives you a fast, reliable rollback path if the upgrade causes issues.

Refer to the backup and restore documentation for your database provider:

• PostgreSQL (self-managed): Backup and Restore
• AWS RDS: Backing Up and Restoring
• Google Cloud SQL: Backup and Recovery
• Azure Database for PostgreSQL: Backup

Step 2: Upgrade Engine Versions

Once your snapshot is in place, upgrade the Hatchet engine.

Docker Compose

Update the image tags in your docker-compose.yml:

services:
  hatchet-engine:
    image: ghcr.io/hatchet-dev/hatchet/hatchet-engine:v0.78.26
    # ... rest of configuration
 
  hatchet-dashboard:
    image: ghcr.io/hatchet-dev/hatchet/hatchet-dashboard:v0.78.26
    # ... rest of configuration

Then redeploy:

docker-compose pull
docker-compose down
docker-compose up -d

Kubernetes (Helm)

The Hatchet Helm charts use a sharedConfig.image.tag value that sets the image tag for all components (engine, API, frontend, migrations). Set this to the target Hatchet version:

# values.yaml
sharedConfig:
  image:
    tag: "v0.78.26"

Then upgrade the release:

# hatchet-stack (standard deployment)
helm upgrade hatchet ./charts/hatchet-stack \
  --namespace hatchet \
  --values values.yaml
 
# hatchet-ha (high-availability deployment)
helm upgrade hatchet ./charts/hatchet-ha \
  --namespace hatchet \
  --values values.yaml

Verification

After upgrading, verify the deployment is healthy:

1. Check that the engine is running and accepting connections
2. Confirm the dashboard loads and shows the correct version
3. Run a test workflow to verify end-to-end functionality
4. Monitor logs for migration errors or unexpected warnings

# Docker Compose
docker-compose logs hatchet-engine | head -50
 
# Kubernetes
kubectl logs -n hatchet -l app=hatchet-engine --tail=50

Step 3: Downgrade if Needed

If the upgrade causes issues, you have two options depending on your situation:

Option A: Restore from Database Snapshot (Recommended for Production)

This is the fastest and safest rollback path. It returns your database to the exact state before the upgrade, avoiding any risk of incomplete down migrations.

# Docker Compose
docker-compose down
 
# Kubernetes
kubectl scale deployment hatchet-engine -n hatchet --replicas=0

Option B: Run Down Migrations (Manual)

If you don’t have a database snapshot or prefer a more targeted rollback, you can run down migrations to revert schema changes. See the Downgrading DB Schema Manually guide for detailed instructions on:

• Finding the target migration version for your desired Hatchet version
• Running hatchet-migrate --down <migration_version>
• Deploying the older engine version