Repository navigation
Align the server upgrade guide with current upgrade guidance - #5738
Merged
Merged
Conversation
Corrects three claims in the upgrade guide against the server-operations upgrade playbook: - Skipping a minor version isn't blocked by unreadable data formats. The server doesn't enforce the path; stepping one minor at a time avoids skipping version-gated startup work, and it's the tested path. - Always run the schema update before rolling out the binary, rather than checking release notes for whether one is needed. One run applies every intermediate schema version. - Replace the fixed 10-minute wait per version with the metrics to watch. Adds the release-notes override, the PostgreSQL v1.30/v1.31 Visibility table rebuild (fixed in v1.30.5, v1.31.1, and v1.31.3 by temporalio/temporal#10371 and #11599), the startup schema check, service order, rollback, and passive-first upgrades with Multi-Cluster Replication, plus a pointer from the Multi-Cluster Replication page.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview links
|
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The upgrade guidance applies zero-value targets to cumulative counters, risking indefinite pauses, and omits topology restrictions needed for passive-first upgrades to preserve the receiver-version rule.
2 open issues
What changed in this PR
Updates the self-hosted Temporal Server upgrade guide to align with current server-operations guidance, building on the upgrade-path clarification in #5716.
Changes:
- Clarifies sequential upgrades, schema-first rollout, and service restart guidance.
- Replaces the fixed wait time with metric checks and adds PostgreSQL rebuild precautions and binary rollback instructions.
- Adds Multi-Cluster Replication upgrade guidance and links it from the replication guide.
| File | Description |
|---|---|
docs/production-deployment/self-hosted-guide/upgrade-server.mdx |
Revises upgrade planning, execution, verification, rollback, and replication guidance. |
docs/production-deployment/self-hosted-guide/multi-cluster-replication.mdx |
Adds an upgrade-order summary and links to the upgrade procedure. |
Review effort: Balanced
Four of the verification metrics are counters, so the near-zero targets apply to their recent rate. Passive-first ordering only holds when one Temporal Service is active for every Global Namespace.
Duncanma
enabled auto-merge (squash)
November 18, 2026 20:18
brianmacdonald-temporal
approved these changes
Nov 18, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

What
Updates Upgrade the Temporal Server to match the server-operations upgrade playbook, which the Server team considers the most current guidance. #5716 already aligned the checklist on the upgrade path (one minor version at a time, latest patch first), and the playbook agrees with that rule. This PR fixes the rest of the page.
Corrections
update-schemarun applies every intermediate version.Added
v1.20.0→v1.20.5→v1.21.6→v1.22.0).executions_visibilityrebuild: use v1.30.5+ and v1.31.3+, plan a maintenance window, and have free space of up to twice the table size.numHistoryShards, and service rollout order.The existing per-database schema commands are unchanged. The Kubernetes and pre-rollout dynamic-config tuning from the playbook are left out for now.
Sources and checks
tsurdilo/temporal-server-operations,playbooks/server-upgrade.md). The docs don't link to it.tsurdilo, could you review for accuracy?common/persistence/schema/version.go, which rejects only a schema older than expected.common/metrics/metric_defs.go. Only three have entries in the service metrics reference, so only those are linked.vale --config .vale-ci.iniis clean, andyarn buildpasses with all new anchors present.Follow-up (not in this PR)
docs/encyclopedia/temporal-service/temporal-server.mdxsays "We aim to publish incremental upgrade guides for each minor and major version." That's a future promise, which the style guide disallows, and it may no longer be planned.Related: #5716. This PR also adds the topic to the Kapa decision log from #5717.