Temporal Upgrade Guide

Safe procedures for upgrading Temporal server, SDKs, and schema versions.

When to Use

• Planning a Temporal server version upgrade
• Checking SDK compatibility for a server upgrade
• Running schema migrations during upgrade
• Rolling back a failed upgrade
• Upgrading from one major version to another

Upgrade Planning

Pre-Upgrade Checklist

1. Review release notes for the target version
2. Check SDK compatibility matrix - ensure your application SDK versions are compatible
3. Identify schema migrations - check if database schema changes are required
4. Test in staging - always upgrade a non-production environment first
5. Plan maintenance window - coordinate with stakeholders
6. Prepare rollback procedure - document how to revert if needed

Version Compatibility

Follow sequential upgrade paths for major versions. Do not skip major versions:

1.21.x -> 1.22.x -> 1.23.x -> 1.24.x

Check SDK compatibility before upgrading:

• Go SDK and Python SDK versions must match the server version range
• Review the compatibility matrix in the Temporal release notes
• Update application dependencies before deploying workers against the new server

Upgrade Process

1. Backup Database

Always backup both the main and visibility databases before upgrading:

pg_dump -h <host> -U temporal temporal > temporal_backup_$(date +%Y%m%d).sql
pg_dump -h <host> -U temporal temporal_visibility > temporal_visibility_backup_$(date +%Y%m%d).sql

2. Scale Down Application Workers

kubectl scale deployment <worker-deployment> --replicas=0 -n <app-namespace>

Wait for workers to drain active tasks before proceeding.

3. Upgrade Temporal Server

helm repo update
helm upgrade temporal temporal/temporal \
  --namespace temporal \
  -f values.yaml \
  --version <target_version>

4. Run Schema Migrations (If Required)

Check release notes for migration requirements. Use the temporal-sql-tool from the admintools pod to apply versioned schema changes.

5. Verify Cluster Health

temporal operator cluster health
temporal operator cluster describe
kubectl get pods -n temporal

6. Update SDK and Deploy Workers

Update your application's SDK dependency to a compatible version, then deploy:

kubectl apply -f worker-deployment.yaml
kubectl rollout status deployment/<worker-deployment> -n <app-namespace>

7. Post-Upgrade Verification

• All Temporal pods running
• Cluster health check passes
• Workers connected and processing tasks
• Test workflow completes successfully
• Monitoring dashboards show normal metrics

Rollback Procedure

If issues occur after upgrading:

1. Rollback Helm release: helm rollback temporal <previous-revision> -n temporal
2. Restore database (if schema changed): restore from backup
3. Redeploy previous workers: kubectl rollout undo deployment/<worker> -n <app-namespace>

Common Upgrade Issues

• Pod startup failures: Check init container logs, verify schema compatibility, review resource limits
• Schema migration errors: Verify database connectivity, check admintools logs
• SDK incompatibility: Update SDK to a version compatible with the new server, check for deprecated API usage
• Non-determinism after upgrade: New server versions may change default behavior; review workflow replay compatibility

Related

• Use /tl-upgrade command for interactive upgrade planning
• Use the temporal-ops agent for operational guidance during upgrades
• See versioning-guide skill for workflow versioning during SDK updates