ProxySQL

ProxySQL Integration Guide

dbdeployer can deploy ProxySQL alongside MySQL sandboxes, automatically configuring backends, hostgroups, and monitoring.

Table of Contents

• Quick Start (5 Minutes)
• Prerequisites
• Standalone ProxySQL
• Single MySQL + ProxySQL
• Replication + ProxySQL
• Group Replication
• ProxySQL Sandbox Structure
• Connecting to ProxySQL
• Configuration Details
• Topology-Aware Hostgroups
• Managing Sandboxes
• Troubleshooting
• Reference

---

Quick Start (5 Minutes)

Deploy a MySQL replication cluster with ProxySQL in front:

# 1. Install prerequisites
#    - Go 1.22+ (for building from source)
#    - ProxySQL binary in PATH
#    - MySQL tarballs unpacked

# 2. Build dbdeployer
go build -o dbdeployer .
export PATH=$PWD:$PATH

# 3. Unpack a MySQL tarball
dbdeployer unpack /path/to/mysql-8.4.4-linux-glibc2.17-x86_64.tar.xz

# 4. Deploy replication with ProxySQL
dbdeployer deploy replication 8.4.4 --with-proxysql

# 5. Connect through ProxySQL
~/sandboxes/rsandbox_8_4_4/proxysql/use_proxy -e "SELECT @@version, @@port"

# 6. Check backends
~/sandboxes/rsandbox_8_4_4/proxysql/use -e "SELECT hostgroup_id, hostname, port, status FROM mysql_servers"

# 7. Clean up when done
dbdeployer delete all

---

Prerequisites

ProxySQL Binary

dbdeployer uses a system-installed ProxySQL binary. It must be in your PATH:

# Verify ProxySQL is available
which proxysql
proxysql --version

# Check dbdeployer sees it
dbdeployer providers
# Output:
# mysql           (base port: 3306, ports per instance: 3)
# proxysql        (base port: 6032, ports per instance: 2)

If ProxySQL is not in PATH, you can add it temporarily:

export PATH=/path/to/proxysql/bin:$PATH

MySQL Binaries

MySQL tarballs must be unpacked into the sandbox binary directory (default ~/opt/mysql/):

dbdeployer unpack /path/to/mysql-8.4.4-linux-glibc2.17-x86_64.tar.xz
dbdeployer versions

Supported MySQL Versions

• MySQL 8.0.x (fully supported)
• MySQL 8.4.x LTS (fully supported, recommended)
• MySQL 9.x Innovation (fully supported)

---

Standalone ProxySQL

Deploy a ProxySQL instance without any MySQL backends:

dbdeployer deploy proxysql
# or with custom port:
dbdeployer deploy proxysql --port 16032

Options

Flag	Default	Description
--port	6032	ProxySQL admin port (mysql port = admin + 1)
--admin-user	admin	Admin interface username
--admin-password	admin	Admin interface password
--skip-start	false	Create sandbox without starting ProxySQL

Usage

# Connect to admin interface
~/sandboxes/proxysql_6032/use

# Check status
~/sandboxes/proxysql_6032/status

# Stop / Start
~/sandboxes/proxysql_6032/stop
~/sandboxes/proxysql_6032/start

---

Single MySQL + ProxySQL

Deploy a single MySQL instance with ProxySQL in front:

dbdeployer deploy single 8.4.4 --with-proxysql

This creates:

• A MySQL sandbox at ~/sandboxes/msb_8_4_4/
• A ProxySQL sandbox at ~/sandboxes/msb_8_4_4/proxysql/
• ProxySQL configured with one backend in hostgroup 0

# Connect directly to MySQL
~/sandboxes/msb_8_4_4/use -e "SELECT VERSION()"

# Connect through ProxySQL
~/sandboxes/msb_8_4_4/proxysql/use_proxy -e "SELECT VERSION()"

