docs: comprehensive documentation covering all topologies, providers, proxies, and their differences

[renecannao]

Overview

dbdeployer now supports multiple databases, topologies, and proxy layers. The documentation needs a comprehensive reference that maps all combinations and explains the differences.

What needs to be documented

Provider × Topology Matrix

Topology	MySQL	PostgreSQL	Notes
single	✓	✓
multiple	✓	✓	Independent instances, no replication
replication (master-slave)	✓	✓ (streaming)	MySQL: SQL-based, PG: pg_basebackup
group (single-primary)	✓	—	GR via raw SQL
group (multi-primary)	✓	—
innodb-cluster	✓	—	GR + MySQL Shell + MySQL Router
fan-in	✓	—	Multi-source
all-masters	✓	—	Multi-source circular
ndb	✓	—	NDB Cluster
pxc	✓	—	Percona XtraDB Cluster

Proxy Layer Differences

Feature	ProxySQL	MySQL Router
Configuration	Explicit (mysql_servers, mysql_users)	Auto-bootstrap from cluster metadata
User management	Users must be added to ProxySQL config	Reads from MySQL user table
Failover detection (replication)	Static hostgroups, manual or script-based	N/A (Router doesn't support standard replication)
Failover detection (GR/InnoDB Cluster)	mysql_group_replication_hostgroups	Metadata-aware, automatic
Read/write split	Query rules + hostgroups	Port-based (R/W port vs R/O port)
Compatible topologies	replication, group, innodb-cluster	innodb-cluster only
Compatible providers	MySQL, PostgreSQL	MySQL only
Port model	admin + mysql (2 ports)	R/W + R/O + X R/W + X R/O (4 ports)

MySQL Users in Sandboxes

User	Password	Role	Created by	Used for
root	msandbox	superuser	grants template	MySQL admin
msandbox	msandbox	R_DO_IT_ALL	grants template	Default sandbox user
msandbox_rw	msandbox	R_READ_WRITE	grants template	Read/write (no admin)
msandbox_ro	msandbox	R_READ_ONLY	grants template	Read only
rsandbox	rsandbox	R_REPLICATION	grants template	Replication
icadmin	icadmin	cluster admin	MySQL Shell (InnoDB Cluster only)	Cluster management

How ProxySQL uses these users

ProxySQL config	Current value	Purpose	Ideal value
monitor_username	msandbox	Health checks	rsandbox (#69)
mysql_users	msandbox (HG 0)	Proxy connections	msandbox_rw (HG 0) + msandbox_ro (HG 1) (#70)

Replication Mechanism Differences

	MySQL Standard	MySQL Group Replication	InnoDB Cluster	PostgreSQL Streaming
Init method	CHANGE REPLICATION SOURCE TO	GR plugin SQL	MySQL Shell AdminAPI	pg_basebackup -R
Replica creation	Independent init + SQL wiring	Independent init + GR join	Independent init + cluster.addInstance()	Base backup from running primary
Parallel replica creation	Yes	Yes	Yes	No (sequential, primary must be running)
Failover	Manual	Automatic (within GR)	Automatic (Router/ProxySQL aware)	Manual
Config files	my.cnf	my.cnf + GR options	my.cnf + GR options + cluster metadata	postgresql.conf + pg_hba.conf

Port Allocation

Provider/Topology	Base port	Ports per instance	Range
MySQL	version-derived	3 (main + mysqlx + admin)	8000-9999
PostgreSQL	15000 + major×100 + minor	1	15000-17999
ProxySQL	6032	2 (admin + mysql)	6032+
InnoDB Cluster	21000	varies	21000+
MySQL Router	auto (from bootstrap)	4 (R/W + R/O + X R/W + X R/O)	varies

Sandbox Directory Structure

Document the directory layout for each topology:

• Single: msb_<version>/
• Replication: rsandbox_<version>/master/, node1/, node2/
• Group: group_msb_<version>/node1/, node2/, node3/
• InnoDB Cluster: ic_msb_<version>/node1/, node2/, node3/, router/
• PostgreSQL single: pg_sandbox_<port>/
• PostgreSQL replication: postgresql_repl_<port>/primary/, replica1/, replica2/

Scripts per Topology

Script	Single	Replication	Group	InnoDB Cluster	PG Single	PG Replication
start	✓	start_all	start_all	start_all	✓	per-node
stop	✓	stop_all	stop_all	stop_all	✓	per-node
status	✓	status_all	status_all	status_all	✓	per-node
use	✓	m/s1/s2	n1/n2/n3	n1/n2/n3	✓	primary/use, replica1/use
check_slaves	—	✓	—	—	—	—
check_nodes	—	—	✓	—	—	—
check_cluster	—	—	—	✓	—	—
check_replication	—	—	—	—	—	✓
check_recovery	—	—	—	—	—	✓
router_start	—	—	—	✓	—	—
router_stop	—	—	—	✓	—	—
proxysql/*	optional	optional	optional	optional	—	optional

Deliverable

A comprehensive reference page on the website (or set of pages) covering all the above. Should be navigable, searchable, and useful as a quick reference for both new users and experienced operators.

[coderabbitai]

🔗 Related PRs

#54 - feat: Phase 3 — PostgreSQL provider [merged]
#55 - feat: dbdeployer documentation website (Astro + Starlight) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!