Test Ecosystem

Test Ecosystem Setup Guide

Certify your AI interactions within a secure, fully isolated integration environment. Effortlessly simulate complex, production-scale deployments to verify zero-trust security boundaries, ensuring your autonomous orchestrations operate with maximum reliability before they ever reach production. Read the full value proposition.

This guide provides the blueprint to deploy, manage, and troubleshoot an integrated test ecosystem featuring InnoDB Cluster, MySQL Router, and ProxySQL. Validate AI agents in an isolated environment before entering production. The stack is configured with Datadog integrations, running alongside Prometheus and Grafana, to provide metrics observability and APM. See Observability for more details.

Tip

Looking for end-user templates? This page documents the heavy internal E2E testing infrastructure. If you just want a clean, user-friendly Docker template for your own projects, check out the examples/ directory in the main repository!

Note

Benchmarks: This test ecosystem includes comprehensive VM sandbox lifecycle benchmarks to validate sandbox pool performance, security validation, and context creation overhead.

---

1. 🚀 Quick Start: Accelerate Validation via Idempotent Deployments

Ensure validation safety and accelerate your testing lifecycle with our fully automated teardown and deployment process. The scripts bootstrap Group Replication idempotently, allowing you to safely simulate production-grade environments and validate AI workflows in minutes.

cd test-server/infrastructure
node scripts/recreate-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. 🏛️ Replicate Production Scenarios with Realistic Topologies

This test ecosystem includes the core database architecture alongside a comprehensive observability stack 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-async-replica││       MySQL Router      │    │   ProxySQL   │  │ redis-server │ │
│ │    Port: 3310     ││ RW: 6446 RO: 6447, 6448 │    │ Admin: 6032  │  │  Port: 6379  │ │
│ └───────────────────┘│     REST API: 8443      │    │ Data:  6033  │  │              │ │
│                      └─────────────────────────┴────┴──────────────┘  └──────────────┘ │
│                                                                              │
│            ┌──────────────────┐           ┌──────────────┐  ┌──────────────┐ │
│            │    Prometheus    │           │   Grafana    │  │   Adminer    │ │
│            │   Port: 9090     │           │  Port: 3001  │  │  Port: 8081  │ │
│            └──────────────────┘           └──────────────┘  └──────────────┘ │
│                                                                              │
│            ┌──────────────────┐           ┌──────────────┐                   │
│            │       Loki       │           │  Grafana     │                   │
│            │   Port: 3100     │           │  Alloy       │                   │
│            └──────────────────┘           └──────────────┘                   │
│                                                                              │
│            ┌──────────────────┐           ┌──────────────┐                   │
│            │      Dozzle      │           │   Datadog    │                   │
│            │    Port: 8080    │           │  (Internal)  │                   │
│            └──────────────────┘           └──────────────┘                   │
│                                                                              │
│            ┌──────────────────┐                                              │
│            │mysql-mcp-exporter│                                              │
│            │    Port: 3000    │                                              │
│            └──────────────────┘                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

3. 🚑 Manage Disaster Recovery Operations

🔄 Reset Data (Re-seed E2E Test DB)

Rapidly restore a pristine state. You may need to re-seed the testdb for E2E validation. This avoids the overhead of tearing down the entire cluster:

cd test-server/infrastructure
node scripts/reset-database.mjs

🛠️ Automated Cluster Recovery

If containers are restarted and the cluster fails to auto-recover via SET PERSIST, you do not need to run manual scripts. The cluster-healer Docker sidecar constantly monitors the cluster topology. If it detects a complete outage, it automatically executes dba.rebootClusterFromCompleteOutage('mcpCluster') and STOP/START GROUP_REPLICATION via mysqlsh. To monitor recovery events:

docker logs -f cluster-healer

🛡️ Host Restart Resilience

All containers in the ecosystem are configured with restart: unless-stopped to gracefully survive host laptop reboots and Docker daemon restarts without manual intervention.

---

4. 🔌 Analyze Network Configurations

🐬 MySQL (via InnoDB Cluster)

Note

The local test cluster uses non-standard ports (3307-3310). This differs from the default 3306 shown in standard configuration examples. This avoids conflicts with local installations.

Property	Value
Primary (R/W)	tcp://localhost:3307
Read Replicas (R/O)	tcp://localhost:3308, tcp://localhost:3309
Async Replica (R/O)	tcp://localhost:3310
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 (Classic), 6448 (X-Protocol) (→ SECONDARY)

📊 Observability & Tools

Property	URL
Datadog	Internal to Docker Network. Use the included Datadog pup CLI script to sync JSON dashboards like AI Efficiency, Token & Tool Metrics, MySQL Cluster Telemetry, Redis Telemetry, and Agent Execution Telemetry.
Prometheus	http://localhost:9090
mysql-mcp-exporter	http://localhost:3000
Loki	http://localhost:3100
Grafana Alloy	http://localhost:12345 (internal HTTP status)
Grafana	http://localhost:3001 (admin/admin)
Dozzle (Logs)	http://localhost:8080
Adminer (DB UI)	http://localhost:8081 (Server: mysql-node1 (uses internal Docker network port 3306), User: root, Pass: root)
ProxySQL Admin	tcp://localhost:6032
ProxySQL Data	tcp://localhost:6033
Redis	tcp://localhost:6379

---

5. ⚠️ Windows Development: WSL2 Guidance

While this ecosystem can be deployed on any standard Docker host, Windows users running native docker-ce inside WSL2 Ubuntu (without Docker Desktop) may encounter a known WSL2 idle timeout behavior. The distro may terminate without active Windows-side client sessions, stopping all containers.

Windows-Specific Workarounds

🛡️ Maintain the Keepalive Mechanism

A Windows Scheduled Task (WSL-KeepAlive) runs at user logon. It is automatically registered by recreate-ecosystem.mjs. It launches wsl.exe -d <Distro-Name> --exec sleep infinity with a hidden window. This holds the distro alive indefinitely.

📡 UDP Telemetry Bridging

When running Datadog Agent or other UDP-based telemetry in a Windows-WSL environment, UDP packets must be explicitly routed across the Windows-WSL boundary. You can achieve this packet bridging using wsl -c "nc -u".

🩺 Diagnose 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 indicates a WSL termination issue.
2. Identify the root cause: Run 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: Certain host kernel environments require iptables-nft. If Docker fails to start, check /etc/docker/daemon.json and update-alternatives --display iptables.

📄 Review Key Config Files

File	Purpose
%USERPROFILE%\.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)

---

Explore Related Topics

• MySQL Router - Connect and query through MySQL Router
• ProxySQL - ProxySQL integration
• MySQL Shell - Run MySQL Shell scripts
• Redis Integration - Redis rate limiting and test isolation
• Observability - Telemetry and monitoring setup