MySQL Proxy

MySQL for Pivotal Cloud Foundry (PCF) uses the Switchboard router to proxy TCP connections to healthy MariaDB nodes.

Using a proxy gracefully handles failure of MariaDB nodes, enabling fast, unambiguous failover to other server nodes within the cluster. When a server node becomes unhealthy, the proxy closes all connections to the unhealthy node and re-routes all subsequent connections to a healthy server node.

On-demand versions of MySQL for PCF do not use proxies.

Switchboard offers three separate functions, for which it uses three separate ports. The default ports are documented, along with all other network port requirements, on the installation page.

  • MySQL Server Access

    MySQL clients communicate with the MySQL servers through this network port. Do not configure any load balancer to check Proxy health via this port; these connections will be automatically passed through to the MySQL servers.

  • Proxy Health

    Switchboard listens for connections on Port 1936. When using a load balancer to balance across multiple instances of Switchboard, configure the load balancer to test for health by connecting to port 1936. To support different kinds of load balancers, Switchboard supports simple TCP connection checks and HTTP requests. HTTP connections are not authenticated, and require no special load balancer configuration.

  • Proxy Dashboard and API

    Operators can connect to Switchboard to view the state of the cluster back-ends. Read either the Dashboard or API documentation for more information.

Node Health

When determining where to route traffic, the proxy queries an HTTP healthcheck process running on the database node VM. This healthcheck can return as either healthy or unhealthy, or the node can be unresponsive.


If the healthcheck process returns HTTP status code 200, the proxy includes the node in its pool of healthy nodes.

When a new or resurrected nodes rejoin the cluster, the proxy continues to route all connections to the currently active node. In the case of failover, the proxy considers all healthy nodes as candidates for new connections.


If the healthcheck returns HTTP status code 503, the proxy considers the node unhealthy.

This happens when a node becomes non-primary, as specified by the cluster behavior section of the Architecture topic.

The proxy severs existing connections to newly unhealthy node. The proxy routes new connections to a healthy node, assuming such a node exists. Clients are expected to handle reconnecting on connection failure should the entire cluster become inaccessible.


If node health cannot be determined due to an unreachable or unresponsive healthcheck endpoint, the proxy considers the node unhealthy. This may happen if there is a network partition or if the VM running the MariaDB node and healthcheck died.

Proxy Count

If the operator sets the total number of proxy hosts to 0 in OpsManager or BOSH deployment manifest, apps connect directly to one MariaDB server node. This makes that node a single point of failure (SPOF) for the cluster.

For high-availability, Pivotal recommends running two proxies, which provides redundancy should one of the proxies fail.

Proxy Dashboard

The service provides a dashboard where administrators can observe health and metrics for each proxy instance. Metrics include the number of client connections routed to each backend database cluster node.

From a browser, you can open the dashboard for each proxy instance at: http://JOB-INDEX-proxy-p-mysql.SYSTEM-DOMAIN. The job index starts at 0. For example, if you have two proxy instances deployed and your system domain is, you would access your proxy instance dashboards would at:

Note: Earlier versions of MySQL for PCF use a different hostname format for the proxies, in the form: http://proxy-JOB-INDEX-p-mysql.SYSTEM-DOMAIN
For example:

You need basic auth credentials to access these dashboards. You can find them in the Credentials tab of the MySQL for PCF tile in Ops Manager.


The proxy hosts a JSON API at JOB-INDEX-proxy-p-mysql.SYSTEM-DOMAIN/v0/.

The API provides the following route:


  • Method: GET
  • Path: /v0/backends
  • Params: ~
  • Headers: Basic Auth


    "name": "mysql-0",
    "ip": "",
    "healthy": true,
    "active": true,
    "currentSessionCount": 2
    "name": "mysql-1",
    "ip": "",
    "healthy": false,
    "active": false,
    "currentSessionCount": 0
    "name": "mysql-2",
    "ip": "",
    "healthy": true,
    "active": false,
    "currentSessionCount": 0
Create a pull request or raise an issue on the source for this page in GitHub