docs: avoiding backfills during a database failover or host change#3086
Merged
Conversation
…nal cutover Extends the existing 'Preventing backfills during database upgrades' guidance to cover planned failovers, including promoting an Aurora Global Database secondary region. Adds the address-repoint step (the new writer does not carry the old CDC position) and the per-engine specifics: Postgres slots are not replicated to a promoted cluster, MySQL binlog coordinates are per-server and require the writer endpoint. Cross-links the PostgreSQL and MySQL connector pages and the cross-region PrivateLink section (pre-registering a standby region for DR).
Generalize rather than create a parallel failover section: the new-host case (failover, standby promotion, instance migration) is a step variant (4b), not a separate procedure. Rename the heading to '...upgrades and failovers', keep one section, drop the Aurora-specific framing to an example. Update cross-link anchors.
jwhartley
changed the title
Drop the Aurora Global Database examples and the MySQL-specific error detail from the general backfill guide; state the new-host failure reason generically (resume from a CDC position that does not exist on the new server). Make the PrivateLink note about pre-registering any standby/backup endpoint for upgrades, failover, or DR rather than cross-region specifically.
aeluce
approved these changes
Jul 1, 2026
aeluce
left a comment
aeluce
left a comment
Collaborator
There was a problem hiding this comment.
Thanks! I see the PR description notes that the Postgres publication and watermarks table will carry over with the storage volume on failover. I didn't see that specified in the docs; would it be useful to include, or is it extraneous?
Contributor
Author
|
Yeah I trimmed those out as they were adding unnecessary bulk |
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.
What
Documents how to avoid a full backfill when a CDC source moves to a new writer, including failovers, standby promotions, instance migrations, and Amazon Aurora Global Database regional switchovers.
The existing "Preventing backfills during database upgrades" section already covers the pause-writes / "Only Changes" procedure, but it was framed entirely around in-place upgrades (same host). It never mentioned failover or a host change, and had no MySQL specifics. A user searching for failover behavior landed nowhere, even though the procedure is the right answer.
Approach
Rather than add a parallel section, this generalizes the existing one. The new-host case is a step variant, not a separate procedure.
guides/backfilling-data.md: renamed the heading to "Preventing backfills during database upgrades and failovers"; generalized the intro to cover failovers/promotions/migrations (Aurora Global Database as one example); split step 4 into 4a (same host, no extra change) and 4b (new host: also repoint the captureaddress, because the new writer does not carry the old CDC position). Updated the internal anchor reference.reference/Connectors/.../PostgreSQL.mdand.../MySQL.md: short pointers into that section. MySQL had no failover guidance at all.private-byoc/privatelink.md: note in the cross-region section about pre-registering another region's endpoint ahead of a host change, cross-linked back.Why these specifics are correct
ERROR 1236); capture must use the writer endpoint (readers reportlog_bin = OFF).addressalone resumes the stale cursor and fails. Verified against the connector source.Notes
No new page; this extends and cross-links existing content. Prompted by a customer asking for a repeatable regional-failover pattern for an Aurora Global Database.