Skip to content

Add database migration docs#887

Open
refat75 wants to merge 11 commits into
masterfrom
migration
Open

Add database migration docs#887
refat75 wants to merge 11 commits into
masterfrom
migration

Conversation

@refat75

@refat75 refat75 commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Summary by CodeRabbit

  • Documentation
    • Added end-to-end database migration guides for MariaDB, MongoDB, MySQL, and PostgreSQL using the KubeDB Migrator, including prerequisites, source authentication/bindings, target database setup, migration configuration (schema/initial copy/CDC), progress monitoring (LAG), and cutover steps (stop writes, wait for LAG to reach zero, update connection strings).
    • Included TLS/mTLS guidance for source connectivity where applicable.
    • Added/updated versioned migration navigation/index pages for MariaDB and MongoDB.
    • Published an operator manual “Migration” page with overview, supported sources, and a step-by-step workflow.

Signed-off-by: Rabbani Islam Refat <refat@appscode.com>
@github-actions

github-actions Bot commented Jun 15, 2026

Copy link
Copy Markdown

Visit the preview URL for this PR (updated for commit b9b45ca):

https://kubedb-v2-hugo--pr887-migration-f4rbd9l5.web.app

(expires Wed, 01 Jul 2026 07:04:18 GMT)

🔥 via Firebase Hosting GitHub Action 🌎

Sign: 0f29ae8ae0bd54a99bf2b223b6833be47acd5943

Signed-off-by: Rabbani Islam Refat <refat@appscode.com>
Comment thread docs/guides/postgres/migration/databaseMigration.md Outdated
Comment thread docs/guides/mariadb/migration/databaseMigration.md
Every 2.0s: kubectl get migrator -n demo

NAME PHASE DBTYPE STAGE LAG PROGRESS AGE
mysql-migrate Running mysql Streaming 0B 4h36m

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

What is the way I can see the migration progress percentage ? I see empty value here.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

MongoShake provides overall migration progress, currently only MongoDB migrations expose this information.

For the other databases, I need to do some work on the monitoring side.

At the moment, the Migrator CR status section displays basic progress information, such as the number of tables that are completed, in progress, and pending.

Signed-off-by: Pulok Saha <puloksaha@appscode.com>
@coderabbitai

coderabbitai Bot commented Jun 18, 2026

Copy link
Copy Markdown

Review Change Stack

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
📝 Walkthrough

Walkthrough

New documentation pages are added for the KubeDB Migrator feature. An operator manual README describes the migration process, helm setup, and a 7-step procedure. Per-database guides (PostgreSQL, MySQL, MariaDB, MongoDB) each cover prerequisites, Kubernetes resource creation, Migrator CR configuration, LAG monitoring, and cutover steps.

Changes

KubeDB Migrator Documentation

