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.
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.
Rather than using a production set up, where each instance runs
on a separate host, AdminAPI provides the
dba.deploySandboxInstance(
operation. The port_number
)port_number
argument
is the TCP port number where the MySQL Server instance listens
for connections. To deploy a new sandbox instance which is bound
to port 3310, issue:
mysql-js> dba.deploySandboxInstance(3310)
By default the sandbox is created in a directory named
$HOME/mysql-sandboxes/
on Unix systems. For Microsoft Windows systems the directory is
port
%userprofile%\MySQL\mysql-sandboxes\
.
Each sandbox instance is stored in a directory named after the
port
port_number
.
The root user's password for the instance is prompted for.
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.
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/
issue:
PATH=/home/user/mysql-latest/bin/:$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.
The following options are supported by the
dba.deploySandboxInstance()
operation:
allowRootFrom
configures which host the root user can connect from. Defaults toroot@%
.ignoreSslError
configures secure connections on the sandbox instance. WhenignoreSslError
is true, which is the default, no error is issued during the operation if SSL support cannot be provided and the server instance is deployed without SSL support. WhenignoreSslError
is set to false, the sandbox instance is deployed with SSL support, issuing an error if SSL support cannot be configured.mysqldOptions
configures additional options on the sandbox instance. Defaults to an empty string, and accepts a list of strings that specify options and values. For examplemysqldOptions: ["lower_case_table_names=1", "report_host="10.1.2.3"]}
. The specified options are written to the sandbox instance's option file.portX
configures the port used for X Protocol connections. The default is calculated by multiplying theport
value by 10. The value is an integer between 1024 and 65535.
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(
. This stops the instance gracefully, unlikeinstance
)dba.killSandboxInstance(
.instance
)To start a sandbox instance use
dba.startSandboxInstance(
.instance
)To kill a sandbox instance use
dba.killSandboxInstance(
. This stops the instance without gracefully stopping it and is useful in simulating unexpected halts.instance
)To delete a sandbox instance use
dba.deleteSandboxInstance(
. This completely removes the sandbox instance from your file system.instance
)