|
| 1 | +# ProxySQL Failover Hooks |
| 2 | + |
| 3 | +Orchestrator has built-in support for updating [ProxySQL](https://proxysql.com) hostgroups during failover. When configured, orchestrator will automatically: |
| 4 | + |
| 5 | +1. **Before failover:** Drain the old master in ProxySQL (set `OFFLINE_SOFT` or `weight=0`) |
| 6 | +2. **After failover:** Update ProxySQL hostgroups to route traffic to the new master |
| 7 | + |
| 8 | +No custom scripts needed — orchestrator + ProxySQL works out of the box. |
| 9 | + |
| 10 | +## Configuration |
| 11 | + |
| 12 | +Add these settings to your `orchestrator.conf.json`: |
| 13 | + |
| 14 | +```json |
| 15 | +{ |
| 16 | + "ProxySQLAdminAddress": "127.0.0.1", |
| 17 | + "ProxySQLAdminPort": 6032, |
| 18 | + "ProxySQLAdminUser": "admin", |
| 19 | + "ProxySQLAdminPassword": "admin", |
| 20 | + "ProxySQLWriterHostgroup": 10, |
| 21 | + "ProxySQLReaderHostgroup": 20, |
| 22 | + "ProxySQLPreFailoverAction": "offline_soft" |
| 23 | +} |
| 24 | +``` |
| 25 | + |
| 26 | +### Settings |
| 27 | + |
| 28 | +| Setting | Default | Description | |
| 29 | +|---------|---------|-------------| |
| 30 | +| `ProxySQLAdminAddress` | (empty) | ProxySQL Admin host. Leave empty to disable hooks. | |
| 31 | +| `ProxySQLAdminPort` | 6032 | ProxySQL Admin port | |
| 32 | +| `ProxySQLAdminUser` | admin | Admin interface username | |
| 33 | +| `ProxySQLAdminPassword` | (empty) | Admin interface password | |
| 34 | +| `ProxySQLAdminUseTLS` | false | Use TLS for Admin connection | |
| 35 | +| `ProxySQLWriterHostgroup` | 0 | Writer hostgroup ID. Must be > 0 to enable hooks. | |
| 36 | +| `ProxySQLReaderHostgroup` | 0 | Reader hostgroup ID. Optional. | |
| 37 | +| `ProxySQLPreFailoverAction` | offline_soft | Pre-failover action: `offline_soft`, `weight_zero`, or `none` | |
| 38 | + |
| 39 | +## How It Works |
| 40 | + |
| 41 | +### Pre-Failover |
| 42 | + |
| 43 | +When orchestrator detects a dead master and begins recovery: |
| 44 | + |
| 45 | +- **`offline_soft`**: Sets the old master's status to `OFFLINE_SOFT` in ProxySQL. Existing connections are allowed to complete, but no new connections are routed to it. |
| 46 | +- **`weight_zero`**: Sets the old master's weight to 0. Similar effect but preserves the server entry's status. |
| 47 | +- **`none`**: Skips pre-failover ProxySQL update. |
| 48 | + |
| 49 | +### Post-Failover |
| 50 | + |
| 51 | +After a new master is promoted: |
| 52 | + |
| 53 | +1. Old master is removed from the writer hostgroup |
| 54 | +2. New master is added to the writer hostgroup |
| 55 | +3. If reader hostgroup is configured: new master is removed from readers |
| 56 | +4. If reader hostgroup is configured: old master is added to the reader hostgroup as `OFFLINE_SOFT` |
| 57 | +5. `LOAD MYSQL SERVERS TO RUNTIME` is executed to apply changes immediately |
| 58 | +6. `SAVE MYSQL SERVERS TO DISK` is executed to persist changes |
| 59 | + |
| 60 | +### Failover Timeline |
| 61 | + |
| 62 | +```text |
| 63 | +Dead master detected |
| 64 | + → OnFailureDetectionProcesses (scripts) |
| 65 | + → PreFailoverProcesses (scripts) |
| 66 | + → ProxySQL pre-failover: drain old master ← NEW |
| 67 | + → [topology manipulation: elect new master] |
| 68 | + → KV store updates (Consul/ZK) |
| 69 | + → ProxySQL post-failover: promote new master ← NEW |
| 70 | + → PostMasterFailoverProcesses (scripts) |
| 71 | + → PostFailoverProcesses (scripts) |
| 72 | +``` |
| 73 | + |
| 74 | +ProxySQL hooks run **alongside** existing script-based hooks — they don't replace `PreFailoverProcesses` or `PostFailoverProcesses`. |
| 75 | + |
| 76 | +## CLI Commands |
| 77 | + |
| 78 | +### Test connectivity |
| 79 | + |
| 80 | +```bash |
| 81 | +orchestrator-client -c proxysql-test |
| 82 | +``` |
| 83 | + |
| 84 | +### Show ProxySQL server list |
| 85 | + |
| 86 | +```bash |
| 87 | +orchestrator-client -c proxysql-servers |
| 88 | +``` |
| 89 | + |
| 90 | +## Multiple ProxySQL Instances |
| 91 | + |
| 92 | +For ProxySQL Cluster deployments, configure orchestrator to connect to **one** ProxySQL node. Changes propagate automatically across the cluster via ProxySQL's built-in cluster synchronization (`proxysql_servers` table). |
| 93 | + |
| 94 | +If not using ProxySQL Cluster, you can run multiple orchestrator hook configurations by setting up a ProxySQL load balancer, or by using the existing `PostMasterFailoverProcesses` script hooks for additional ProxySQL instances. |
| 95 | + |
| 96 | +## Interaction with Existing Hooks |
| 97 | + |
| 98 | +ProxySQL hooks are **non-blocking** during pre-failover: if ProxySQL is unreachable, the failover proceeds normally. Post-failover errors are logged but do not mark the recovery as failed. |
| 99 | + |
| 100 | +This ensures that a ProxySQL outage never prevents MySQL failover from completing. |
0 commit comments