Layer / File(s) Summary
Operator manual: overview, setup, and migration procedure
docs/operatormanual/migration/README.md
Introduces the migration concept and operational characteristics, helm setup for fresh installs and upgrades (including manual CRD apply), a numbered 7-step migration procedure, and a supported-database list with links to per-database guides.
Navigation index pages
docs/guides/mariadb/migration/_index.md, docs/guides/mongodb/migration/_index.md
Front-matter-only index files defining versioned menu identifiers, display names, parent sections, and weights for the MariaDB and MongoDB migration doc sections.
PostgreSQL migration guide
docs/guides/postgres/migration/databaseMigration.md
End-to-end guide covering three-phase description (schema dump, bulk copy, logical replication), wal_level=logical prerequisites with per-environment configuration (self-hosted, AWS RDS, Azure, Google Cloud SQL, CloudNativePG), source secret and AppBinding creation, target Postgres CR provisioning, Migrator CR with schemaOnly and logical replication (publication/subscription), LAG monitoring, and cutover steps.
MySQL migration guide
docs/guides/mysql/migration/databaseMigration.md
End-to-end guide covering binlog and replication prerequisites, source secret and AppBinding with optional TLS/mTLS configuration, target MySQL CR, Migrator CR with schema migration, snapshot pipeline with batching parameters, and streaming (CDC) configuration, LAG monitoring, and cutover steps with connection-string repoint.
MariaDB migration guide
docs/guides/mariadb/migration/databaseMigration.md
End-to-end guide covering binlog prerequisites (binlog_format=ROW, binlog_row_image=FULL), source secret and AppBinding with TLS/mTLS support, target MariaDB CR, Migrator CR with schema migration and two-phase data move (snapshot pipeline and CDC streaming), LAG monitoring, cutover via Migrator CR deletion, and connection-string update.
MongoDB migration guide
docs/guides/mongodb/migration/databaseMigration.md
End-to-end guide covering replica set and oplog prerequisites, self-hosted and MongoDB Atlas configuration guidance, source secret and AppBinding creation, target MongoDB CR, Migrator CR with mongoshake full sync (syncMode: all) and extraConfiguration, LAG monitoring, and cutover steps with connection-string repoint.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hoppity-hop through the docs we go,
Four databases migrating, row by row!
A Migrator CR, a LAG near zero,
KubeDB's the guide and you're the hero.
Stop your writes and delete the CR—
Your new database isn't very far! ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title directly and clearly describes the primary change: adding database migration documentation across multiple database systems (PostgreSQL, MySQL, MariaDB, MongoDB).
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch migration

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

Comment @coderabbitai help to get the list of available commands.

@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

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/operatormanual/migration/README.md (1)

59-64: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

MongoDB migration support is missing from the supported database list.

The PR adds a complete MongoDB migration guide (docs/guides/mongodb/migration/databaseMigration.md), but it is not listed in the "Supported Database" section. Add the MongoDB link to maintain consistency with the provided documentation.

📝 Proposed fix to add MongoDB to supported databases
 [PostgreSQL](/docs/guides/postgres/migration/databaseMigration.md)

 [MySQL](/docs/guides/mysql/migration/databaseMigration.md)

 [MariaDB](/docs/guides/mariadb/migration/databaseMigration.md)
+
+[MongoDB](/docs/guides/mongodb/migration/databaseMigration.md)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/operatormanual/migration/README.md` around lines 59 - 64, MongoDB
migration support is missing from the supported database list in the README file
even though the MongoDB migration guide has been added. Add a new line with the
MongoDB migration link in the same format as the existing PostgreSQL, MySQL, and
MariaDB entries in the supported database section at the specified location,
ensuring consistency with the other database migration documentation links.
🧹 Nitpick comments (5)
docs/guides/mariadb/migration/databaseMigration.md (1)

13-13: 💤 Low value

Use descriptive link text instead of "here".

Lines 13 and 23 use the anchor text "here", which is not descriptive. Consider: "Please start [here]" → "Please [start with KubeDB basics]" and "following the steps [here]" → "in the [KubeDB migration setup guide]".

Also applies to: 23-23

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/mariadb/migration/databaseMigration.md` at line 13, The anchor
text "here" used in links at lines 13 and 23 is not descriptive and should be
replaced with more meaningful text. On line 13, change the link text from
"[here]" to something descriptive like "[start with KubeDB basics]" to indicate
what the link leads to. On line 23, similarly replace "[here]" with a
descriptive alternative like "[KubeDB migration setup guide]" that better
describes the linked content. This makes the links more accessible and helps
readers understand where they will navigate to.
docs/guides/mongodb/migration/databaseMigration.md (1)

13-13: 💤 Low value

Use descriptive link text instead of "here".

Lines 13 and 23 use the anchor text "here", which is not descriptive. Consider: "Please start [here]" → "Please [start with KubeDB basics]" and "following the steps [here]" → "in the [KubeDB migration setup guide]".

