docs: write full content for all topology and provider pages#75
docs: write full content for all topology and provider pages#75renecannao merged 1 commit intomasterfrom
Conversation
…oDB Cluster, MySQL provider
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (7)
📝 WalkthroughWalkthroughThis PR expands documentation for dbdeployer deployment topologies and MySQL providers. It adds a new InnoDB Cluster guide page, updates the Astro sidebar configuration, and replaces placeholder content in five deployment and provider documentation files with detailed technical guidance on topology deployment, configuration, and operations. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~28 minutes Possibly related PRs
Poem
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for various database topologies and providers, including Fan-In & All-Masters, Group Replication, InnoDB Cluster, NDB Cluster, MySQL, and Percona XtraDB Cluster. I have provided feedback to align the documentation with modern MySQL terminology and syntax, specifically recommending the use of 'Source-Replica' over 'Master-slave' and 'SHOW REPLICA STATUS' over the deprecated 'SHOW SLAVE STATUS'.
| ## Running Queries on All Nodes | ||
|
|
||
| ```bash | ||
| ~/sandboxes/all_masters_msb_8_4_8/use_all -e "SHOW SLAVE STATUS\G" | grep -E "Master_Host|Running" |
There was a problem hiding this comment.
In MySQL 8.0.22 and later, the SHOW SLAVE STATUS command and the Master_Host column are deprecated in favor of SHOW REPLICA STATUS and Source_Host. Since the examples in this documentation use MySQL 8.4.8 (LTS), it is recommended to use the modern syntax for better alignment with current best practices.
| ~/sandboxes/all_masters_msb_8_4_8/use_all -e "SHOW SLAVE STATUS\G" | grep -E "Master_Host|Running" | |
| ~/sandboxes/all_masters_msb_8_4_8/use_all -e "SHOW REPLICA STATUS\G" | grep -E "Source_Host|Running" |
| | Topology | Flag | Min Version | | ||
| |----------|------|-------------| | ||
| | Single | `deploy single` | any | | ||
| | Master-slave | `--topology=master-slave` (default) | any | |
There was a problem hiding this comment.
The term 'Master-slave' is deprecated in official MySQL documentation in favor of 'Source-Replica'. While the CLI flag --topology=master-slave remains for technical compatibility, updating the label in the documentation table improves clarity and adheres to modern terminology standards.
| | Master-slave | `--topology=master-slave` (default) | any | | |
| | Source-Replica | --topology=master-slave (default) | any | |
There was a problem hiding this comment.
Pull request overview
This PR replaces multiple “Coming soon” stubs in the website documentation with full pages covering additional MySQL topologies/providers (Group Replication, Fan-In/All-Masters, NDB Cluster, PXC) and adds a new InnoDB Cluster page, plus expands the MySQL provider documentation.
Changes:
- Add full documentation pages for Group Replication, Fan-In/All-Masters, NDB Cluster, and PXC.
- Introduce a new “InnoDB Cluster” documentation page and add it to the Astro sidebar navigation.
- Expand “MySQL provider” documentation to cover flavors, binary management, supported versions, and topologies.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| website/src/content/docs/providers/pxc.md | Replaces stub with PXC/Galera usage docs and examples. |
| website/src/content/docs/providers/mysql.md | Expands MySQL provider docs: flavors, downloads/unpack, version/topology support. |
| website/src/content/docs/deploying/ndb-cluster.md | Adds NDB Cluster topology docs and example commands/layout. |
| website/src/content/docs/deploying/innodb-cluster.md | New page documenting InnoDB Cluster deployment and Router/ProxySQL options. |
| website/src/content/docs/deploying/group-replication.md | Adds Group Replication deployment docs and usage notes. |
| website/src/content/docs/deploying/fan-in-all-masters.md | Adds multi-source topology docs (fan-in and all-masters) with examples. |
| website/astro.config.mjs | Adds “InnoDB Cluster” entry to the Deploying sidebar nav. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Flavor | Tarball prefix | Notes | | ||
| |--------|---------------|-------| | ||
| | MySQL Community Server | `mysql-` | Default; versions 5.7, 8.0, 8.4, 9.x | | ||
| | Percona Server | `Percona-Server-` | Drop-in MySQL replacement with extra features | | ||
| | MariaDB | `mariadb-` | Compatible with MySQL 5.7 API; some features differ | |
There was a problem hiding this comment.
The tables in this page use || at the start of header/separator rows (e.g., || Flavor | ...). Standard Markdown tables use single | delimiters; the doubled pipes can break rendering in Astro/Markdown processors. Update these rows to the standard | col | col | format so the tables render consistently with the rest of the docs site.
| | Series | Status | Topologies | | ||
| |--------|--------|-----------| | ||
| | 5.7.x | Legacy | single, replication, group (5.7.17+) | | ||
| | 8.0.x | Stable | all topologies | | ||
| | 8.4.x | LTS (recommended) | all topologies | | ||
| | 9.x | Innovation | all topologies | | ||
|
|
There was a problem hiding this comment.
Same as above: this versions/status table uses || prefixes. Please convert it to a standard Markdown table (single | delimiters) to ensure it renders correctly.
| | Master-slave | `--topology=master-slave` (default) | any | | ||
| | Group Replication | `--topology=group` | 5.7.17 | | ||
| | Single-primary GR | `--topology=group --single-primary` | 5.7.17 | | ||
| | InnoDB Cluster | `--topology=innodb-cluster` | 8.0 | |
There was a problem hiding this comment.
The minimum version for InnoDB Cluster is documented as 8.0, but the implementation enforces 8.0.11+ (it errors with “InnoDB Cluster requires MySQL 8.0.11 or later”). Please update the min-version column to 8.0.11 to match actual behavior.
| | InnoDB Cluster | `--topology=innodb-cluster` | 8.0 | | |
| | InnoDB Cluster | `--topology=innodb-cluster` | 8.0.11 | |
| ```bash | ||
| dbdeployer unpack mysql-cluster-8.4.8-linux-glibc2.17-x86_64.tar.gz | ||
| dbdeployer versions | ||
| # cluster_8.4.8 | ||
| ``` | ||
|
|
||
| dbdeployer detects that the tarball is an NDB Cluster build and marks the version accordingly. |
There was a problem hiding this comment.
This page says dbdeployer versions will show cluster_8.4.8 after unpacking, but dbdeployer versions lists the binary directory names (and unpack names the directory as --prefix + version). Unless the user supplies --prefix, unpacking mysql-cluster-8.4.8... results in a directory like 8.4.8, not cluster_8.4.8. Please adjust the example/output (and, if you want a visible prefix like ndb8.4.8, show using dbdeployer unpack --prefix=ndb ...).
| ## Deploying an NDB Cluster | ||
|
|
||
| ```bash | ||
| dbdeployer deploy replication 8.4.8 --topology=ndb --ndb-nodes=3 |
There was a problem hiding this comment.
The deploy example uses dbdeployer deploy replication 8.4.8 --topology=ndb, but earlier the page implies a prefixed version label. To avoid confusion, make the version argument consistent with whatever directory name you tell users to create (e.g., 8.4.8 if no prefix, or ndb8.4.8 if using --prefix=ndb).
| dbdeployer deploy replication 8.4.8 --topology=ndb --ndb-nodes=3 | |
| dbdeployer deploy replication cluster_8.4.8 --topology=ndb --ndb-nodes=3 |
| # node1:3310 PRIMARY ONLINE | ||
| # node2:3320 SECONDARY ONLINE | ||
| # node3:3330 SECONDARY ONLINE |
There was a problem hiding this comment.
The sample check_cluster output shows node ports 3310/3320/3330, but InnoDB Cluster port allocation is based on the InnoDB Cluster base port range (defaults to 21000 + offsets) rather than the classic 3310/3320/3330 pattern. Consider updating the example output to reflect the actual ports users will see (or omit specific port numbers to keep it accurate across configurations).
| # node1:3310 PRIMARY ONLINE | |
| # node2:3320 SECONDARY ONLINE | |
| # node3:3330 SECONDARY ONLINE | |
| # node1 PRIMARY ONLINE | |
| # node2 SECONDARY ONLINE | |
| # node3 SECONDARY ONLINE |
| ``` | ||
| ~/sandboxes/pxc_msb_8_0_35/ | ||
| ├── node1/ # writable Galera node | ||
| ├── node2/ # writable Galera node | ||
| ├── node3/ # writable Galera node | ||
| ├── check_nodes | ||
| ├── start_all | ||
| ├── stop_all | ||
| └── use_all |
There was a problem hiding this comment.
This wsrep example refers to node1/ node2/ node3/ in the layout, but the command examples use n1/n2/n3 helper scripts. If the intent is to show the helper scripts, consider updating the directory tree comments to mention that n1, n2, n3 scripts are generated alongside node1/.. to avoid confusion for first-time users.
| ## Monitoring: check_nodes | ||
|
|
||
| The `check_nodes` script queries `performance_schema.replication_group_members` on each node and summarizes the group state: | ||
|
|
||
| ```bash | ||
| ~/sandboxes/group_msb_8_4_8/check_nodes | ||
| # node 1 - ONLINE (PRIMARY) | ||
| # node 2 - ONLINE (SECONDARY) | ||
| # node 3 - ONLINE (SECONDARY) | ||
| ``` |
There was a problem hiding this comment.
The check_nodes script for Group Replication runs select * from performance_schema.replication_group_members on each node (raw output), but this page describes it as a summarized status report and shows example lines like # node 1 - ONLINE (PRIMARY). Please update the description/example output to match what the script actually prints.
| # node 1 - wsrep_cluster_size=3 wsrep_local_state_comment=Synced | ||
| # node 2 - wsrep_cluster_size=3 wsrep_local_state_comment=Synced | ||
| # node 3 - wsrep_cluster_size=3 wsrep_local_state_comment=Synced |
There was a problem hiding this comment.
The PXC check_nodes script prints a header per node and then the raw SHOW GLOBAL STATUS ... wsrep_* result set, but the example output here is a single-line summary per node. Please adjust the example to match the real script output (or describe it generically without hardcoding an output format).
| # node 1 - wsrep_cluster_size=3 wsrep_local_state_comment=Synced | |
| # node 2 - wsrep_cluster_size=3 wsrep_local_state_comment=Synced | |
| # node 3 - wsrep_cluster_size=3 wsrep_local_state_comment=Synced | |
| # Prints a header for each node, followed by that node's | |
| # `SHOW GLOBAL STATUS LIKE 'wsrep_%'` result set. |
| ~/sandboxes/ndb_msb_8_4_8/check_nodes | ||
| # or connect to the management node: |
There was a problem hiding this comment.
~/sandboxes/.../check_nodes in NDB deployments is generated from the ndb_mgm template (it launches the NDB management client). It won’t print status by itself unless arguments are provided. The example here implies check_nodes outputs status directly; consider changing it to something like check_nodes -e show / check_nodes -e "ALL STATUS", or document that check_nodes opens ndb_mgm and users should pass -e commands.
| ~/sandboxes/ndb_msb_8_4_8/check_nodes | |
| # or connect to the management node: | |
| ~/sandboxes/ndb_msb_8_4_8/check_nodes -e "ALL STATUS" | |
| # or connect to the management node directly: |
Summary
Replaces all stub pages with real documentation:
42 pages build successfully.
Summary by CodeRabbit