Test Ecosystem

Test Ecosystem Setup Guide

This guide details how to seamlessly deploy, manage, and troubleshoot our lightweight, purpose-built MySQL test ecosystem. Leverage a fully integrated InnoDB Cluster, MySQL Router, and ProxySQL topology to ensure reliable AI agent behavior in rigorous, production-like scenarios.

Value Proposition Accelerate agent validation with a production-grade test ecosystem. Deploy an integrated InnoDB Cluster, MySQL Router, and ProxySQL topology. We validate agent behavior before hitting production. Read the full value proposition.

Note

Note on Datadog: This environment includes native Prometheus and Grafana for metrics observability. If you require full Datadog tracing/APM, you will need to manually inject a Datadog Agent container; it is omitted here to keep the test infrastructure lightweight.

---

1. 🚀 Quick Start: Recreating the Cluster

The entire process of tearing down, spinning up the containers, and bootstrapping Group Replication is automated and idempotent.

cd test-server/infrastructure
node scripts/recreate-test-ecosystem.mjs

This master script will:

• Tear down the existing cluster and volumes (docker compose down -v).
• Start the fresh test containers (docker compose up -d).
• Automatically poll the nodes until they are healthy.
• Initialize the primary node (mysql-node1) as the cluster creator.
• Join mysql-node2 and mysql-node3 to the cluster.
• Output the final cluster topology.

---

2. 🏛️ Architecture Overview

This test ecosystem includes only the necessary components to validate the mysql-mcp server:

┌─────────────────────────────────────────────────────────────────────────────┐
│                    Docker Network: infrastructure_default                    │
│                                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                       │
│  │ mysql-node1  │  │ mysql-node2  │  │ mysql-node3  │                       │
│  │   PRIMARY    │  │  SECONDARY   │  │  SECONDARY   │                       │
│  │  Port: 3307  │  │  Port: 3308  │  │  Port: 3309  │                       │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘                       │
│         │                 │                 │                                │
│         └────────────┬────┴─────────────────┘                                │
│                      ▼                                                       │
│            ┌──────────────────┐           ┌──────────────┐  ┌──────────────┐ │
│            │   MySQL Router   │           │   ProxySQL   │  │    Redis     │ │
│            │ RW: 6446 RO:6447 │           │ Admin: 6032  │  │  Port: 6379  │ │
│            │ REST API: 8443   │           │ Data:  6033  │  │              │ │
│            └──────────────────┴───────────┴──────────────┘  └──────────────┘ │
│                                                                              │
│            ┌──────────────────┐           ┌──────────────┐  ┌──────────────┐ │
│            │    Prometheus    │           │   Grafana    │  │   Adminer    │ │
│            │   Port: 9090     │           │  Port: 3001  │  │  Port: 8081  │ │
│            └──────────────────┘           └──────────────┘  └──────────────┘ │
│                                                                              │
│            ┌──────────────────┐                                              │
│            │      Dozzle      │                                              │
│            │    Port: 8080    │                                              │
│            └──────────────────┘                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

3. 🚑 Disaster Recovery & Operations

🔄 Data Reset (Re-seed E2E Test DB)

If you need to re-seed the testdb for the E2E tests without tearing down the entire cluster:

node scripts/reset-database.mjs

🛠️ Manual Cluster Recovery

If containers are restarted and the cluster fails to auto-recover via SET PERSIST:

node scripts/reboot-cluster.mjs

This script executes dba.rebootClusterFromCompleteOutage().

---

4. 🔌 Connection Details

🐬 MySQL (via InnoDB Cluster)

Note

The local test cluster uses non-standard ports (3307-3309) compared to the default 3306 shown in standard configuration examples to avoid conflicts with local installations.

Property	Value
Primary (R/W)	localhost:3307
Read Replicas (R/O)	localhost:3308, localhost:3309
User	root
Password	root

🚦 MySQL Router

Property	Value
REST API URL	https://localhost:8443
REST API User	rest_api
REST API Password	router_api
RW Routing Port	6446 (→ PRIMARY)
RO Routing Port	6447 (→ SECONDARY)

📊 Observability & Tools

Property	URL
Prometheus	http://localhost:9090
Grafana	http://localhost:3001 (admin/admin)
Dozzle (Logs)	http://localhost:8080
Adminer (DB UI)	http://localhost:8081 (Server: mysql-node1, User: root, Pass: root)
ProxySQL Admin	localhost:6032
ProxySQL Data	localhost:6033
Redis	localhost:6379

---

5. ⚠️ WSL2 Stability (Critical)

This environment runs on native docker-ce inside WSL2 Ubuntu (no Docker Desktop). WSL2 has a known failure mode where the distro instance is terminated when no Windows-side WSL client sessions are holding it open, which kills Docker and all containers.

🛡️ Keepalive Mechanism

A Windows Scheduled Task (WSL-KeepAlive) runs at user logon. It executes scripts/wsl-keepalive.vbs, which launches wsl.exe -d <Distro-Name> --exec sleep infinity with a hidden window. This holds the distro alive indefinitely.

🩺 Diagnosing Crashes

If containers are cycling (green → red → green repeatedly):

1. Check if WSL is rebooting: wsl bash -c "journalctl --list-boots" — multiple short-lived boots = WSL termination issue.
2. Check for the smoking gun: wsl bash -c "dmesg | grep InitTerminateInstanceInternal" — this message means WSL sent systemctl poweroff to the distro.
3. Check the keepalive task: Get-ScheduledTask -TaskName 'WSL-KeepAlive' | Select State — must be Running.
4. Check Docker daemon: wsl bash -c "systemctl status docker" — must be active (running).
5. Check iptables backend: Modern kernel versions require iptables-nft. If Docker fails to start, check /etc/docker/daemon.json and update-alternatives --display iptables.

📄 Key Config Files

File	Purpose
C:\Users\chris\.wslconfig	WSL2 VM config: memory, swap, vmIdleTimeout=-1
/etc/docker/daemon.json	Docker storage driver, log rotation
/etc/systemd/system/wsl-keepalive.service	Backup in-distro keepalive (defense-in-depth)
scripts/wsl-keepalive.vbs	Hidden launcher for the Windows Scheduled Task

---

🌐 Explore Related Topics

• MySQL Router - Connect and query through MySQL Router
• ProxySQL - ProxySQL integration
• MySQL Shell - Run MySQL Shell scripts