Also applies to: 23-23

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/mongodb/migration/databaseMigration.md` at line 13, Replace
non-descriptive link text "here" with meaningful, descriptive anchor text that
explains what the user will find when clicking the link. In the
databaseMigration.md file, change the anchor text on line 13 from "here" to
something descriptive like "start with KubeDB basics" that indicates the link
leads to KubeDB documentation basics, and similarly update the anchor text on
line 23 from "here" to a descriptive alternative like "KubeDB migration setup
guide" that clearly indicates the link's destination and purpose. Ensure the new
link text is concise and provides context about what the reader will encounter.
docs/operatormanual/migration/README.md (1)

16-16: 💤 Low value

Use descriptive link text instead of "here".

Line 16 has a link with the anchor text "here", which does not describe what the link points to. Consider: "Please start here" → "Please start with KubeDB basics" or similar.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/operatormanual/migration/README.md` at line 16, The link text "here" in
the blockquote on line 16 is not descriptive and does not convey the destination
or purpose to users. Replace the anchor text "here" with a more descriptive
phrase such as "KubeDB basics" or "get started with KubeDB" while keeping the
URL path /docs/README.md unchanged. This improves accessibility and user
experience by making the link destination clear before clicking.
docs/guides/postgres/migration/databaseMigration.md (1)

13-13: 💤 Low value

Use descriptive link text instead of "here".

Lines 13 and 31 use the anchor text "here", which is not descriptive. Consider: "Please start [here]" → "Please [start with KubeDB basics]" and "Install KubeDB operator with the Migrator operator enabled in your cluster following the steps [here]" → "following the steps in the [KubeDB migration setup guide]".

