docs: add comprehensive topology/provider/proxy reference (#71)

[renecannao]

Summary

New reference page covering all topologies, providers, proxies, and their differences in one place.

Sections:

1. Provider × Topology matrix — what works where
2. Proxy layer differences — ProxySQL vs MySQL Router (config, failover, R/W split, ports)
3. MySQL sandbox users — all users, roles, passwords
4. ProxySQL user configuration — monitor, R/W, R/O users
5. Replication mechanism differences — MySQL standard vs GR vs InnoDB Cluster vs PostgreSQL
6. Port allocation — ranges for each provider/topology
7. Sandbox directory structures — layout for each topology
8. Available scripts per topology — what scripts exist where
9. Command quick reference — deploy commands for every topology

Added to website sidebar under Reference > Topology Reference.

Closes #71

Test Plan

• Website builds (41 pages)
• Sidebar entry renders

Summary by CodeRabbit

• Documentation
  • Added a new "Topology Reference" documentation page providing comprehensive reference material for dbdeployer configurations, including provider and topology support matrices for MySQL and PostgreSQL variants, proxy-layer comparisons between ProxySQL and MySQL Router, replication mechanism details, deterministic port allocation rules, sandbox directory structures across topology types, available helper scripts per topology, and command examples for deployment scenarios.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e7d3a273-169d-430a-8eb9-28e843210eb2

📥 Commits

Reviewing files that changed from the base of the PR and between 2c6eba9 and 29cae3e.

📒 Files selected for processing (2)

• website/astro.config.mjs
• website/src/content/docs/reference/topology-reference.md

---

📝 Walkthrough

Walkthrough

This PR extends the documentation site by adding a new "Topology Reference" navigation item and comprehensive reference page. The new documentation consolidates information about dbdeployer's supported database providers, topologies, proxy layers, configuration matrices, directory structures, and helper scripts.

Changes

Cohort / File(s)	Summary
Navigation Configuration website/astro.config.mjs	Added "Topology Reference" sidebar link to the Reference section of the Starlight documentation configuration.
Documentation Content website/src/content/docs/reference/topology-reference.md	New comprehensive reference page documenting provider × topology support matrices (MySQL/PostgreSQL), proxy layer differences (ProxySQL vs MySQL Router), default sandbox users, replication mechanisms, deterministic port allocation rules, sandbox directory structures across topology types, helper scripts availability matrix, and example deployment commands.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 Hops of joy through topology lands,
A reference map now in reviewers' hands,
From proxies to ports, each sandbox design,
The docs now complete—what a grand design!
No more confusion, just clarity bright,
dbdeployer's paths made perfectly right! 🎉

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree-agent-aae77db6

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive 'Topology Reference' documentation page for dbdeployer, covering provider-topology matrices, proxy layer differences, user management, and directory structures. The review feedback highlights several technical inaccuracies in the new documentation, specifically regarding ProxySQL's compatibility with single topologies, the mathematical formula for MySQL port derivation, and the specific directory naming conventions used for PostgreSQL sandboxes.

[gemini-code-assist]

ProxySQL is also compatible with the single topology, as implemented in the deploy single command (see cmd/single.go). It should be included in the list of compatible topologies.

Suggested change

	| Compatible topologies | replication, group, innodb-cluster | innodb-cluster only |
	| Compatible topologies | single, replication, group, innodb-cluster | innodb-cluster only |

[gemini-code-assist]

The formula for the MySQL base port is incorrect. Based on the example 8.4.8 → 8408, the calculation is major * 1000 + minor * 100 + revision. The current text incorrectly states minor * 10.

Suggested change

	| MySQL single | Version-derived (e.g. `major×1000 + minor×10`) | 3 (main + admin + mysqlx) | 8.4.8 → 8408 |
	| MySQL single | Version-derived (e.g. major×1000 + minor×100 + revision) | 3 (main + admin + mysqlx) | 8.4.8 → 8408 |

[gemini-code-assist]

The directory name for PostgreSQL single sandboxes in the documentation (pgsb_16_13) does not match the implementation in cmd/single.go. The code uses the format postgresql_sandbox_{port} (e.g., postgresql_sandbox_16613).

Suggested change

	~/sandboxes/pgsb_16_13/
	~/sandboxes/postgresql_sandbox_16613/

[gemini-code-assist]

The directory name for PostgreSQL replication sandboxes in the documentation (pgrsandbox_16_13) does not match the implementation in cmd/replication.go. The code uses the format postgresql_repl_{port} (e.g., postgresql_repl_16613).

Suggested change

	~/sandboxes/pgrsandbox_16_13/
	~/sandboxes/postgresql_repl_16613/

[Copilot]

Pull request overview

Adds a new “Topology Reference” documentation page intended to centralize provider/topology/proxy/user/ports/scripts/directory-layout information, and links it from the website sidebar under Reference.

Changes:

• Added a comprehensive topology/provider/proxy reference page.
• Added a new sidebar entry pointing to the new reference page.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 14 comments.

File	Description
website/src/content/docs/reference/topology-reference.md	New reference page covering supported topologies/providers plus proxy/users/ports/scripts/directory layouts and command examples.
website/astro.config.mjs	Adds “Topology Reference” to the Reference section of the docs sidebar.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

--check-port is referenced here, but there is no such CLI flag (no matches in cmd/ or elsewhere). Since dbdeployer does do port bumping via FindFreePort, consider either removing the preview suggestion or pointing to an existing command/documentation for inspecting computed ports.

Suggested change

	Port conflicts are automatically avoided: dbdeployer checks whether a port is in use before deploying and bumps the base if needed. Use `dbdeployer deploy single <version> --check-port` to preview the port that will be used.
	Port conflicts are automatically avoided: dbdeployer checks whether a port is in use before deploying and bumps the base if needed.

[Copilot]

This table implies ProxySQL uses rsandbox as monitor user and that multiple application users are configured in mysql_users. In the current ProxySQL deployment flow, monitor_user defaults to msandbox and the generated mysql_users/pgsql_users block contains only that one user (see sandbox/proxysql_topology.go and providers/proxysql/config.go). Please update these rows to match current behavior (or adjust the implementation if the intent is to preconfigure RW/RO users).

Suggested change

	| `mysql_monitor_username` | `rsandbox` | Health checks (requires `REPLICATION CLIENT`) |
	| `mysql_monitor_password` | `rsandbox` | Corresponding password |
	| `mysql_users`: `msandbox` | `default_hostgroup=0` | General proxy connections routed to the writer group |
	| `mysql_users`: `msandbox_rw` | `default_hostgroup=0` | Explicit write connections |
	| `mysql_users`: `msandbox_ro` | `default_hostgroup=1` | Read connections routed to the reader group |
	| `mysql_monitor_username` | `msandbox` | Health checks using the default monitor user configured by dbdeployer |
	| `mysql_monitor_password` | `msandbox` | Corresponding password |
	| `mysql_users`: `msandbox` | `default_hostgroup=0` | Only preconfigured ProxySQL frontend user; connections default to the writer hostgroup |

[Copilot]

PostgreSQL single sandbox directory naming here (pgsb_16_13) doesn’t match the implementation. dbdeployer deploy postgresql 16.13 creates ~/sandboxes/pg_sandbox_<port>/ (e.g., pg_sandbox_16613). Please update this example path to the real one.

Suggested change

	~/sandboxes/pgsb_16_13/
	~/sandboxes/pg_sandbox_16613/

[Copilot]

The ProxySQL overlay tree doesn’t match what the ProxySQL provider generates: the config file is proxysql.cnf and the scripts are use (admin) + use_proxy (proxy), not use_admin + use and not proxysql.cfg (see providers/proxysql/proxysql.go). Please align the filenames/script names here.

Suggested change

	├── use_admin # Admin interface (port 6032)
	├── use # Proxy interface (port 6033)
	├── proxysql.cfg # Initial bootstrap config
	├── use # Admin interface (port 6032)
	├── use_proxy # Proxy interface (port 6033)
	├── proxysql.cnf # Initial bootstrap config

[Copilot]

PostgreSQL replication topology directory naming/layout here (pgrsandbox_16_13/ with master/) doesn’t match the implementation. The code uses ~/sandboxes/postgresql_repl_<port>/primary/replicaN (see cmd/replication.go). Please update this example path and the node directory names accordingly.

Suggested change

	~/sandboxes/pgrsandbox_16_13/
	├── start_all
	├── stop_all
	├── status_all
	├── use_all
	├── check_replicas # Show replication lag / state
	├── metadata
	├── master/
	~/sandboxes/postgresql_repl_<port>/
	├── start_all
	├── stop_all
	├── status_all
	├── use_all
	├── check_replicas # Show replication lag / state
	├── metadata
	├── primary/

[Copilot]

This section documents ProxySQL config variables as mysql_monitor_username/mysql_monitor_password, but the generated proxysql.cnf uses monitor_username/monitor_password inside mysql_variables (or pgsql_variables) (see providers/proxysql/config.go). Please align the docs with the actual variable names.

Suggested change

	| `mysql_monitor_username` | `rsandbox` | Health checks (requires `REPLICATION CLIENT`) |
	| `mysql_monitor_password` | `rsandbox` | Corresponding password |
	| `monitor_username` | `rsandbox` | Health checks (requires `REPLICATION CLIENT`) |
	| `monitor_password` | `rsandbox` | Corresponding password |

[Copilot]

The MySQL port formula shown (major×1000 + minor×10) doesn’t match how dbdeployer computes ports. For MySQL, common.VersionToPort() formats major, minor, and a zero-padded 2-digit rev (e.g., 8.4.8 → 8408). Please correct the formula text to match the implementation.

Suggested change

	| MySQL single | Version-derived (e.g. `major×1000 + minor×10`) | 3 (main + admin + mysqlx) | 8.4.8 → 8408 |
	| MySQL single | Version-derived (formatted as `major`, `minor`, and zero-padded 2-digit `rev`) | 3 (main + admin + mysqlx) | 8.4.8 → 8408 |

[Copilot]

These examples label --topology=group as “single-primary mode”, but single-primary is controlled by the boolean --single-primary flag; without it, group replication deploys multi-primary (group_msb_...). Please adjust the example commands so the described mode matches the flags used.

Suggested change

	dbdeployer deploy replication 8.4.8 --topology=group
	# Group Replication, multi-primary mode
	dbdeployer deploy replication 8.4.8 --topology=group --single-primary=false
	dbdeployer deploy replication 8.4.8 --topology=group --single-primary
	# Group Replication, multi-primary mode
	dbdeployer deploy replication 8.4.8 --topology=group

[Copilot]

These PostgreSQL examples also use --proxy=proxysql, but the supported flag is --with-proxysql. Please update this command line so it’s copy/paste correct.

Suggested change

	dbdeployer deploy replication 16.13 --provider=postgresql --proxy=proxysql
	dbdeployer deploy replication 16.13 --provider=postgresql --with-proxysql

[Copilot]

The InnoDB Cluster example shows router/start and router/stop, but dbdeployer generates router_start/router_stop scripts at the topology root, and Router bootstrap creates router/start.sh (see sandbox/innodb_cluster.go). Please update this directory listing to match the real script names.

Suggested change

	├── router/ # MySQL Router instance
	│ ├── start
	│ ├── stop
	├── router_start
	├── router_stop
	├── router/ # MySQL Router instance
	│ ├── start.sh