Sequential Upgrade vs. Fresh DB Cutover (With Planned Downtime)

Community Support Server Deployment
1

Hi Temporal Team,

We are planning to upgrade our self-hosted Temporal cluster from v1.26.2 to v1.31.2. Many of our production apps rely on Temporal for critical workflows. We can plan a maintenance window/downtime for production, but we want the safest and cleanest approach.

We are evaluating two options:

  1. Sequential In-Place Upgrade: Step through each minor version sequentially with DB schema updates at each step.

  2. Fresh DB Cutover: Spin up a brand new cluster + fresh DB directly on the target version, cut traffic over during downtime, and drain/migrate open workflows.

Questions:

  1. Given that we can take planned downtime, which approach is considered best practice for jumping multiple minor versions?

  2. If we do a Fresh DB Cutover, what is the cleanest way to handle open/in-flight workflows without losing execution state?

  3. What are the key risks to watch out for on the SDK / Worker side during this transition?

Environment:

  • Current Version Server: v1.26.2

  • Target Version Server: v1.31.2

  • Database: PostgreSQL

  • Temporal chart version: From 0.55 to 1.6

  • Deployment: Using helm chart with git submodule for temporal chart and specify server and UI version.

Thank you for the help!

2

would go with upgrade process. how long you need to set your maintenance time for upgrade will highly depend on how large your persistence stores are. for sql, currently, upgrade can take a bit of time

look at playbook here and honestly would also read through slack thread here especially if your persistence stores very large