Temporal database schema upgrades: when they run and why they set the pace
Schema upgrades run before server upgrades whenever the release notes for the target version call for them, and you move one minor version at a time. The order matters because each server version expects a persistence and visibility schema that matches it, so a new server pointed at an old schema can fail to start or behave unpredictably. For a self-hosted cluster, the schema work often decides the calendar. It changes the database that holds all workflow state, it has to run against every store the cluster uses, and it repeats for each minor step on the path. For every step, confirm whether the release notes list a schema change, because some steps may not have one.
Temporal provides three schema tools, and the one you run depends on the store behind each role. temporal-sql-tool applies schema changes to SQL persistence and SQL visibility stores, which Temporal documents for MySQL and PostgreSQL, with SQLite meant only for development and testing. temporal-cassandra-tool handles Cassandra persistence. temporal-elasticsearch-tool manages the index used for advanced visibility, which Temporal documents for Elasticsearch 7 and 8 and for OpenSearch 2 or later from server 1.30.1. Cassandra visibility was removed in 1.24, so temporal-cassandra-tool usually applies to persistence only. A cluster with separate persistence and visibility stores runs more than one tool in a step, and each run needs its own sign-off in the plan.
Temporal Server v1.32.1 was published on GitHub on October 8, 2026. Patch releases v1.31.4 and v1.30.8 followed on October 12, 2026, for the earlier minor lines. Start by identifying your current minor version. The first move is to the latest patch of that minor, and the following steps go to each successive minor. Backward compatibility is guaranteed only between two successive minor versions, so the path is built one link at a time, and the newest patch of your current line is the safe starting point. Check the release notes of each patch as well, since the path you plan should reflect the notes you actually read.
What sets the pace is the number of steps and what each step touches. The server restart is the part that takes the least planning. Ask your team to record the current server minor, the persistence and visibility stores in use, the number of minor versions between current and target, and which of those steps the release notes mark as schema changes. Those four facts decide how many tool runs and staging rehearsals the project needs. Plan the window around the slowest store, and confirm with your database owner that backups and restores have been tested before the first schema run.
What changes across Temporal database schema upgrades and what each change means
This table lists the persistence, visibility and deployment changes that affect Temporal schema upgrades and what each one means for your plan. Check each row against your current databases, search engine, and Helm chart before you choose a target version. The main takeaway is that every change needs confirmation in the release notes for your target version before you schedule the schema steps.
| Change | Impact | Action needed |
|---|---|---|
| Cassandra visibility removed in 1.24 | Cassandra can no longer serve as a visibility store from Server 1.24 onward. | Find any visibility store still on Cassandra and plan a supported store first. Confirm the schema step in the 1.24 release notes. |
| Elasticsearch 7 and 8, OpenSearch 2 or later | Supported for advanced visibility from Server 1.30.1. Temporal recommends it beyond a few workflow executions. | Confirm your search engine version is on the supported list. Check the 1.30.1 visibility schema step in the release notes. |
| MySQL and PostgreSQL visibility | Supported for advanced visibility from Server 1.20, with MySQL 8.0.17 or later and PostgreSQL 12 or later. | Confirm your database versions meet these minimums. Check the visibility schema step for your target release. |
| Persistence testing matrix | Temporal tests persistence on PostgreSQL 13 to 16 and MySQL 5.7 and 8.0.19 or later. | Compare current and target database versions with this matrix. Any version outside it needs a staging rehearsal before production. |
| PostgreSQL 13 and earlier | PostgreSQL does not support version 13 or earlier, so it sits at the low end of the tested range. | Plan a PostgreSQL major upgrade alongside the Temporal upgrade. Confirm your vendor support position for your version. |
| SQLite persistence | SQLite is meant only for development and testing. | Confirm no production or staging path uses SQLite. Move any such environment to a tested database before rehearsing upgrades. |
| Helm chart versions below 0.73.1 | These chart versions do not work with Temporal server images 1.30 and later. | Check chart versions in your deployment pipeline. Upgrade the chart before changing the server image. |
The upgrade path Temporal documents, one minor version at a time
Temporal documents that backward compatibility is guaranteed only between two successive minor versions. A jump across several minors therefore needs intermediate stops, and each stop has to be a version the team can run, verify and roll back from before the next step begins. For schema work, this matters because the persistence and visibility schemas change in step with the server, so skipping a stop can leave the database in a state that the next server version does not expect. Plan the full path before anyone touches a staging database, and treat the path as the first deliverable of the upgrade.
To pick each stop, start from the release list on the Temporal Server GitHub releases page and identify every minor line between your current version and your target. Take one stop per minor line, and on each line move to the latest patch release rather than the first release of that minor. The patch release list is where you confirm which build is current on that line at the time you rehearse, because patches on several lines can be published on the same day. Record the chosen stop list in the change ticket with the exact tag for each stop, so reviewers can check the sequence against the documentation for the target version.
Applying the latest patch of the current minor first matters because the patch carries the fixes for that line, including fixes that affect how the server behaves during the next step. Starting from an older patch means the first stop may contain known defects that are already resolved on the same minor. Before you begin, confirm the current patch on your starting line, run it in staging, and check that the server is healthy. Only then move to the next minor. Keep the same discipline at every stop so that each step starts from a known, tested state.
To find out whether a release calls for a schema upgrade before the server binary or image changes, read the release notes and the upgrade documentation for that exact version, not only the headline notes. Look for explicit instructions to run the persistence or visibility schema tool before the server is replaced. Where the notes call for a schema upgrade, Temporal's guidance is that schema upgrades run before server upgrades. Also check the deployment tooling: Helm chart versions below 0.73.1 do not work with server images 1.30 and later, so the chart version may need to change at the same stop. Confirm the exact stop list and each schema command against the upgrade documentation for the target version before you run anything.
Preparing Temporal database schema upgrades: backups and inventory
Schema upgrades change the stores that hold workflow state, so preparation decides whether a failed step can be reversed. The five items below set the baseline: verified backups, point-in-time recovery, an inventory of the database estate and configuration, and a staging copy to rehearse on before the first schema command runs.
Verified backups of both stores
Back up the persistence store and the visibility store together, since the server reads state from both during and after an upgrade. A backup that has never been restored has not been proven to work. Before the first schema run, confirm the restore procedure with the team that owns each database, record who runs it and how long it takes in your environment, and check that a Temporal Server started against the restored data can read it.
Point-in-time recovery for persistence
Where the database supports it, enable continuous archiving so the persistence store can return to a moment just before a failed schema step. For PostgreSQL, this means a base backup plus archived write-ahead log, and the recovery path must be tested by restoring to a chosen timestamp in a separate environment. Confirm the retention window covers your rehearsal and production schedule, that archive storage sits in infrastructure you control, and which stores support this recovery and which only support full snapshots.
Inventory of the database estate
List every persistence and visibility store with its engine, exact version, host or managed service, high availability layout and backup owner. Persistence is tested on PostgreSQL 13 to 16, Cassandra 3.11, 4.0 and 5.0.4 or later, and MySQL 5.7 and 8.0.19 or later, while SQLite is meant only for development and testing. For visibility, confirm whether you run Elasticsearch 7 or 8, OpenSearch 2 or later, or a SQL store, and flag any engine version nearing end of support.
Namespaces, codecs and access settings
Export every namespace with its retention setting and owning team, along with each custom codec used for payload encryption. Payloads written through a codec must be decrypted by that same codec after the upgrade, so keep the codec configuration under version control. Record the Authorizer and ClaimMapper settings as deployed, and confirm whether the default noopAuthorizer is still in use, since it allows every API request without authentication or access control.
Helm chart and server version record
Record the Helm chart version in use alongside the server image tag and the minor version you are moving from. Chart versions below 0.73.1 do not work with server images 1.30 and later, so a chart that predates that point must be moved first. Upgrades go one minor version at a time, so write down each step in the planned path and keep the chart values file in version control with the rest of the inventory.
How to run each Temporal schema step, verify it and roll back
This sequence runs one Temporal schema upgrade from start to finish, with an explicit check and a named rollback point at each step. It keeps the database schema, the server and the workers in the order the upgrade documentation requires, one minor version at a time. The output is a cluster on the target minor with a verified backup and a written record of each check.
Freeze changes and drain workers
The platform owner announces a change freeze for the Temporal cluster and for the teams that deploy workflows and workers. Workers are drained so that no workflow task is in flight when schema changes begin. Check that deployment pipelines are paused and that the task queue backlog and worker activity show no processing before you continue. Rollback point: none is needed yet, because nothing has changed and the cluster still runs the current minor version.
Take and verify the backup
The database administrator takes a backup of the persistence store and of the visibility store if one is in use, using the database's native tooling. For PostgreSQL, confirm the backup method against the PostgreSQL backup documentation, including whether point-in-time recovery is configured. Verify the backup by restoring it to a separate instance and checking that the Temporal namespaces and schema version match the source. This restored and verified backup is the rollback point for the rest of the sequence.
Rehearse the sequence on staging
Run the identical sequence against a staging copy of production data, using the same server, schema tool and database versions as production. Record the time each step takes and every error, then correct the runbook before production. Check that the staging server starts at the target minor, that workflows started before the upgrade complete, and that a test workflow runs on a newly started worker. Rollback point: restore the staging backup, so the team proves the restore works before it is needed in production.
Run the schema tool for each store
The database administrator runs the schema tool that matches each store, starting with persistence: temporal-sql-tool for SQL stores, temporal-cassandra-tool for Cassandra, and temporal-elasticsearch-tool for an Elasticsearch visibility index. Run the visibility step only when the release notes for the target version call for it. Check the tool output for errors and record the tool version and the exact command used. Rollback point: the verified backup. Confirm in the target version's upgrade documentation whether any schema change can be reversed, and plan on restoring the backup if it cannot.
Verify the schema version
Use the schema tool's status or version check to confirm that the persistence store reports the target schema version, and that the visibility store does too when it was upgraded. Compare the reported versions with the release notes for the target minor. Do not start the server until every store matches. If a version differs or the check returns an error, stop, keep the server on the previous minor, and restore the verified backup if the schema is only partly applied.
Wait for the documented interval
Hold for the wait interval that the target version's upgrade documentation specifies before moving on, so that shards stay consistent. Take the interval from that documentation, not from this page or from a general rule. Check that no operator is changing the schema or the server during the wait and that the database and Elasticsearch endpoints remain reachable. Rollback point: the verified backup, because waiting does not change stored state and restoring the backup remains the fallback.
Start the server at the new minor
The platform engineer deploys the server at the latest patch of the target minor version, using the same deployment method as before, such as Helm, Docker Compose or binaries. Helm chart versions below 0.73.1 do not work with server images 1.30 and later, so confirm the chart version before deploying. Check that every service starts, that the logs show no schema or shard errors, and that the services report healthy. Rollback point: redeploy the previous minor image, and restore the verified backup if the previous server cannot run against the upgraded schema.
Check health and proceed to the next minor
Confirm that health checks pass, that a test client can reach each namespace with the access roles it held before, and that workflows started on the previous minor finish. Check the Web UI and the authorization path as well. Only when every check passes and the team signs off in the runbook does the next minor begin, following the same steps from the latest patch of that line. Rollback point: the previous minor image and the verified backup, kept until the team signs off that this minor is stable.
How to test and roll back when a schema step fails
Schema rollbacks are cheapest when the decision is made before any production step runs. A staging rehearsal should use the same schema tool, the same target Temporal Server version, the same database engine version and a copy of production data with a realistic shape. Time each step, record every warning and error, and write the go or no-go criteria down in advance so a poor rehearsal does not turn into pressure to proceed.
Rollback options at this stage:
- Backup rollback: a verified backup taken immediately before the step lets you return the database to its pre-upgrade state.
- Restore only: record how long a restore takes on your storage and which workflow activity would be lost between the backup and the restore.
- Older server: an older server may not start against a schema that a newer tool already changed, so do not treat a server downgrade as a rollback plan.
- Version order: upgrade one minor version at a time and move to the latest patch of the current minor first.
- Criteria: tool exit status, completion of every step, successful server start and a sample of workflow reads and writes.
Confirm each rollback path against the upgrade documentation for your target version before you approve the rehearsal.
Failures during a schema step are the hardest to reverse because the database may be in a state that no single tool command describes. A tool can stop after some statements have run, a lock wait can hold up a step for longer than the window allows, or the tool can exit with an error that does not say which statement failed. Treat the database as unknown until you have checked what actually changed.
What to do in each case:
- Partial failure: identify the last completed step from the tool output and the database metadata before you rerun anything.
- Lock contention: pause writers if your runbook allows it, and set a limit on how long the step waits for locks so the window does not run out unexpectedly.
- Tool error: capture the full error text and the tool version, then rerun only the steps that the target version's documentation describes as safe to repeat.
- Backup rollback: the cleanest path while the database still reflects the pre-step state that the backup captured.
- Restore only: the required path when the database is in a mixed state and you cannot confirm the position, because starting an older server does not undo partial schema changes.
Confirm which steps are safe to repeat for your target version with the upgrade documentation before the window opens.
A server that starts is not proof that the upgrade is sound. Problems often appear later, when workers reconnect, when shards move between history instances, or when visibility queries run against data written during the new version's first hours. Once new workflows have run on the new schema, the rollback options narrow, because any restore discards the history written after the backup.
Checks and their rollback implications:
- Shard health: confirm that shards report healthy across all history instances before accepting production traffic.
- Workflow history reads: read a sample of recent and long-running workflow histories to confirm they load completely.
- Worker reconnection: confirm that workers reconnect and resume tasks, and restart any worker that keeps a stale endpoint.
- Visibility queries: run representative list queries against the visibility store, because a visibility problem can look like missing workflows.
- Rollback cutoff: decide in advance the point after which a restore from backup is no longer acceptable, and record who makes that call.
Verify each rollback path against the upgrade documentation for your target version, and keep the pre-upgrade backup until every check above passes.
How PostgreSQL upgrades interact with Temporal schema changes
Many self-hosted Temporal clusters store workflow state in PostgreSQL, which means the database platform has its own upgrade track that runs alongside Temporal's schema and server releases. Before planning any change, record the PostgreSQL major version in every environment and check it against both the PostgreSQL versioning policy and the persistence versions Temporal documents. The PostgreSQL project supports version 18 until November 14, 2030, version 17 until November 8, 2029, version 16 until November 9, 2028, version 15 until November 11, 2027, and version 14 until November 12, 2026. Temporal's persistence documentation lists PostgreSQL 13 to 16 as tested, so confirm with Temporal's current documentation whether a newer major version is supported before you move to it.
Minor PostgreSQL releases never change the internal storage format, so they replace executables and require a restart rather than a data conversion. That makes them the low-risk part of the database track, but they still need a window and a rollback path. Major upgrades are different. The PostgreSQL upgrading documentation describes three routes: pg_dumpall with a restore, pg_upgrade, and logical replication. Pg_dumpall suits small databases where a longer outage is acceptable. Pg_upgrade is faster on large databases, and PostgreSQL 18 retains planner statistics across major upgrades and adds parallel jobs and a --swap option. Logical replication works between major versions and the documentation describes downtime of only several seconds at cutover, but it needs careful verification of replicated objects before the switch.
A major database upgrade and a Temporal schema upgrade should not run in the same change window. Each change alters a different part of the system, and combining them makes it hard to tell which change caused a failure. A practical sequence is to complete and verify the PostgreSQL major upgrade first, confirm that Temporal services reconnect and that shard ownership looks healthy, and then schedule the schema upgrade in a separate window. Temporal's upgrade guidance says schema upgrades must run before server upgrades when release notes call for them, so the server upgrade follows last. Each window should have its own go or no-go check, its own rollback point, and a named owner who can stop the change if the metrics or logs look wrong.
If the cluster uses a hot standby, synchronous replication or asynchronous replication, the standby setup needs its own failover tests after every major database change. PostgreSQL does not provide software that detects a primary failure and notifies the standby, so automatic failover depends on external tools that your team selects and configures. Test the whole path: promotion of the standby, the connection endpoint Temporal uses, any connection pooler such as PgBouncer, and how Temporal services recover after the switch. Confirm with Temporal's documentation how its services behave during a database failover and whether any manual step is needed. Record the observed behavior, because the next database upgrade will depend on it.
What makes Temporal schema upgrades take longer
This table lists the factors that most often lengthen a Temporal schema upgrade and explains why each one adds work. Read each row as a question to answer before requesting a quote, because the answers set how many schema steps, test cycles and plugin checks are needed. The main takeaway is that the version gap, the data store versions and the presence of a production-like staging copy often matter more than the raw size of the upgrade.
| Driver | Why it adds effort | What to ask for in a quote |
|---|---|---|
| Number of Temporal versions between current and target | Server upgrades move one minor version at a time, and each step can need its own schema change, release note review and verification. | The number of minor steps, the schema tool and release notes each step requires, and the test cycle planned per step. |
| Persistence backend and version | Cassandra, PostgreSQL and MySQL each have their own schema tool and supported version range, and an older database version may need its own upgrade first. | The backend and version in use, whether the database platform must move, and the schema tool commands for each step. |
| Visibility backend | Elasticsearch, OpenSearch and SQL visibility stores have separate schema tools and version ranges. Cassandra visibility was removed in server 1.24. | The visibility store type and version, whether an index change is included, and the tool and steps used for it. |
| Size of workflow history and visibility data | Large stores lengthen schema changes and index work, make rehearsals slower and make rollback planning more involved. | How data volume was measured, how each schema step was estimated at that volume, and the rollback approach. |
| Custom codecs and Authorizer or ClaimMapper plugins | Custom plugins may need rebuilding and retesting for each target version. Access settings also need checking, because the default noopAuthorizer allows every request. | The plugins in use, where their source and build pipeline live, and the test scope for each target version. |
| Helm chart or deployment method | Docker Compose, Go binaries, Helm and custom Go builds each change how schema jobs run and how server images are replaced. Helm chart versions below 0.73.1 do not work with server images 1.30 and later. | The deployment method, chart version, whether schema jobs are automated, and the pipeline changes the quote covers. |
| Number of namespaces and environments | Each environment and namespace needs its own checks, and environments that have drifted apart need separate verification steps. | The count of environments and namespaces, and whether each one gets its own rehearsal and sign-off. |
| Staging environment with production-like data | Without a staging copy of similar size and configuration, production behavior is harder to predict and rehearsal findings carry less weight. | Whether staging exists, how data is refreshed, and the sizing and data handling the quote assumes. |
Questions buyers ask before they hire help with Temporal schema upgrades
What drives the cost of a Temporal database schema upgrade?
The cost follows the number of schema versions between your current release and the target, the persistence and visibility stores involved, and how much rehearsal and evidence work the scope includes. Temporal release notes can call for schema steps in more than one minor release, so a jump across several minors means repeating the same checks for each step. Cost also rises with the number of clusters, namespaces and environments that must be upgraded in order, and with the database engine, since the persistence tools differ for PostgreSQL, MySQL and Cassandra. Visibility on Elasticsearch, OpenSearch or SQL adds another store to upgrade.
One-time costs cover planning, staging rehearsal, runbook writing and the production change window. Recurring costs appear only if you retain a partner for later minor releases. Ask any quote to list each store, each environment and each version step separately.
How long does a Temporal database schema upgrade take?
No duration applies to every upgrade. Elapsed time is set by how many schema versions you cross, how large the persistence and visibility stores are, how long a staging rehearsal takes on a copy of production data, and how many approved change windows you have. The Temporal upgrade documentation sets the order of steps and the requirement to run schema upgrades before server upgrades when release notes call for them. The wait between steps keeps shards consistent, so count it into the calendar.
To get a figure for your environment, run the schema tool against a staging copy, record the elapsed time for each step, and ask any partner to base the schedule on those measurements and the target release notes. Treat any timeline that does not come from those measurements as an estimate to challenge.
What does the client team need to provide for a Temporal schema upgrade?
Plan for four groups of input: access, change windows, named owners and staging. Access means accounts that can run temporal-sql-tool, temporal-cassandra-tool or temporal-elasticsearch-tool against the persistence and visibility stores, plus read access to Temporal service and host logs. Change windows must be approved for each step, and the release notes for each version show whether any step needs services stopped or workers idle.
Backup owners must confirm a tested backup of each store before the first step and hold authority to restore it. Staging should match production in server version, schema version, topology and data volume closely enough that the rehearsal means something. Confirm each item in writing before the schedule is set.
Can an internal team upgrade Temporal schemas without outside help?
Yes, an internal team can do it if it has database administration skills for the chosen store, someone who reads Temporal release notes carefully, and time to rehearse in staging. The steps are documented, and an external engineer would run the same tools. The risk sits in the gaps: a missed version step, a skipped staging run, or an order that moves the server ahead of the schema.
Teams that have not run these tools before benefit from a second reviewer on the runbook and a dry run with recorded timings. Ask whether the people who will hold the pager during the change window have run the steps before. If they have not, an outside rehearsal or a fixed-scope engagement can close that gap without handing over day-to-day operations.
What does a fixed-scope quote for a Temporal schema upgrade include?
A fixed-scope quote lists the work, the deliverables and the timeline in writing before anything starts. For this topic, the scope should name the Temporal Server versions and the persistence and visibility stores in each environment, the version-by-version upgrade plan, the staging rehearsal and its recorded results, the production runbook with rollback notes, and the change-window support agreed in advance.
It should also state what the client provides and what is excluded, such as application code changes or work on the underlying database platform. DeployOpen does not publish a price list, so the quote follows from that written scope. Compare quotes line by line against the same list of versions, environments and deliverables.
Does Temporal Cloud remove the need for schema upgrades?
Temporal Cloud removes the self-hosted persistence and visibility upgrade work from your team, because Temporal Technologies operates the managed service. You still own your workflow code, worker deployment, workflow versioning and how your applications connect to the service. Pay-as-you-go pricing starts at 50 US dollars per million actions, with storage charged per GB-hour, according to the Temporal pricing page, which also lists support tiers and SLA options.
Confirm current terms with Temporal before deciding, since the choice affects data residency, identity integration and your own change control. If the data must stay in infrastructure you control, self-hosting remains the option that carries this upgrade work.
What happens if a Temporal schema upgrade step fails in production?
The step stops, the team follows the rollback path in the runbook, and nobody moves to the next version until the failure is understood. Before the first change, the backup owner should have a restore that was tested in staging, so recovery returns the store to a known state. Record the exact tool command, its output and the state of each store at the point of failure.
Do not rerun a schema step against a store whose state is unclear. Ask any partner how failures are escalated, who makes the rollback decision, and which vendor documents or support channels the team will use. Whether a given step can be rolled back depends on the release notes and the store, so confirm that before the window opens.
How DeployOpen scopes, delivers and supports a Temporal schema upgrade
DeployOpen plans and runs Temporal database schema upgrades inside infrastructure you control, starting from the schema versions your cluster runs today. Each engagement is fixed-scope, with the written scope fixing which persistence and visibility stores, tools and target versions are covered. Ongoing support and upgrade work can be added as a retainer.
How we scope
- The written scope names each persistence and visibility store, its current schema version and the target Temporal Server version.
- It lists which tool applies to each store: temporal-sql-tool, temporal-cassandra-tool or temporal-elasticsearch-tool.
- Scope records the path one minor version at a time, since compatibility is guaranteed only between successive minors.
How we build
- Build a staging environment that matches production topology, then rehearse each schema step and the server upgrade in order.
- Run schema upgrades before server upgrades where release notes call for it, and confirm the schema version after each step.
- Keep the wait between steps that DeployOpen plans so shards stay consistent, and record it in the runbook.
How we hand over
- Deliverables include the executed runbook, rollback notes, staging rehearsal results and the version record for each store.
- Walk your operators through each command, its expected output and the checks that confirm shards are healthy.
- Helm users get chart compatibility notes, since charts below 0.73.1 do not work with server images 1.30 and later.
How we support
- Ongoing support, upgrade planning and continuous testing are available as a retainer, scoped separately from the build.
- Future Temporal Server minor upgrades can reuse the staging rehearsal approach and runbook structure.
- Ask for a quote built from the written scope; DeployOpen does not publish a price list.