# ProxySQL admin
~/sandboxes/msb_8_4_4/proxysql/use -e "SELECT * FROM mysql_servers"

---

Replication + ProxySQL

Deploy a MySQL master-slave replication cluster with ProxySQL:

dbdeployer deploy replication 8.4.4 --with-proxysql

This creates:

• MySQL master + 2 slaves
• ProxySQL with topology-aware configuration:
  • Hostgroup 0: writer (master)
  • Hostgroup 1: readers (slaves)
  • Monitor user: msandbox (checks backend health)

# Check MySQL replication
~/sandboxes/rsandbox_8_4_4/check_slaves

# Check ProxySQL backends
~/sandboxes/rsandbox_8_4_4/proxysql/use -e \
  "SELECT hostgroup_id, hostname, port, status FROM mysql_servers"
# Output:
# hostgroup_id | hostname  | port  | status
# 0            | 127.0.0.1 | 19805 | ONLINE    (master)
# 1            | 127.0.0.1 | 19806 | ONLINE    (slave1)
# 1            | 127.0.0.1 | 19807 | ONLINE    (slave2)

# Connect through ProxySQL (routes to master by default)
~/sandboxes/rsandbox_8_4_4/proxysql/use_proxy -e "SELECT @@port"

# ProxySQL admin — add query rules, check stats, etc.
~/sandboxes/rsandbox_8_4_4/proxysql/use

Adding Query Rules

ProxySQL sandboxes are deployed without query rules — you configure routing yourself:

# Example: route SELECT to readers (hostgroup 1)
~/sandboxes/rsandbox_8_4_4/proxysql/use -e "
  INSERT INTO mysql_query_rules (active, match_pattern, destination_hostgroup)
  VALUES (1, '^SELECT', 1);
  LOAD MYSQL QUERY RULES TO RUNTIME;
  SAVE MYSQL QUERY RULES TO DISK;
"

---

Group Replication

Deploy a MySQL Group Replication cluster:

# Multi-primary (default)
dbdeployer deploy replication 8.4.4 --topology=group

# Single-primary
dbdeployer deploy replication 8.4.4 --topology=group --single-primary

# Check group members
~/sandboxes/group_msb_8_4_4/check_nodes

# Connect to a node
~/sandboxes/group_msb_8_4_4/n1 -e "SELECT * FROM performance_schema.replication_group_members"

---

ProxySQL Sandbox Structure

~/sandboxes/rsandbox_8_4_4/
├── master/              # MySQL master sandbox
├── node1/               # MySQL slave 1
├── node2/               # MySQL slave 2
├── proxysql/            # ProxySQL sandbox
│   ├── proxysql.cnf     # Generated configuration
│   ├── data/            # ProxySQL SQLite data directory
│   │   └── proxysql.pid # PID file (written by ProxySQL)
│   ├── start            # Start ProxySQL
│   ├── stop             # Stop ProxySQL
│   ├── status           # Check if running
│   ├── use              # Connect to admin interface
│   └── use_proxy        # Connect through ProxySQL's MySQL port
├── check_slaves         # Check replication status
├── start_all            # Start all MySQL nodes
├── stop_all             # Stop all MySQL nodes
└── ...

---

Connecting to ProxySQL

Admin Interface

The use script connects to ProxySQL’s admin port:

~/sandboxes/rsandbox_8_4_4/proxysql/use
# ProxySQL Admin>

From here you can manage backends, query rules, users, and all ProxySQL configuration.

MySQL Protocol (Through Proxy)

The use_proxy script connects through ProxySQL’s MySQL port, which routes to backends:

~/sandboxes/rsandbox_8_4_4/proxysql/use_proxy -e "SELECT @@hostname, @@port"

Manual Connection

# Admin (default port: 6032)
mysql -h 127.0.0.1 -P 6032 -u admin -padmin

# Through proxy (default port: 6033)
mysql -h 127.0.0.1 -P 6033 -u msandbox -pmsandbox

