The MySQL Sandbox

PURPOSE

   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.

INSTALLATION
   MySQL Sandbox installs as a normal Perl Module. Since its purpose is to
   install side servers in user space, you can install it as roo (default) 
   or as an unprivileged user. in this case, you need to set the PERL5LIB 
   variable.

   # as root
   perl Makefile.PL 
   make
   make test
   make install

   # as normal user
   export PERL5LIB=$HOME/usr/local/lib/perl5/site_perl/5.8.8
   perl Makefile.PL PREFIX=$HOME/usr/local
   make
   make test
   make install


MAKING SANDBOXES

SINGLE SERVER SANDBOX

   The easiest way to make a sandbox is

    1. download the sandbox package and expand it somewhere
    2. download a MySQL binary tarball
    3. run this command

$ 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
   $HOME/sandboxes/msb_X_X_XX

MAKING A REPLICATION SANDBOX

   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
   $HOME/sandboxes/rsandbox_X_X_XX

CIRCULAR REPLICATION

    It requires an appropriate option when you start a replication sandbox

      $ make_replication_sandbox --topology=circular /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.

  MULTIPLE SANDBOXES
    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.

  DEFAULTS AND SHORTCUTS
    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

  FINE TUNING
    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.

  SANDBOX HOME
    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 "$HOME/sandboxes/stop_all" you will stop all servers
    of all sandboxes, single or groups, below that directory.

USING A SANDBOX
    Change directory to the newly created one (default:
    $HOME/sandboxes/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.

    start
    restart
    stop "./start", "./restart", and "./stop" do what their name suggests.
    use "./use" calls the command line client with the appropriate
    parameters,
    clear "./clear" stops the server and removes everything from the data
    directory, letting you ready to start from scratch.
    multiple server sandbox On a replication sandbox, you have the same
    commands, with a "_all" suffix, meaning that you propagate the command
    to all the members. Then you have "./m" as a shortcut to use the master,
    "./s1" and "./s2" to access the slaves (and "s3", "s4" ... if you define
    more)

       start_all
       stop_all
       use_all
       clear_all
       m
       s1,s2

  DATABASE USERS
    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 AND SOCKETS
    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 |
     +--------+-----------------------------+

  ENVIRONMENT VARIABLES
    All programs in the Sandbox suite recognize and uses the following
    variables:

     * HOME the user's home directory
     * USER the operating system user
     * PATH the execution path
     * DEBUG if set, the programs will print debugging messages

    In addition to the above, make_sandbox will use * 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

REQUIREMENTS
    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
version 2.0
    Copyright © 2006,2007,2008 Giuseppe Maxia Home Page
    http://launchpad.net/mysql-sandbox/

LEGAL NOTICE
    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