Skip to content

docs: clarify MariaDB DM migration prerequisites - #24668

Open
doc-claw-bot wants to merge 5 commits into
masterfrom
docs/mariadb-dm-doc-sync
Open

doc-claw-bot wants to merge 5 commits into
masterfrom
docs/mariadb-dm-doc-sync

Conversation

@doc-claw-bot

@doc-claw-bot doc-claw-bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

What is changed, added, or deleted? (Required)

  • Clarify the MariaDB-to-TiDB migration guide so it points readers to the version-specific MariaDB privilege requirements in dm-worker-intro instead of listing an incomplete subset inline.
  • Replace the MariaDB precheck workaround in the migration guide and DM compatibility catalog with the narrower replication_privilege, dump_privilege, and conn_number skips documented for DM v8.5.6, and remind readers to verify the corresponding privileges and connection limit manually.
  • Clarify that the linked TiDB Lightning and DM quick-start guides are for test or development environments, and point production users to the relevant production guidance.

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions.

  • master (the latest development version)
  • v9.0 (TiDB 9.0 versions)
  • v8.5 (TiDB 8.5 versions)
  • v8.1 (TiDB 8.1 versions)
  • v7.5 (TiDB 7.5 versions)
  • v7.1 (TiDB 7.1 versions)
  • v6.5 (TiDB 6.5 versions)

What is the related PR or file link(s)?

AI agent involvement

  • The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

  • Delete files
  • Change aliases
  • Need modification after applied to another branch
  • Might cause conflicts after applied to another branch

Summary by CodeRabbit

  • Documentation
    • Updated MariaDB migration guidance with version-specific privilege requirements.
    • For DM v8.5.6, documented a targeted workaround for specified precheck failures: ignore only replication privilege, dump privilege, and connection-number checks, then manually verify the required privileges and connection limit.
    • Clarified that connection-number checks cover upstream dump and downstream load stages, not incremental replication.
    • Added separate guidance for test or trial environments and production migration planning.

@ti-chi-bot ti-chi-bot Bot added the contribution This PR is from a community contributor. label Nov 10, 2026
@doc-claw-bot doc-claw-bot added type/bugfix This PR fixes a bug. area/dm needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. translation/welcome Waits for a contributor to translate this PR and create a PR to the pingcap/docs-cn repository. ONCALL Relates to documentation oncall. labels Nov 10, 2026
@ti-chi-bot ti-chi-bot Bot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Nov 10, 2026
@coderabbitai

coderabbitai Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Explain Change →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

The MariaDB migration guide now links to environment-specific guidance and documents version-specific DM privileges and a conditional DM v8.5.6 precheck workaround. DM documentation clarifies which connections the conn_number check covers.

Changes: MariaDB migration guidance

Layer / File(s) Summary
Environment-specific migration references
migrate-from-mariadb.md
The guide links test or trial users to the Getting Started guide and production deployments to production migration guidance.
DM privileges and precheck workaround
migrate-from-mariadb.md, dm/dm-compatibility-catalog.md, dm/dm-precheck.md
The guidance links to version-specific privilege requirements and documents the DM v8.5.6 workaround for replication_privilege, dump_privilege, and conn_number checks. It directs users to verify privileges and connection limits manually. The precheck table describes the upstream dump-stage and downstream load-stage connections checked by conn_number, excluding incremental-replication connections.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Possibly related PRs

  • pingcap/docs#24361: Changes wording for the MariaDB dump-connection precheck that this update also documents.

Suggested reviewers: alastori

Merge Risk: Low · up to 0a834

The workaround could lead readers to overlook the downstream connection limit. The linked precheck documentation explains both limits, so the remaining risk is bounded.

Pre-merge checks: Passed 5

Check name Status Explanation
Title check Passed The title clearly summarizes the main change: clarifying MariaDB migration prerequisites for DM.
Description check Passed The description covers the required change summary, affected TiDB versions, reference links, AI involvement, and applicable change checkboxes. The first-time contributor checklist is conditional and c…
Docstring Coverage Passed No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Description check

Explanation

The description covers the required change summary, affected TiDB versions, reference links, AI involvement, and applicable change checkboxes. The first-time contributor checklist is conditional and can be omitted when it does not apply.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between b0beec4 and 0a834df.

Files selected for processing: 1

  • dm/dm-precheck.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 1 remain after this review.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 16b9550 and 38d42c9.

Files selected for processing: 2

  • dm/dm-compatibility-catalog.md
  • migrate-from-mariadb.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

Comment thread dm/dm-compatibility-catalog.md Resolved
Comment thread migrate-from-mariadb.md Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Two active documentation inconsistencies remain: both new workarounds reference dm-precheck.md without documenting the conn_number check they instruct users to bypass.

2 open issues
What changed in this PR

Clarifies MariaDB-to-TiDB migration prerequisites and provides version-specific DM v8.5.6 precheck guidance while distinguishing test or development workflows from production deployment guidance.

Changes:

  • Links users to version-specific MariaDB privilege requirements.
  • Narrows the precheck workaround to replication_privilege, dump_privilege, and conn_number, with manual verification guidance.
  • Adds separate guidance for test or trial environments and production migration procedures.
File Description
migrate-from-mariadb.md Updates MariaDB migration prerequisites, DM precheck handling, and test-versus-production guidance.
dm/​dm-compatibility-catalog.md Documents the narrower DM v8.5.6 MariaDB precheck workaround and related privilege references.

Review effort: Lite

Comment thread dm/dm-compatibility-catalog.md Resolved
Comment thread migrate-from-mariadb.md Resolved
Comment thread migrate-from-mariadb.md Resolved
Comment thread dm/dm-compatibility-catalog.md Resolved
@ti-chi-bot

ti-chi-bot Bot commented Nov 10, 2026

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from lilin90. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: lilin90 <30922556+lilin90@users.noreply.github.com>
Copilot AI requested a review from lilin90 November 10, 2026 06:55

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 38d42c9 and b0beec4.

Files selected for processing: 3

  • dm/dm-compatibility-catalog.md
  • dm/dm-precheck.md
  • migrate-from-mariadb.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

Comment thread dm/dm-precheck.md Resolved
@lilin90
lilin90 requested a review from zhaoshangzi November 10, 2026 10:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/dm contribution This PR is from a community contributor. needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. ONCALL Relates to documentation oncall. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. translation/welcome Waits for a contributor to translate this PR and create a PR to the pingcap/docs-cn repository. type/bugfix This PR fixes a bug.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants