#!/usr/bin/perl
use strict;
use warnings;

use English qw( -no_match_vars ); 
use Data::Dumper;
use MySQL::Sandbox;

my $DEBUG = $MySQL::Sandbox::DEBUG;

#my $install_dir;
#$install_dir = $PROGRAM_NAME;
#$install_dir =~ s{/\w+(\.pl)?$}{};

my $msb = MySQL::Sandbox->new();

my @apps = (
        { 
            name => 'make_sandbox',
            description  => 'the easiest way of creating a sandbox',
        },
        {
            name => 'low_level_make_sandbox', 
            description => q{create a single sandbox, with fine tuning options (don't use directly)},
        },
        {
            name    => 'make_replication_sandbox',
            description  => 'creates a sandbox with replicated master and slaves or circular',
        },
        {
            name    => 'make_multiple_sandbox',
            description => 'creates a group of sandboxes with the same version',
        },
        {
            name => 'make_multiple_custom_sandbox',
            description  => 'create a group of sandboxes with different versions',
        }
);

my $choice = shift
    or help();
if (grep {$choice eq $_->{name} } @apps ) { 
    my $application = "$choice";
    if ( -x $application) {    
        exec $application, @ARGV;
    }
    else {
        die "application $application not found\n";
    }
}
else {
    exec "perldoc $0";
    #die "'$choice' is not an application in MySQL Sandbox\n";
}

sub help {
    print $msb->credits(); 
    print "available applications:\n";
    for my $app (@apps) {
        printf " %-30s: %s\n", $app->{'name'}, $app->{'description'};
    }
    exit(1);
}

__END__

=head1 The MySQL Sandbox

=head1 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.

=head1 MAKING SANDBOXES

=head2 SINGLE SERVER SANDBOX

The easiest way to make a sandbox is 

=over 3

=item 1
download the sandbox package and expand it somewhere

=item 2
download a MySQL binary tarball

=item 3
run this command
   $ ./make_sandbox  /path/to/mysql-X.X.XX-osinfo.tar.gz

=back

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


=head2 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

=head2 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 C(--master_master), which will create a circular replication system of exactly two members.

=head2 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.

=head2 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

=head2 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.

=head2 SANDBOX HOME

Unless you override the defaults, sandboxes are created inside a 
directory that servers two purposes:

=over 3

=item *
further isolates the sandboxes, and keep them under easy control if you are in the habit of creating many of them;

=item *
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.

=back

=head1 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.
 
=over 3

=item start

=item restart

=item stop
"./start", "./restart", and "./stop" do what their name suggests.

=item use
"./use" calls the command line client with the appropriate parameters,

=item clear
"./clear" stops the server and removes everything from the data directory, letting you ready to start from scratch.

=item 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)

=over 3

=item start_all

=item stop_all

=item use_all

=item clear_all

=item m

=item s1,s2

=back

=back

=head2 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 *.*                    |
 +-----------------+-------------+-------------------------------+

=head2 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 |
 +--------+-----------------------------+

=head2 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

=head1 REQUIREMENTS

To use this package you need at least the following:

=over 3

=item *
Linux or Mac OSX operating system (it may work in other *NIX OSs, but has not been tested)

=item *
a bynary tarball of MySQL 3.23 or later

=item *
Perl 5.8.1 or later (for installation only)

=item *
bash shell

=back


=head1 COPYRIGHT
version 2.0

Copyright © 2006,2007,2008 Giuseppe Maxia
Home Page  http://launchpad.net/mysql-sandbox/


=head1 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
