docs: PostgreSQL cross-cluster instance migration guide (KB260720001) + pending PG-solutions review fixes#809
Open
SuJinpei wants to merge 9 commits into
Open
docs: PostgreSQL cross-cluster instance migration guide (KB260720001) + pending PG-solutions review fixes#809SuJinpei wants to merge 9 commits into
SuJinpei wants to merge 9 commits into
Conversation
…1526) Precipitate historical internal KB PostgreSQL solutions, modernized to the current acid.zalan.do/v1 postgresql CR and verified live on ACP 4.2/4.3, bilingual (en + zh): - KB260515007 How to Migrate a PostgreSQL Instance to Another Node - KB260515008 How to Deploy CloudBeaver for PostgreSQL Management Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The zh translations are produced by the translation pipeline from the en sources (tracked via sourceSHA); they should not be committed by hand. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- CloudBeaver: retrieve superuser password from the operator-created Secret (postgres.<cluster>.credentials...) instead of a non-existent PGPASSWORD_SUPERUSER env var - node migration: label only the target node to avoid rescheduling onto the source Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…001) Validated end-to-end on operator v4.3.3 across two ACP platforms (NodePort pairing, two-phase switchover, checksum-gated cutover). Includes troubleshooting for the ECO-703 cross-version XCR schema drift and standby-recreate secret cleanup. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Ordered teardown (standby first, then remove clusterReplication from the promoted primary), operator-side cleanup behavior (sys_operator schema drop, xdc_hotstandby slot removal), leftover-object cleanup, and verification. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…slot/xcr svc) Ran the full teardown on the validated v4.3.3 pair: sys_operator schema drop confirmed automatic; PVC retention is config-dependent (deleted with the CR on v4.3.3); the physical xdc_hotstandby slot and the -xcr service linger and need manual removal. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
For topologies with no inter-cluster network where the workstation reaches both API servers: pg_dump piped between two kubectl exec sessions. Validated live (100k rows, exact checksum parity, clean exit); documents the version-matched-binary and spilo-schema-exclusion requirements found during validation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…721001 Workstation-relayed logical migration as its own doc, tested verbatim end-to-end before commit. Testing corrected the restore identity: restore as the CR-defined application user (plus --no-comments), otherwise objects land owned by postgres and the app user cannot query them. Migration guide now links to the standalone doc instead of embedding the procedure. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Verify with exact per-table counts (query_to_xml) instead of the n_live_tup estimate, in both baseline and post-restore steps - Run the relay pipe under pipefail and report per-side PIPESTATUS so a source-side dump failure cannot be masked - Add extension preflight: inventory pg_extension on the source and pre-create missing extensions as postgres on the target; new troubleshooting entry for 'permission denied to create extension' - Scope the ownership guidance to the single-owner operator layout and extend the fallback ALTER note beyond public tables/sequences - Add security notes: password visibility in local process listings, dump-file permissions/retention, TLS transport - List required Kubernetes permissions and Spilo image assumptions in Prerequisites - Reword the 'no version-matching constraints' claim (here and in the companion guide's pointer) to same-or-newer target major, no downgrades Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
1 participant
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
How_to_Migrate_a_PostgreSQL_Instance_Across_Clusters.md(KB260720001) — cross-cluster/cross-platform PostgreSQL instance migration using the operator's hot-standby (XCR) feature with a two-phase switchover and checksum-gated cutover. Companion to KB251000009 (Hot Standby Cluster Configuration Guide).Validation
The migration guide was validated end-to-end on 2026-07-20 with operator v4.3.3 on two separate ACP platforms (NodePort pairing, arm64, PG 16): standby bootstrap from peer, checksum parity, demote-then-promote switchover, reverse replication after cutover.
The troubleshooting section encodes real failures encountered during validation, including the cross-version XCR schema drift (ECO-703) and the standby-recreate secret cleanup trap.
🤖 Generated with Claude Code