Also applies to: 31-31

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/postgres/migration/databaseMigration.md` at line 13, The link
anchor text "here" on lines 13 and 31 is not descriptive and should be replaced
with meaningful text that describes the destination. On line 13, change the
anchor text from "here" in the phrase about starting with KubeDB to descriptive
text like "start with KubeDB basics". On line 31, change the anchor text from
"here" in the phrase about migration steps to descriptive text like "KubeDB
migration setup guide" to make the link purpose clear to readers.
docs/guides/mysql/migration/databaseMigration.md (1)

13-13: 💤 Low value

Use descriptive link text instead of "here".

Lines 13 and 23 use the anchor text "here", which is not descriptive. Consider: "Please start [here]" → "Please [start with KubeDB basics]" and "following the steps [here]" → "in the [KubeDB migration setup guide]".

Also applies to: 23-23

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/guides/mysql/migration/databaseMigration.md` at line 13, The link anchor
text "here" on lines 13 and 23 is not descriptive and does not convey what the
user will find when clicking the link. Replace the generic "here" text with
descriptive alternatives that explain the link's purpose: on line 13 change
"start [here]" to "start with [KubeDB basics]" to describe the README content,
and on line 23 change "following the steps [here]" to a descriptive phrase like
"[KubeDB migration setup guide]" that clearly indicates what the reader will
find. This improves accessibility and helps users understand where they are
being directed before clicking.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/guides/mysql/migration/databaseMigration.md`:
- Around line 99-101: The kubectl command at line 99 references a remote
quickstart-v1.yaml template from GitHub instead of using the target-mysql.yaml
file that was created earlier in the guide (lines 80-96). Replace the entire
command to use kubectl apply with the locally created target-mysql.yaml file
instead of kubectl create with the remote quickstart URL. This will ensure users
deploy the configured database defined in the migration workflow steps, not a
generic quickstart template, and will align with the PostgreSQL and MariaDB
guide examples.

---

Outside diff comments:
In `@docs/operatormanual/migration/README.md`:
- Around line 59-64: MongoDB migration support is missing from the supported
database list in the README file even though the MongoDB migration guide has
been added. Add a new line with the MongoDB migration link in the same format as
the existing PostgreSQL, MySQL, and MariaDB entries in the supported database
section at the specified location, ensuring consistency with the other database
migration documentation links.

---

Nitpick comments:
In `@docs/guides/mariadb/migration/databaseMigration.md`:
- Line 13: The anchor text "here" used in links at lines 13 and 23 is not
descriptive and should be replaced with more meaningful text. On line 13, change
the link text from "[here]" to something descriptive like "[start with KubeDB
basics]" to indicate what the link leads to. On line 23, similarly replace
"[here]" with a descriptive alternative like "[KubeDB migration setup guide]"
that better describes the linked content. This makes the links more accessible
and helps readers understand where they will navigate to.

In `@docs/guides/mongodb/migration/databaseMigration.md`:
- Line 13: Replace non-descriptive link text "here" with meaningful, descriptive
anchor text that explains what the user will find when clicking the link. In the
databaseMigration.md file, change the anchor text on line 13 from "here" to
something descriptive like "start with KubeDB basics" that indicates the link
leads to KubeDB documentation basics, and similarly update the anchor text on
line 23 from "here" to a descriptive alternative like "KubeDB migration setup
guide" that clearly indicates the link's destination and purpose. Ensure the new
link text is concise and provides context about what the reader will encounter.

In `@docs/guides/mysql/migration/databaseMigration.md`:
- Line 13: The link anchor text "here" on lines 13 and 23 is not descriptive and
does not convey what the user will find when clicking the link. Replace the
generic "here" text with descriptive alternatives that explain the link's
purpose: on line 13 change "start [here]" to "start with [KubeDB basics]" to
describe the README content, and on line 23 change "following the steps [here]"
to a descriptive phrase like "[KubeDB migration setup guide]" that clearly
indicates what the reader will find. This improves accessibility and helps users
understand where they are being directed before clicking.

In `@docs/guides/postgres/migration/databaseMigration.md`:
- Line 13: The link anchor text "here" on lines 13 and 31 is not descriptive and
should be replaced with meaningful text that describes the destination. On line
13, change the anchor text from "here" in the phrase about starting with KubeDB
to descriptive text like "start with KubeDB basics". On line 31, change the
anchor text from "here" in the phrase about migration steps to descriptive text
like "KubeDB migration setup guide" to make the link purpose clear to readers.

In `@docs/operatormanual/migration/README.md`:
- Line 16: The link text "here" in the blockquote on line 16 is not descriptive
and does not convey the destination or purpose to users. Replace the anchor text
"here" with a more descriptive phrase such as "KubeDB basics" or "get started
with KubeDB" while keeping the URL path /docs/README.md unchanged. This improves
accessibility and user experience by making the link destination clear before
clicking.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ad86f9e0-225e-4855-bc67-36d7ef935df7

📥 Commits

Reviewing files that changed from the base of the PR and between fc50286 and 7890fc2.

📒 Files selected for processing (7)
  • docs/guides/mariadb/migration/_index.md
  • docs/guides/mariadb/migration/databaseMigration.md
  • docs/guides/mongodb/migration/_index.md
  • docs/guides/mongodb/migration/databaseMigration.md
  • docs/guides/mysql/migration/databaseMigration.md
  • docs/guides/postgres/migration/databaseMigration.md
  • docs/operatormanual/migration/README.md

Comment thread docs/guides/mysql/migration/databaseMigration.md Outdated
refat75 and others added 8 commits June 18, 2026 18:42
Signed-off-by: Rabbani Islam Refat <refat@appscode.com>
Signed-off-by: Rabbani Islam Refat <refat@appscode.com>
Signed-off-by: Rabbani Islam Refat <refat@appscode.com>
Signed-off-by: Rabbani Islam Refat <refat@appscode.com>
Signed-off-by: Rabbani Islam Refat <refat@appscode.com>
Signed-off-by: Rabbani Islam Refat <refat@appscode.com>
Signed-off-by: Pulok Saha <puloksaha@appscode.com>
Signed-off-by: Rabbani Islam Refat <refat@appscode.com>
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.

3 participants