6.5 AdminAPI MySQL Sandboxes

This section explains how to set up a sandbox deployment with AdminAPI. Initially deploying and using local sandbox instances of MySQL is a good way to start your exploration of AdminAPI. You can fully test out the functionality locally, prior to deployment on your production servers. AdminAPI has built-in functionality for creating sandbox instances that are correctly configured to work with InnoDB Cluster and InnoDB ReplicaSet in a locally deployed scenario.

Important

Sandbox instances are only suitable for deploying and running on your local machine for testing purposes. In a production environment the MySQL Server instances are deployed to various host machines on the network. See Section 6.2.2, “Deploying a Production InnoDB Cluster” for more information.

Unlike a production deployment, where you work with instances and specify them by a connection string, sandbox instances run locally on the same machine as which you are running MySQL Shell. Therefore, to specify a sandbox instance you supply the port number which the MySQL sandbox instance is listening on.

Deploying Sandbox Instances

The MySQL AdminAPI adds the dba global variable to MySQL Shell, which provides functions for administration of sandbox instances. In this example setup, you create three sandbox instances using dba.deploySandboxInstance(port_number). To deploy a new sandbox instance which is bound to port 3310, issue:

mysql-js> dba.deploySandboxInstance(3310)

The argument passed to deploySandboxInstance() is the TCP port number where the MySQL Server instance listens for connections. By default the sandbox is created in a directory named $HOME/mysql-sandboxes/port on Unix systems. For Microsoft Windows systems the directory is %userprofile%\MySQL\mysql-sandboxes\port.

The root user's password for the instance is prompted for.

Important

Each sandbox instance uses the root user and password, and it must be the same on all sandbox instances which should work together. This is not recommended in production.

To deploy another sandbox server instance, repeat the steps followed for the sandbox instance at port 3310, choosing different port numbers for each instance. For each additional sandbox instance issue:

mysql-js> dba.deploySandboxInstance(port_number)

To follow this tutorial, use port numbers 3310, 3320 and 3330 for the three sandbox server instances. Issue:

mysql-js> dba.deploySandboxInstance(3320)
mysql-js> dba.deploySandboxInstance(3330)

To change the directory which sandboxes are stored in, for example to run multiple sandboxes on one host for testing purposes, use the MySQL Shell sandboxDir option. For example to use a sandbox in the /home/user/sandbox1 directory, issue:

mysql-js> shell.options.sandboxDir='/home/user/sandbox1'

All subsequent sandbox related operations are then executed against the instances found at /home/user/sandbox1.

When you deploy sandboxes, MySQL Shell searches for the mysqld binary which it then uses to create the sandbox instance. You can configure where MySQL Shell searches for the mysqld binary by configuring the PATH environment variable. This can be useful to test a new version of MySQL locally before deploying it to production. For example, to use a mysqld binary at the path /home/user/mysql-latest/bin/mysqld issue:

PATH=/home/user/mysql-latest/bin/mysqld:$PATH

Then run MySQL Shell from the terminal where the PATH environment variable is set. Any sandboxes you deploy then use the mysqld binary found at the configured path.

Managing Sandbox Instances

Once a sandbox instance is running, it is possible to change its status at any time using the following:

To stop a sandbox instance use dba.stopSandboxInstance(instance). This stops the instance gracefully, unlike dba.killSandboxInstance(instance).
To start a sandbox instance use dba.startSandboxInstance(instance).
To kill a sandbox instance use dba.killSandboxInstance(instance). This stops the instance without gracefully stopping it and is useful in simulating unexpected halts.
To delete a sandbox instance use dba.deleteSandboxInstance(instance). This completely removes the sandbox instance from your file system.