docs: write full content for all topology and provider pages by renecannao · Pull Request #75 · ProxySQL/dbdeployer · GitHub
Skip to content

docs: write full content for all topology and provider pages#75

Merged
renecannao merged 1 commit into
masterfrom
worktree-agent-add34511
Apr 3, 2026
Merged

docs: write full content for all topology and provider pages#75
renecannao merged 1 commit into
masterfrom
worktree-agent-add34511

Conversation

@renecannao

@renecannao renecannao commented Apr 3, 2026

Copy link
Copy Markdown

Summary

Replaces all stub pages with real documentation:

  • Group Replication — single-primary vs multi-primary, check_nodes, scripts
  • Fan-In & All-Masters — multi-source replication, --master-list/--slave-list
  • NDB Cluster — NDB tarball, --ndb-nodes, data vs SQL nodes
  • PXC — Percona XtraDB Cluster, Galera, all-writable
  • InnoDB Cluster (NEW) — GR + MySQL Shell + Router, --skip-router, ProxySQL alternative
  • MySQL provider — expanded from 29→80 lines: flavors, versions, binary management

42 pages build successfully.

Summary by CodeRabbit

  • Documentation
    • Added new comprehensive guide for deploying MySQL InnoDB Cluster
    • Expanded complete documentation for Fan-In, All-Masters, Group Replication, and NDB Cluster deployment topologies with usage examples and configuration options
    • Enhanced MySQL and Percona XtraDB Cluster provider documentation with deployment workflows, version compatibility tables, and topology coverage
    • Updated navigation to include InnoDB Cluster documentation entry

Copilot AI review requested due to automatic review settings April 3, 2026 07:28
@renecannao renecannao merged commit cc30aca into master Apr 3, 2026
8 of 25 checks passed
@coderabbitai

coderabbitai Bot commented Apr 3, 2026

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist 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.

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"

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

medium

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.

Suggested change
~/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 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

medium

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.

Suggested change
| Master-slave | `--topology=master-slave` (default) | any |
| Source-Replica | --topology=master-slave (default) | any |

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.

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.

Comment on lines +10 to +14
| 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 |

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

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.

Copilot uses AI. Check for mistakes.
Comment on lines +86 to +92
| 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 |

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

Same as above: this versions/status table uses || prefixes. Please convert it to a standard Markdown table (single | delimiters) to ensure it renders correctly.

Copilot uses AI. Check for mistakes.
| 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 |

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

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.

Suggested change
| InnoDB Cluster | `--topology=innodb-cluster` | 8.0 |
| InnoDB Cluster | `--topology=innodb-cluster` | 8.0.11 |

Copilot uses AI. Check for mistakes.
Comment on lines +14 to +20
```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.

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

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 ...).

Copilot uses AI. Check for mistakes.
## Deploying an NDB Cluster

```bash
dbdeployer deploy replication 8.4.8 --topology=ndb --ndb-nodes=3

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

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).

Suggested change
dbdeployer deploy replication 8.4.8 --topology=ndb --ndb-nodes=3
dbdeployer deploy replication cluster_8.4.8 --topology=ndb --ndb-nodes=3

Copilot uses AI. Check for mistakes.
Comment on lines +98 to +100
# node1:3310 PRIMARY ONLINE
# node2:3320 SECONDARY ONLINE
# node3:3330 SECONDARY ONLINE

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

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).

Suggested change
# node1:3310 PRIMARY ONLINE
# node2:3320 SECONDARY ONLINE
# node3:3330 SECONDARY ONLINE
# node1 PRIMARY ONLINE
# node2 SECONDARY ONLINE
# node3 SECONDARY ONLINE

Copilot uses AI. Check for mistakes.
Comment on lines +30 to +38
```
~/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

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

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.

Copilot uses AI. Check for mistakes.
Comment on lines +53 to +62
## 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)
```

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

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.

Copilot uses AI. Check for mistakes.
Comment on lines +68 to +70
# 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

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

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).

Suggested change
# 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.

Copilot uses AI. Check for mistakes.
Comment on lines +67 to +68
~/sandboxes/ndb_msb_8_4_8/check_nodes
# or connect to the management node:

Copilot AI Apr 3, 2026

Copy link

Choose a reason for hiding this comment

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

~/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.

Suggested change

Copilot uses AI. Check for mistakes.
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.

2 participants