MySQL::Sandbox - Quickly installs MySQL side server, either standalone or in groups
make_sandbox /path/to/MySQL-VERSION.tar.gz
This package is a sandbox for testing features under any version of MySQL from 3.23 to 6.0.
It will install one node under your home directory, and it will provide some useful commands to start, use and stop this sandbox.
With this package you can play with new MySQL releases without need of using other computers. The server installed in the sandbox use non-standard data directory, ports and sockets, so they won't interfere with existing MYSQL installations.
MySQL Sandbox installs as a normal Perl Module. Since its purpose is to install side servers in user space, you can install it as root (default) or as an unprivileged user. In this case, you need to set the PERL5LIB and PATH variables.
# as root perl Makefile.PL make make test make install # as normal user export PATH=$HOME/usr/local/bin:$PATH export PERL5LIB=$HOME/usr/local/lib/perl5/site_perl/5.8.8 perl Makefile.PL PREFIX=$HOME/usr/local make make test make install
The easiest way to make a sandbox is
$ make_sandbox /path/to/mysql-X.X.XX-osinfo.tar.gz
That's all it takes to get started. The Sandbox will ask you for confirmation, and then it will tell you where it has installed your server.
By default, the sandbox creates a new instance for you under
$SANDBOX_HOME/msb_X_X_XX
It's as easy as making a single sandbox
$ make_replication_sandbox /path/to/mysql-X.X.XX-osinfo.tar.gz
This will create a new instance of one master and two slaves
under $SANDBOX_HOME/rsandbox_X_X_XX
It requires an appropriate option when you start a replication sandbox
$ make_replication_sandbox --circular=4 /path/to/mysql-X.X.XX-osinfo.tar.gz
This will create a replication system with three servers connected by circular replication. A handy shortcut is --master_master, which will create a circular replication system of exactly two members.
--master_master
You can create a group of sandboxes without any replication among its members. If you need three servers of the same version, you can use
$ make_multiple_sandbox /path/to/tarball
If you need servers of different versions in the same group, you may like
$ make_multiple_custom_sandbox /path/to/tarball1 path/to/tarball2 /path/to/tb3
Assuming that each tarball is from a different version, you will group three servers under one directory, with the handy sandbox scripts to manipulate them.
If you want to create a sandbox from the code that you have just compiled, but you don't want to install, there is a script that makesa binary tarball for you and installs a sandbox in one go.
$ make_sandbox_from_source {SOURCE_DIRECTORY} {sandbox_type} [options]
The first parameters is the directory where you have successfully run "./configure && make". The second parameter is what kind of sandbox you want to create: One of the following:
* single * multiple * replication * circular
You can then add all the options you need at the end. For example:
$ make_sandbox_from_source $HOME/build/5.0 single --export_binaries --check_port
or
$ make_sandbox_from_source $HOME/build/5.0 replication --how_many_slaves=5
If you call this program several times from the same directory, it will check if the compiled binaries are newer than the extracted ones, and if they aren't, it will reuse the ones created during the previous run, thus saving time and CPU.
If you use sandboxes often, instead of pointing to a tarball you can set a directory containing expanded tarballs. By default, the sandbox looks under $HOME/opt/mysql and /opt/mysql
The expanded tarballs must be named with the full version. e.g.
$HOME/opt/mysql/5.0.64 /opt/mysql/5.1.24
If you have such an organization, then you can invoke every sandbox script with this abridged syntax:
make_sandbox 5.0.64 make_replication_sandbox 5.1.25 make_multiple_custom_sandbox 5.0.64 5.1.25
If you use some options frequently, it would make sense to add them to the default option file, which is $HOME/.msandboxrc
Every sandbox script will give you additional information if you invoke it with the "--help" option.
When creating a single sandbox, you can pass to the new server most any option that can be used in a my.cnf file, in addition to specific sandbox options.
Multiple and replication sandboxes, for example, accept a --how_many_slaves=X or --how_many_nodes=X option, allowing you to create very large groups.
Unless you override the defaults, sandboxes are created inside a directory that servers two purposes:
further isolates the sandboxes, and keep them under easy control if you are in the habit of creating many of them;
provides a set of handy super-commands, which can be passed to all the sandboxes. Running "$SANDBOX_HOME/stop_all" you will stop all servers of all sandboxes, single or groups, below that directory.
Change directory to the newly created one (default: $SANDBOX_HOME/msb_VERSION for single sandboxes)
The sandbox directory of the instance you just created contains some handy scripts to manage your server easily and in isolation.
There are 2 database users installed by default:
+-----------------+-------------+-------------------------------+ | user name | password | privileges | +-----------------+-------------+-------------------------------+ | root@localhost | msandbox | all on *.* with grant option | | msandbox@% | msandbox | all on *.* | +-----------------+-------------+-------------------------------+
Ports are created from the server version. a 5.1.25 server will use port 5125, unless you override the default. Replicated and group sandboxes add a delta number to the version figure, to avoid clashing with single installations.
(note: ports can be overriden using -P option during install)
+--------+-----------------------------+ | port | socket | +--------+-----------------------------+ | 3310 | /tmp/mysql_sandbox3310.sock | +--------+-----------------------------+
All programs in the Sandbox suite recognize and uses the following variables:
* HOME the user's home directory * SANDBOX_HOME the place where the sandboxes are going to be built. ($HOME/sandboxes by default) * USER the operating system user * PATH the execution path * SBDEBUG if set, the programs will print debugging messages
In addition to the above, make_sandbox will use * SANDBOX_BINARY or BINARY_BASE the directory containing the installation server binaries
make_replication_sandbox will recognize the following * MASTER_OPTIONS additional options to be passed to the master * SLAVE_OPTIONS additional options to be passed to each slave * NODE_OPTIONS additional options to be passed to each node
The latter is also recognized by make_multiple_custom_sandbox and make_multiple_sandbox
The test suite, test_sandbox, recognizes two environment variables
test_sandbox
* TEST_SANDBOX_HOME, which sets the path where the sandboxes are installed, if the default $HOME/test_sb is not suitable. It is used when you test the package with 'make test' * PRESERVE_TESTS. If set, this variable prevents the removal of test sandboxes created by test_sandbox. It is useful to inspect sandboxes if a test fails.
The Sandbox Helper, sbtool, is a tool that allows administrative operations on already existing sandboxes. It does a number of important tasks that are not available at creation time or that would require too much manual labor.
sbtool
usage: sbtool [options] -o --operation (s) <> - what task to perform 'info' returns configuration options from a Sandbox 'copy' copies data from one Sandbox to another 'ports' lists ports used by the Sandbox 'tree' creates a replication tree 'move' moves a Sandbox to a different location 'range' finds N consecutive ports not yet used by the Sandbox 'port' Changes a Sandbox port 'delete' removes a sandbox completely 'preserve' makes a sandbox permanent 'unpreserve' makes a sandbox NOT permanent -s --source_dir (s) <> - source directory for move,copy -d --dest_dir (s) <> - destination directory for move,copy -n --new_port (s) <> - new port while moving a sandbox -u --only_used (-) <> - for "ports" operation, shows only the used ones -i --min_range (i) <5000> - minimum port when searching for available ranges -x --max_range (i) <64000> - maximum port when searching for available ranges -z --range_size (i) <10> - size of range when searching for available port range -f --format (s) <text> - format for "ports" and "info" 'perl' fully structured information in Perl code 'text' plain text dump of requested information -p --search_path (s) </Users/gmax/sandboxes> - search path for ports and info -a --all_info (-) <> - print more info for "ports" operation --tree_nodes (s) <> - description of the tree (x-x x x-x x|x x x|x x) --mid_nodes (s) <> - description of the middle nodes (x x x) --leaf_nodes (s) <> - description of the leaf nodes (x x|x x x|x x) --tree_dir (s) <> - which directory contains the tree nodes -v --verbose (-) <> - prints more info on some operations -h --help (-) <1> - this screen
Returns configuration options from a Sandbox (if specified) or from all sandboxes under $SANDBOX_HOME (default). You can use --search_path to tell sbtool where to start. The return information is formatted as a Perl structure.
--search_path
Lists ports used by the Sandbox. Use --search_path to tell sbtool where to start looking (default is $SANDBOX_HOME). You can also use the --format option to influence the outcome. Currently supported are only 'text' and 'perl'. If you add the --only_used option, sbtool will return only the ports that are currently open.
--format
--only_used
Finds N consecutive ports not yet used by the Sandbox. It uses the same options used with 'ports' and 'info'. Additionally, you can define the low and high boundaries by means of --min_range and --max_range. The size of range to search is 10 ports by default. It can be changed with --range_size.
--min_range
--max_range
--range_size
Changes port to an existing Sandbox. This requires the options --source_dir and --new_port to complete the task. If the sandbox is running, it will be stopped.
--source_dir
--new_port
Copies data from one Sandbox to another. It only works on single sandboxes. It requires the --source_dir and --dest_dir options to complete the task. Both Source and destination directory must be already installed sandboxes. If any of them is still running, it will be stopped. If both source and destination directory point to the same directory, the command is not performed. At the end of the operation, all the data in the source sandbox is copied to the destination sandbox. Existing files will be overwritten. It is advisable, but not required, to run a "./clear" command on the destination directory before performing this task.
--dest_dir
Moves a Sandbox to a different location. Unlike 'copy', this operation acts on the whole sandbox, and can move both single and multiple sandboxes. It requires the --source_dir and --dest_dir options to complete the task. If the destination directory already exists, the task is not performed. If the source sandbox is running, it will be stopped before performing the operation. After the move, all paths used in the sandbox scripts will be changed.
Creates a replication tree, with one master, one or more intermediate level slaves, and one or more leaf node slaves for each intermediate level. To create the tree, you need to create a multiple nodes sandbox (using make_multiple_sandbox) and then use sbtool with the following options:
make_multiple_sandbox
* --tree_dir , containing the sandbox to convert to a tree * --master_node, containing the node that will be master * --mid_nodes, with a list of nodes for the intermediate level * --leaf_nodes, with as many lists as how many mid_nodes Each list is separated from the next by a pipe sign (|).
Alternatively, you can use the --tree_nodes option to describe all the tree at once.
--tree_nodes
For example, in a sandbox with 8 nodes, to define 1 as master node, nodes 2 and 3 as middle nodes, nodes 4, 5, and 6 as slaves of node 2 and nodes 7 and 8 as slaves of node 3, you can use either of the following:
sbtool --tree_dir=/path/to/source \ --master_node=1 \ --mid_nodes='2 3' --leaf_nodes='4 5 6|7 8' sbtool --tree_dir=/path/to/source \ --tree_nodes='1 - 2 3 - 4 5 6|7 8'
Makes a sandbox permanent. It requires the --source_dir option to complete the task. This command changes the 'clear' command within the requested sandbox, disabling its effects. The sandbox can't be erased using 'clear' or 'clear_all'. The 'delete' operation of sbtool will skip a sandbox that has been made permanent.
Makes a sandbox NOT permanent. It requires the --source_dir option to complete the task. This command cancels the changes made by a 'preserve' operation, making a sandbox erasable with the 'clear' command. The 'delete' operation can be performed successfully on an unpreserved sandbox.
Removes a sandbox completely. It requires the --source_dir option to complete the task. The requested sandbox will be stopped and then deleted completely. WARNING! No confirmation is asked!
The MySQL Sandbox comes with a test suite, called test_sandbox, which by default tests single,replicated, multiple, and custom installations of MySQL version 5.0.77 and 5.1.32.You can override the version being tested by means of command line options:
test_sandbox --versions=5.0.67,5.1.30
or you can specify a tarball
test_sandbox --versions=/path/to/mysql-tarball-5.1.31.tar.gz test_sandbox --tarball=/path/to/mysql-tarball-5.1.31.tar.gz
You can also define which tests you want to run:
test_sandbox --tests=single,replication
The tests are not performed in the common $SANDBOX_HOME directory, but on a separate directory, which by default is $HOME/test_sb. To avoid interferences, before the tests start, the application runs the $SANDBOX_HOME/stop_all command. The test directory is considered to exist purely for testing purposes, and it is erased several times while running the suite. Using this directory to store valuable data is higly risky.
$SANDBOX_HOME
$HOME/test_sb
$SANDBOX_HOME/stop_all
When you build the package and run
make test
test_sandbox is called, and the tests are performed on a temporary directory under $INSTALLATION_DIRECTORY/t/test_sb. By default, version 5.0.77 is used. If this version is not found in $HOME/opt/mysql/, the test is skipped. You can override this option by setting the TEST_VERSION environment variable.
$INSTALLATION_DIRECTORY/t/test_sb
$HOME/opt/mysql/
TEST_VERSION=5.1.30 make test TEST_VERSION=$HOME/opt/mysql/5.1.30 make test TEST_VERSION=/path/to/myswl-tarball-5.1.30.tar.gz make test
To use this package you need at least the following:
Linux or Mac OSX operating system (it may work in other *NIX OSs, but has not been tested)
a binary tarball of MySQL 3.23 or later
Perl 5.8.1 or later (for installation only)
bash shell
Copyright (C) 2006,2007,2008,2009 Giuseppe Maxia
Home Page http://launchpad.net/mysql-sandbox/
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
To install MySQL::Sandbox, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MySQL::Sandbox
CPAN shell
perl -MCPAN -e shell install MySQL::Sandbox
For more information on module installation, please visit the detailed CPAN module installation guide.