---

Configuration Details

Generated proxysql.cnf

datadir="/home/user/sandboxes/rsandbox_8_4_4/proxysql/data"

admin_variables=
{
    admin_credentials="admin:admin"
    mysql_ifaces="127.0.0.1:6032"
}

mysql_variables=
{
    interfaces="127.0.0.1:6033"
    monitor_username="msandbox"
    monitor_password="msandbox"
    monitor_connect_interval=2000
    monitor_ping_interval=2000
}

mysql_servers=
(
    { address="127.0.0.1" port=19805 hostgroup=0 max_connections=200 },
    { address="127.0.0.1" port=19806 hostgroup=1 max_connections=200 },
    { address="127.0.0.1" port=19807 hostgroup=1 max_connections=200 }
)

mysql_users=
(
    { username="msandbox" password="msandbox" default_hostgroup=0 }
)

Default Credentials

Component	User	Password	Purpose
ProxySQL Admin	admin	admin	Admin interface management
MySQL / Monitor	msandbox	msandbox	Backend connections and health monitoring
Replication	rsandbox	rsandbox	MySQL replication user

---

Topology-Aware Hostgroups

Topology	Hostgroup 0	Hostgroup 1	Monitoring
Single	1 backend	—	Basic health
Replication	Writer (master)	Readers (slaves)	read_only check
Group Replication	(configure manually)	(configure manually)	—

---

Managing Sandboxes

List Deployed Sandboxes

dbdeployer sandboxes

Delete a Specific Sandbox

dbdeployer delete rsandbox_8_4_4

ProxySQL is automatically stopped before the directory is removed.

Delete All Sandboxes

dbdeployer delete all

List Available Providers

dbdeployer providers
# mysql           (base port: 3306, ports per instance: 3)
# proxysql        (base port: 6032, ports per instance: 2)

---

Troubleshooting

”proxysql binary not found in PATH”

ProxySQL must be installed and available in your PATH:

which proxysql || echo "Not found — install ProxySQL or add to PATH"
export PATH=/path/to/proxysql:$PATH

ProxySQL fails to start

Check the data directory for errors:

ls ~/sandboxes/*/proxysql/data/
# Look for proxysql.pid — if missing, startup failed

Backends showing SHUNNED

ProxySQL detected the backend is unhealthy. Check if MySQL is running:

~/sandboxes/rsandbox_8_4_4/node1/status
~/sandboxes/rsandbox_8_4_4/node1/start  # restart if needed

Port conflicts

If deployment fails with port errors, clean up stale processes:

dbdeployer delete all
pkill -u $USER proxysql
pkill -u $USER mysqld

---

Reference

CLI Commands

dbdeployer deploy proxysql [flags]
    --port int              ProxySQL admin port (default 6032)
    --admin-user string     Admin username (default "admin")
    --admin-password string Admin password (default "admin")
    --skip-start           Don't start ProxySQL after creation

dbdeployer deploy single <version> [flags]
    --with-proxysql        Deploy ProxySQL alongside MySQL

dbdeployer deploy replication <version> [flags]
    --with-proxysql        Deploy ProxySQL alongside replication cluster
    --topology=group       Use group replication instead of master-slave
    --single-primary       Single-primary mode for group replication

dbdeployer providers
    Lists all registered providers (mysql, proxysql)

dbdeployer delete <sandbox-name>
    Deletes sandbox (stops ProxySQL automatically)

ProxySQL Sandbox Scripts

Script	Purpose
start	Start ProxySQL (waits for PID file)
stop	Stop ProxySQL (kills process and children)
status	Check if ProxySQL is running
use	Connect to admin interface via mysql client
use_proxy	Connect through ProxySQL’s MySQL port

Environment Variables

Variable	Default	Description
SANDBOX_HOME	~/sandboxes	Where sandboxes are created
SANDBOX_BINARY	~/opt/mysql	Where MySQL binaries are stored