Using Mysos

Mysos provides a REST API for creating and managing MySQL clusters on Mesos.


  • HTTP Method: GET
  • Path: /

The root of API endpoint is a web page that lists the managed MySQL clusters.

Creating a MySQL cluster

  • HTTP Method: POST
  • Path: /clusters/<cluster_name>


  • cluster_name: Name of the cluster.
  • cluster_user: The user account for all MySQL instances in the cluster which as full admin privileges.
  • num_nodes: Number of nodes in the cluster. [default: 3]
  • backup_id: An ID for the MySQL backup to restore from when the MySQL instance starts. If not specified, Mysos will start an empty MySQL instance. The format and meaning of backup_id is specific to the implementation of BackupStore that the Mysos cluster uses.

cluster_name is part of the path and the rest of the parameters are specified as form fields.


A JSON object with the following fields:

  • cluster_password: The password for accessing the MySQL instance (associated with cluster_user).
  • cluster_url: A URL to the ZooKeeper group for discovering the MySQL instances of this cluster. See the Service Discovery section below.


# Create a cluster named 'test_cluster3' and restore from the backup 'foo/bar:201503122000'.
curl -X POST --form "cluster_user=mysos" --form "num_nodes=2" --form "num_nodes=2" --form "backup_id=foo/bar:201503122000"
# Response
{"cluster_password": "w9gMCkecsMh6sWsRdxNTa", "cluster_url": "zk://mysos:mysos@"}


  • Cluster creation is asynchronous. The API call returns (with status 200) as soon as the Mysos scheduler has accepted the request. The same goes for cluster deletion.
  • ZooKeeper <cluster_url>/master sub-group has at most one ZNode which is the master of the MySQL cluster.
  • ZooKeeper <cluster_url>/slaves sub-group can have multiple ZNodes which are the slaves of the MySQL cluster.
  • A ZNode is added to the ZooKeeper group when the instance becomes available and ready to serve traffic.

Removing a MySQL cluster

  • HTTP Method: DELETE
  • Path: /clusters/<cluster_name>


  • cluster_name: Name of the cluster.
  • password: The password for the cluster returned by cluster creation call.


A JSON object with:

  • cluster_url: A URL to the ZooKeeper group to watch for the termination of the cluster. The group ZNode is removed from ZooKeeper when the MySQL cluster is removed/terminated.


# Remove a cluster named 'test_cluster3'
curl -X DELETE --form "password=w9gMCkecsMh6sWsRdxNTa"
# Response
{"cluster_url": "zk://mysos:mysos@"}

Service Discovery

Mysos' service discovery with ZooKeeper conforms to the ServerSet protocol. Each MySQL instance is represented by a ZNode with its data being a ServiceInstance serialized into JSON.

  • The Endpoint serviceEndpoint field in ServiceInstance has the host and port that MySQL client can connect to.
  • Some utilities for watching ZooKeeper and parsing the ServiceInstances: Java src | Maven, Python src | PyPI.