docs: guide for zero-downtime PostgreSQL major-version upgrade#37795
Open
tylerhartwig wants to merge 1 commit into
Open
docs: guide for zero-downtime PostgreSQL major-version upgrade#37795tylerhartwig wants to merge 1 commit into
tylerhartwig wants to merge 1 commit into
Conversation
Add a guide covering how to upgrade the major version of the PostgreSQL database behind a Materialize source. Documents two validated approaches: - Parallel source (self-managed): keep the existing source serving fresh while native logical replication feeds a new-version primary and a second source hydrates in parallel, then cut consumers over. Only approach that keeps reads continuously fresh. - Amazon RDS Blue/Green: managed cutover with a bounded freshness gap. Documents that Materialize's replication slot counts as "external replication" (so the source must be dropped before the deployment can be created), and that after an in-place switchover the source can resume from the same slot via ALTER CONNECTION ... SET (HOST = ...) with no re-snapshot. Both approaches and their gotchas (DDL/sequences not replicated, REPLICA IDENTITY FULL, slot-preservation semantics of ALTER CONNECTION) were validated end-to-end against RDS PostgreSQL 15->16. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
djahandarie
reviewed
Jul 22, 2026
Comment on lines
+180
to
+182
| 1. `DROP SOURCE` in Materialize to release the replication slot. Confirm | ||
| `pg_replication_slots` no longer lists Materialize's slot. **The freshness | ||
| gap starts here.** |
Contributor
There was a problem hiding this comment.
Let alone freshness gap, won't this cascade drop all the downstream objects and cause an availability incident?
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
2 participants
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.
Motivation
Users running a Materialize PostgreSQL source periodically need to upgrade the major version of the upstream database (e.g. PG 15 → 16). This is trickier than a normal upgrade because the source holds an active logical replication slot on the primary, and a major-version upgrade replaces that primary. There was no guidance for doing this while keeping Materialize fresh.
What this adds
A new guide, Guide: Upgrade the major version of your PostgreSQL source (
ingest-data/postgres/major-version-upgrade.md), plus a link from the PostgreSQL guides index. It documents two approaches:ALTER CONNECTION ... SET (HOST = ...), because green is promoted in place (same LSN timeline).A considerations section calls out the gotchas: DDL and sequences aren't replicated,
REPLICA IDENTITY FULLis required, andALTER CONNECTIONonly avoids a re-snapshot when the slot is preserved.Validation
Both approaches were validated end-to-end against Amazon RDS PostgreSQL 15 → 16 under continuous insert/update/delete load, with an order-independent fingerprint (and a
SUM(balance)transactional invariant for the self-managed path) confirming byte-consistency across the upstream databases and Materialize sources through cutover.hugobuilds clean; all internal links resolve.🤖 Generated with Claude Code