Skip to content

docs: clarify operational differences between throttling and postponing cut-over (#1775) - #1767

Open
soepic1 wants to merge 6 commits into
github:masterfrom
soepic1:docs/clarify-postpone-vs-throttle-and-uuid-progress
Open

soepic1 wants to merge 6 commits into
github:masterfrom
soepic1:docs/clarify-postpone-vs-throttle-and-uuid-progress

Conversation

@soepic1

@soepic1 soepic1 commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #1775

Description

This PR improves the operational documentation for large-scale migrations (100M+ rows / multi-hour executions):

  1. Throttling vs. Postponing Cut-Over: Adds a clear comparison table and best-practice operational workflow detailing why --postpone-cut-over-flag-file is preferred over long-term --throttle-additional-flag-file during scheduled maintenance windows (preventing MySQL wait_timeout disconnects while maintaining real-time binlog sync).
  2. UUID / String Primary Key Guidance: Documents progress percentage behavior (e.g., overshoot past 100% and ETA: due) on tables with lexicographical/UUID primary keys and explains how operators can verify boundary progress.

Related Issue

Closes #1775

@soepic1 soepic1 changed the title docs: clarify operational differences between throttling and postponing cut-over (#1766) docs: clarify operational differences between throttling and postponing cut-over (#1775) Sep 22, 2026
@soepic1

soepic1 commented Sep 30, 2026

Copy link
Copy Markdown
Contributor Author

Hi @timvaillancourt,
I've just updated this branch to resolve the conflicts with master.
It looks like the CI workflows are awaiting approval to run. Would it be possible to approve them so the automated checks can complete?
Happy to make any changes based on the results. Thank you!

@soepic1

soepic1 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor Author

Hi @timvaillancourt,

I've investigated the CI test failure. It looks like the copy-retries-exhausted test is failing on MariaDB 10.11.

The error log indicates that the test failed because the gh-ost execution succeeded when it was expected to fail:

ERROR copy-retries-exhausted execution was expected to exit on error but did not.
Since my PR only modifies documentation, this seems like it might be a flaky test.

Is there a way to re-run the failed check? I'm happy to help in any way I can. Thanks!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Operational Case Study: Non-Linear Progress on UUID Tables & Throttle Timeout Behaviors

1 participant