MySQL:...Recipes(3pm)

✨ NAME ✨

MySQL::Sandbox::Recipes — a cookbook for MySQL Sandbox 🍓

(yes bestie, we're in the User Contributed Perl Documentation corner of the man pages, this is the MySQL::Sandbox::Recipes(3pm) page, and it's giving recipe book 💅)

🎀 PURPOSE 🎀

okay so this package is literally a collection of HOW-TO brief tutorials and recipes for MySQL Sandbox. that's the whole vibe. it's a cookbook. no cap. 👑

---

🧚 Installing MySQL::Sandbox 🧚

every single recipe in here needs the MySQL Sandbox (it lives at http://launchpad.net/mysql-sandbox). so like, you have to install it to be able to follow these recipes. for a general description of the application, go look at MySQL::Sandbox. also there's a presentation about it at Slideshare (http://www.slideshare.net/datacharmer/mysql-sandbox-3) if you wanna vibe with that 🔥

💖 the easy way - as root 💖

this is so easy that honestly the author is almost ashamed to show it. whatever, here goes:

$ sudo su -
# cpan MySQL::Sandbox

🌸 the ambitious way - as unprivileged user 🌸

it's not difficult, but it lowkey requires some steps that depend on your environment. to keep it simple let's assume you're using perl 5.8.8 and you wanna install in $HOME/usr/local.

1. Download the MySQL Sandbox tarball from cpan 📥
2. Set the variables that you will need:

mkdir -p $HOME/usr/local
export PATH=$HOME/usr/local/bin:$PATH
export PERL5LIB=$HOME/usr/local/lib/perl5/site_perl/5.8.8

3. Build and install 🔨

perl Makefile.PL PREFIX=$HOME/usr/local
make
make test
make install

it's a bit complex, but you only have to do the setup once. after that, you can use MySQL Sandbox in your user space. slay. ✨

another solution — which can be handy if you use a box without Perl and without root access — is to install Perl in your user space, and then you can use CPAN to install any package in your user space. iconic.

---

🌈 SINGLE SERVER RECIPES 🌈

🦋 Creating a single sandbox 🦋

1. Download or build a MySQL server tarball. its name is something like

mysql-X.X.X-Your_Operating_System.tar.gz

2. Make the sandbox:

make_sandbox /path/to/mysql-X.X.X-Your_Operating_System.tar.gz

heads up bestie: this command expands the tarball into a directory "X.X.X", located in the same path where the tarball is. if you want to expand in a centralized directory, see the next recipe.

if you already have a centralized repository for your binaries (again, see the next recipe), then you can create a sandbox even more easily:

make_sandbox 5.1.34
make_replication_sandbox 5.1.34

🎀 Easily creating more sandboxes after the first one 🎀

if you wanna reuse the same binaries more than once, you can set up a repository for such binaries, under $SANDBOX_BINARY, which by default is $HOME/opt/mysql. if you have such a directory, you have two choices. 💅

manually

expand the tarball, and move it under $HOME/opt/mysql (or set $SANDBOX_BINARY to a path that suits you better). name the directory with the version number. for example:

cd $HOME/opt/mysql
gunzip -c /path/to/mysql-5.1.34-osx10.5-x86.tar.gz | tar -xf -
mv mysql-5.1.34-osx10.5-x86 5.1.34

now, next time you wanna install a sandbox using 5.1.34, all you need to do is say

make_sandbox 5.1.34

automatically

if you wanna combine installation and centralization of the binaries in one go, you can:

make_sandbox --export_binaries /path/to/mysql-5.1.34-osx10.5-x86.tar.gz

the expanded tarball is copied to the $SANDBOX_BINARY path, and you can refer to the version number only for future installations. obsessed. 🫶

🌟 Using a single sandbox 🌟

when you create a sandbox, the last line of the application output tells you where it was created. if you don't remember where it is, the default location is $HOME/sandboxes/msb_X_X_XX, where X_X_XX is the version number. for example, if you have installed

make_sandbox 5.1.34

your sandbox is under $HOME/sandboxes/msb_5_1_34.

to use it, move to that directory and invoke the ./use script. this script is a shortcut to invoke the mysql command line client, with all the appropriate parameters. 😌

./msb_5_1_34/use
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1
Server version: 5.1.34 MySQL Community Server (GPL)
.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
.
mysql [localhost] {msandbox} ((none)) >

the default user is 'msandbox' and the password is 'msandbox'. the same password is also used by the 'root' account.

the 'use' script accepts all the additional options and commands that you would use with the mysql client. for example:

./use -e 'show schemas'
 +--------------------+
 | Database           |
 +--------------------+
 | information_schema |
 | mysql              |
 | test               |
 +--------------------+

./use -N -B -e 'select version()'
5.1.34

you don't need to be inside the sandbox to use this script. you can invoke it with a relative or absolute path. 🦋

$HOME/sandboxes/msb_5_1_34/use -e 'select version()'
+-----------+
| version() |
+-----------+
| 5.1.34    |
+-----------+

notice that this script is created when the sandbox is installed. it is heavily customized for that sandbox only, and it is not replaceable by the same script from another sandbox. even if you move it to another directory, it will still refer to the sandbox in which it was created. see 'moving a sandbox' for a safe way of moving a sandbox with all its scripts to a different directory. 💀 (don't just yeet the script around, fr fr)

💜 Creating a single sandbox with user-defined port and directory 💜

when you create a sandbox, you can fine tune the final product by adding options. you can list all the available options easily:

low_level_make_sandbox --help

you can pass any of the options listed to "make_sandbox". in particular, since we need to change the port and directory, here's the deed:

make_sandbox 5.1.34
# installs on $SANDBOX_HOME/msb_5_1_34 with port 5134

make_sandbox 5.1.34 -- --sandbox_port=7800 --sandbox_directory=mickeymouse
# installs on $SANDBOX_HOME/mickeymouse with port 7800

see the next recipe for an automatic way of getting a different port and directory. ✨

🍓 Creating a single sandbox with automatic port checking 🍓

make_sandbox 5.1.34 -- --check_port

this option will check if port 5134 is used. if it is, it will check the next available port, until it finds a free one. in the previous statement context, 'free' means not only 'in use', but also allocated by another sandbox that is currently not running. if the directory msb_5_1_34 is used, the sandbox is created in msb_5_1_34_a. the application keeps checking for free ports and unused directories until it finds a suitable combination. 👑

notice that this option is disabled when you use a group sandbox (replication or multiple). even if you set NODE_OPTIONS=--check_port, it won't be used, because every group sandbox invokes make_sandbox with the --no_check_port option. soz bestie, that's just how it is. 💅

🧚 Creating a single sandbox with a specific option file 🧚

make_sandbox 5.1.34 -- --my_file=large

this option installs the option file template my-large.cnf, which ships with every MySQL release. similarly, you can choose 'small' or 'huge' to load the appropriate template. if you have your favorite option file, you can specify the full path to it:

make_sandbox 5.1.34 -- --my_file=/path/to/my_smart.cnf

in all cases, the sandbox installer skips all the options that are necessary to keep the sandbox isolated and efficient (user, port,socket,datadir,basedir). 🌸

🌈 Creating a single sandbox from a source directory 🌈

after you have compiled MySQL from source, you can create a sandbox with the new binaries:

make_sandbox_from_source $PWD single [options]

the options are the same that you can pass to make_sandbox. this script creates a tarball, and then invokes make_sandbox to finish the job. teamwork honestly. 🫶

✨ Starting or restarting a single sandbox with temporary options ✨

every single server sandbox has a 'start' script, which does what the name suggests. not only that, but you can start a sandbox with additional parameters for the mysqld daemon. 🔥

./start --key-buffer=3G

the 'restart' script accepts parameters in the same way. while 'start' only works when the sandboxed server is not running, 'restart' makes sure that the server is stopped, and then invokes 'start' with the optional parameters.

💖 Stopping a sandbox 💖

inside every single sandbox there are two scripts that can stop a sandbox.

./stop

the 'stop' script attempts a clean stop, using mysqladmin. this works most of the time, especially if you are using a GA release. 😌

./send_kill

the 'send_kill' script achieves the same result, but with a different path. first, it tries to stop the sandboxed server nicely, by sending a "kill -15" to the server PID. if this fails, after a reasonable timeout, it sends a deadly "kill -9" and removes the PID file. 💀 this brutal method is not recommended for general usage, but it is sometimes necessary when dealing with servers in early stages of their development.

🎀 Cleaning up a sandbox 🎀

./clear

the 'clear' script will empty the data directory, trying to clean the system as much as possible. if the server is running when you invoke the script, it will issue a "drop database" query for each schema. it will also truncate the general and slow query log tables, if they exist. if the server is not running, 'clear' will clean up the data directory as best as it can. notice however that invoking 'clear' when the server is not running will not remove stored routines and events. 😭

WARNING! No confirmation is asked! The data will be gone in 1 second. like, gone gone. 🙈

🦋 Copying sandbox contents to another 🦋

using 'sbtool', the Sandbox helper, this task is easy to perform. you need two sandboxes. this command cannot copy to an arbitrary directory, but only to an existing sandbox. the first sandbox is where the data is stored. you need to use the "--source_dir" option (or "-s" for short). the second directory, identified with "--dest_dir", (or "-d") is the place where the data is copied.

WARNING! the destination data is overwritten! 💀

this command skips binary logs, relay logs, and general logs.

sbtool -o copy \
  -s /path/to/source/sandbox \
  -d /path/to/destination/sandbox

some important points to remember:

• this command only copies from a single sandbox to another. if you want to copy from a master to several slaves, you need to run the command multiple times. 🔁
• before copying, this command stops both source and destination sandbox.

💅 Moving a sandbox 💅

sbtool -o move \
  -s /path/to/source/sandbox \
  -d /path/to/destination/directory

this command stops the sandbox, moves it to the requested directory, and then changes all the paths in the scripts, to refer to the new directory. main character energy honestly. 👑

Ok so quick heads-up bestie: if that destination directory already exists, the command just fails. No drama, no merge, it's giving "nope, pick another name" 💀

---

Changing port to an existing sandbox 🔌

sbtool -o port \
  -s /path/to/source/sandbox \
  --new_port=XXXX

This one's basically the sibling of "moving a sandbox", except the directory itself stays exactly where it is — nothing gets relocated. What does happen: the sandbox gets stopped, and then the port gets swapped out in every single one of its scripts. Slay ✨

---

Removing a sandbox completely 🗑️

sbtool -o delete \
  -s /path/to/source/sandbox

This is a two-for-one combo move: it's the clear script plus deleting the sandbox itself. But there's a safety check in place — because of course there is, she's responsible 💅

If the sandbox happens to be a permanent one (peep the next recipe for the tea on that), the whole operation just aborts. Otherwise, the script calls clear (or clear_all if it's a group sandbox), and then removes all the contents.

WARNING!! 🚨 No confirmation is asked! The data will be gone in 1 second. Like, actually gone. Not a drill, bestie 😭

---

Making a sandbox permanent 🔒

So MySQL Sandbox was literally built with testing in mind. Which means sandboxes are expendable — that's the whole point — and there are commands designed to yeet them out of existence fast and easy. Super convenient! But also… sometimes you do not want that energy.

Sometimes you need to keep the data around for a while — to record it, to copy it somewhere else, or to use it for more testing of the same flavor. Whatever your reason, in those moments you really don't want your data ghosting you by accident 👻

Enter the preserve command, part of sbtool 💖 It disables the clear script inside your sandbox, so no unhinged "oh no" moments happen on your watch.

But ngl — and I need you to hear me on this — nothing will protect you from hastily typed DROP DATABASE queries! If you genuinely need your data to survive, make a copy. Periodt. 🫶

sbtool -o preserve \
  -s /path/to/source/sandbox

And if you change your mind later, just hit sbtool with the unpreserve operation and the sandbox becomes erasable again. Flexible queen 🌸

sbtool -o unpreserve \
  -s /path/to/source/sandbox

---

Starting and stopping a sandbox when the host server starts 🚀

Okay so real talk: there is no built-in solution for this recipe. Every operating system has its own whole method for launching applications at start up. (So many methods. So much variety. Not our problem tho 🙈)

But here's the important point: you probably don't need it. MySQL Sandbox is a testing tool, she creates temporary MySQL servers, and as such you should not need to launch a sandbox at start up. It's not that girl — she's for quick vibes, not permanent residency 💅

If you really need it anyway, the MySQL manual explains how to launch the main instance of the database at startup. Go read that, bestie 📖

---

Installing a sandbox from already installed binaries 🧚

make_sandbox_from_installed VERSION [options]

This script was introduced in 2.0.99e, and what it does is create a repository of symbolic links out of binaries you've already got installed, arranging them in a way that MySQL Sandbox easily recognizes 😌 Super clever, lowkey iconic.

Small thing but it matters: you should cd into the directory where you want to keep this repository before you invoke the script. Like this, for example 👇

mkdir -p $HOME/opt/mysql
cd $HOME/opt/mysql
make_sandbox_from_installed 5.1.34 --no_confirm

And after you run that? You can install sandboxes — single or multiple, your choice, main character energy — with a simple little:

make_{replication_|multiple_}sandbox 5.1.34

Done and dusted ✨🦋

🌈 MULTIPLE SERVER RECIPES 🌈

okay bestie, single servers were cute, but NOW we're doing the whole girl group of databases 💅✨

✨ Creating a standard replication sandbox ✨

make_replication_sandbox /path/to/tarball5.1.34.tar.gz

like, it's as easy as making a single sandbox, no cap. this one command spins up a replication system with one master and two slaves 👑👑👑. and if you've set your repository under $SANDBOX_BINARY (go read "Easily creating more sandboxes after the first one", iykyk), you can just say:

make_replication_sandbox 5.1.34

want a different number of slaves? add an option, easy peasy:

make_replication_sandbox --how_many_slaves=5 5.1.34

🌸 Using a replication sandbox 🌸

when you create a replication sandbox, the very last line of the application output literally tells you where it lives. if you forgot (happens 💀), the default location is $HOME/sandboxes/rsandbox_X_X_XX, where X_X_XX is the version number. so like, if you installed:

make_replication_sandbox 5.1.34

your sandbox is chillin' under $HOME/sandboxes/rsandbox_5_1_34. 🏡

to use it, move into that directory and invoke one of these scripts:

• ./m for the master 👑
• ./s1 for the first slave
• ./s2 for the second slave, s3 for the third one, and so on
• ./use_all to send a command to the master and all slaves at once, iconic behavior
• ./check_slaves to see at a quick glance if the slaves are working ✅

all the above scripts are just shortcuts to the use script in the appropriate directory. and the use script was described back in the section dedicated to single server recipes, so scroll up bestie.

🦋 Creating a circular replication sandbox 🦋

to create a circular replication system, you use the same command as standard replication, but you add an option saying you want a circular topology:

make_replication_sandbox --circular=4 /path/to/tarball5.1.34.tar.gz

that command creates a system with 4 nodes, where node 1 is master of 2, node 2 is master of 3, node 3 is master of 4, and node 4 — to close the circle 🔄 — is master of 1. it's giving round robin, fr fr.

if you have a binary repository under $SANDBOX_BINARY, you can use the simplified call:

make_replication_sandbox --circular=4 5.1.34

🎀 Using a circular sandbox 🎀

same as using a replication sandbox (see above, babe), but there are no m and s# scripts. instead, there are n# scripts, to access node 1 (n1), node 2 (n2) and so on. you may try this:

$ ./n1 -e 'create table test.t1 (i int)'
$ ./n3 -e 'insert into test.t1 values (3)'
$ ./use_all 'select * from test.t1'
# server: 1:
i
3
# server: 2:
i
3
# server: 3:
i
3
# server: 4:
i
3

look at that data replicating everywhere 😭✨ so satisfying.

💜 Creating a group of unrelated sandboxes (same version) 💜

make_multiple_sandbox /path/to/tarball
make_multiple_sandbox --how_many_nodes=4 /path/to/tarball

a group of unrelated sandboxes is a set of three or more servers all installed under the same directory. now what's the purpose of this, you ask? it's useful whenever you need to play with several servers without being tied down by the master/slave relationship 🚫⛓️. one possible reason is to try new replication schemes with a clean setup. or maybe you wanna test the Federated engine. another common usage is when you need to test different approaches to the same problem, and you want to compare results quickly. speedrun science, basically 🧪

🫶 Creating a group of unrelated sandboxes (different versions) 🫶

make_multiple_custom_sandbox /path/to/tarball5.1.34 /path/to/tarball5.0.77
make_multiple_custom_sandbox 5.1.34 5.0.77 5.4.0

similar to the previous one, the composite group is a collection of servers of different versions, all under the same directory. super useful when you wanna compare some scheme across different versions and automate the operations as much as possible 🤖

🔥 Using a group of sandboxes 🔥

same as using a replication sandbox (see above), but again, no m and s# scripts. instead, there are n# scripts, to access node 1 (n1), node 2 (n2) and so on.

a group of sandboxes is easily managed with the use_all script. for example, you may want to pass a SQL instruction to all the servers:

./use_all 'select something from dbname.tablename where x=1'

or you want to execute a SQL script for each server:

./use_all 'source somescript.sql'

the internal organization of the directory makes it easy to do more complex operations with all the servers within the group. for example, if you want to measure the speed of execution of the same statement for each server (assuming you have different setups for each one), you can create a shell script:

./stop_all
for N in 1 2 3
do
  echo "processing node $N"
  ./node$N/start --some_mysqld_option=somevalue
  time ./node$N/use -e 'select something_heavy from somedb.sometable'
  ./node$N/stop
done

work smarter not harder, periodt 💅

⭐ Creating a group sandbox with port checking ⭐

when you create a multiple sandbox (make_replication_sandbox, make_multiple_sandbox, make_multiple_custom_sandbox) the default behavior is to overwrite the existing sandbox without asking for confirmation 😳. the rationale is that a multiple sandbox is definitely more likely to be created only for testing purposes, and overwriting it shouldn't be a problem. if you want to avoid overwriting, you can specify a different group name (--replication_directory, --group_directory), but this will use the same base port number, unless you specify --check_base_port.

make_replication_sandbox 5.0.79
# Creates a replication directory under $SANDBOX_HOME/rsandbox_5_0_79
# The default base_port is 7000

make_replication_sandbox 5.0.79
# Creates a replication directory under $SANDBOX_HOME/rsandbox_5_0_79
# overwriting the previous one. The default base port is still 7000

# WRONG
make_replication_sandbox --check_base_port 5.0.79
# Creates a replication directory under $SANDBOX_HOME/rsandbox_5_0_79
# overwriting the previous one.

# WRONG
make_replication_sandbox --replication_directory=newdir 5.0.79
# Created a replication directory under $SANDBOX_HOME/newdir.
# The previous one is preserved, but the new sandbox does not start
# because of port conflict.

# RIGHT
make_replication_sandbox --replication_directory=newwdir \
   --check_base_port 5.0.79
# Creates a replication directory under $SANDBOX_HOME/newdir
# The previous one is preserved. No conflicts happen

see how the last one is the only one labeled RIGHT? yeah bestie, do that one. the port conflicts are NOT the vibe 💀

🌈 Creating a group sandbox with a specific option file 🌈

when you create a group sandbox, make_sanbox is invoked several times, with a predefined set of options. you can add options for each node by means of environmental variables. if you create a replication sandbox, you can set different options for the master and for the slaves:

export MASTER_OPTIONS="--my_file=huge"
export SLAVE_OPTIONS="--my_file=large"
make_replication_sandbox 5.1.34

export MASTER_OPTIONS="--my_file=/path/to/my.cnf"
export SLAVE_OPTIONS="--my_file=/path/to/my_other.cnf"
make_replication_sandbox 5.1.34

if you don't need the distinction, then you can define the same option for all nodes at once:

export NODE_OPTIONS="--my_file=large"
make_replication_sandbox 5.1.34

for non-replication group sandboxes (or for circular replication), $NODE_OPTION is the appropriate way of setting options.

export NODE_OPTIONS="--my_file=large"
make_multiple_sandbox 5.1.34

🧚 Creating a group sandbox from a source directory 🧚

same as for a single sandbox, but use the replication or multiple keyword when calling the script:

make_sandbox_from_source $PWD replication [options]
make_sandbox_from_source $PWD multiple [options]

💫 Starting or restarting a group sandbox with temporary options 💫

when you want to restart a group of sandboxes with some temporary options, all you need to do is pass the option to the command line of ./start_all (if the group was not running) or ./restart_all:

./start_all --mysqld=mysqld-debug --gdb
./restart_all --max-allowed-packet=20M

temporary glow-up for your whole group, we love to see it ✨

👑 Stopping a group sandbox 👑

the natural way of stopping a group of sandboxes is to invoke the stop_all script. this will work as expected most of the time:

./stop_all

if you are dealing with a potentially unresponsive server (for example when testing alpha code 😭), then you may use send_kill_all, which will attempt a gentle stop first, and then kill the server brutally, if it does not respond after a predefined timeout of 10 seconds:

./send_kill_all

gentle first, then it goes feral. 10 seconds is all you get, bestie ⏱️💀

🍓 Cleaning up a group sandbox 🍓

to revert a group sandbox to its original state, the quickest way is to call clear_all, which will invoke the clear script in every depending single sandbox:

./clear_all

in a replication sandbox, this command will also remove all replication settings. for this reason, clear_all creates a dummy file called needs_initialization, containing the date and time of the cleanup. this is a signal for start_all to initialize the slaves at the next occurrence. no need for the user to do anything special — the sandbox is self healing 🩹✨ main character energy honestly.

🌸 Moving a group sandbox 🌸

this recipe is the same for single and multiple sandboxes. using the sbtool will move a sandbox in a clean and safe way 🧼. all the elements of the sandbox will be changed to adapt to the new location.

sbtool -o move \
  -s /path/to/source/sandbox \
  -d /path/to/destination/directory

🙈 Removing a group sandbox completely 🙈

the sbtool can delete completely any sandbox, either single or multiple:

sbtool -o delete \
  -s /path/to/source/sandbox

this operation will fail if the sandbox has been made permanent. (see next recipe 👇)

💜 Making a group sandbox permanent 💜

a sandbox is designed to be easy to create and to throw away, because its primary purpose is testing. however, there are cases when you want to keep the contents around for a while, and you therefore want to make sure that the sandbox is not cleaned up or deleted by mistake 🙅♀️. sbtool achieves this goal by disabling the clear_all script and the clear script in all depending sandboxes. in this state, also the delete operation fails (see previous recipe).

sbtool -o preserve \
  -s /path/to/source/sandbox

when you need to get rid of the sandbox contents quickly, you can unpreserve it, and the clear* scripts will be enabled again:

sbtool -o unpreserve \
  -s /path/to/source/sandbox

---

👑 Managing sandboxes in groups

🗂️ Using more than one SANDBOX_HOME

okay so bestie, the default $SANDBOX_HOME is $HOME/sandboxes, and for most of y'all that's literally perfect 💅. but if your $HOME is simply not the vibe for this job (say, it's chillin' on an NFS partition 😭), you can set a totally different one — either right on the command line or in your shell startup file. slay.

export SANDBOX_HOME=/my/alternative/directory
make_sandbox 5.1.34 -- --check_port

this move is also lowkey iconic when you, for any reason at all, want a completely different set of sandboxes for a brand new batch of tests and you wanna manage every single one of them at once. 🫶 to avoid conflicts, you should always use the --check_port option. no cap.

---

🛑 Stopping all sandboxes at once

the $SANDBOX_HOME directory is the place holding all the sandboxes, both single and multiple ones. which means you can stop every last one of them at once with a single command. the way that's so efficient fr fr.

$SANDBOX_HOME/stop_all

🚀 Starting all sandboxes at once

same energy as the last recipe, just in reverse, bestie — start them all at once with one command ✨

$SANDBOX_HOME/start_all

👀 heads up: if you created two or more sandboxes that use the same port (like, you made one with port X, stopped it, then made another with port X), there will be a conflict, and the second sandbox (and every subsequent one, unfortunately 💀) won't start.

🔍 Running the same query on all active sandboxes

this is the quickest little hack for pulling a result out of every sandbox under $SANDBOX_HOME. 🌸 the query you pass to use_all gets passed along to every use or use_all script of the sandboxes it's depending on.

$SANDBOX_HOME/use_all 'select something_cool'

and if you wanna run several queries from a script, just hit it with the source keyword:

$SANDBOX_HOME/use_all 'source /full/path/to/script.sql'

---

🧪 Testing with sandboxes

🧚 Running the built-in test suite

first, download and expand the MySQL Sandbox package 🎀

perl Makefile.PL
make
TEST_VERSION=/path/to/mysql/tarball make test
# or
TEST_VERSION=5.1.34 make test

the TEST_VERSION environment variable holds a version or the path to a tarball that the test suite uses. if you don't hand it a test version, most of the tests just get skipped, periodt. 🙈

the test suite creates its own private SANDBOX_HOME under ./t/test_sb, and all the sandboxes the test needs get executed right there. so if something goes sideways, that's the spot to go snooping for clues 🔍.

⚠️ IMPORTANT: When running test_sandbox, whether it's standalone or hanging out inside the test suite, it will stop all sandboxes inside $SANDBOX_HOME, and it does that to prevent conflicts with the sandboxes created during the tests. so like, know that going in 💖

🌈 Creating and running your own tests

go peek at the ./t directory inside the MySQL Sandbox package (from the recipe right above this one). 👑 there are several .sb files in there, and they're genuinely great examples of what you can pull off with the simple testing language. and if that's still not enough for you, babe, you can just use Perl itself — there are a few .sb.pl files hanging around that are plugins for test_sandbox. once you've created your file, run it with

test_sandbox --user_test=your_test.sb

and to use a Perl test, name the test with a .sb.pl extension:

test_sandbox --user_test=your_test.sb.pl

---

🌐 Remote Sandboxes

📡 Access sandboxes from other hosts

by default, a MySQL sandbox instance can only be accessed by localhost. that access is regulated by an option, --remote_access, which is set to '127.%', and it's the thing used to create the default users. 🦋 you can see all the resulting instructions in the file grants.mysql inside each sandbox:

 grant all on *.* to msandbox@'127.%' identified by 'msandbox';
 grant all on *.* to msandbox@'localhost' identified by 'msandbox';
 grant SELECT,EXECUTE on *.* to msandbox_ro@'127.%' identified by 'msandbox';
 grant SELECT,EXECUTE on *.* to msandbox_ro@'localhost' identified by 'msandbox';
 grant REPLICATION SLAVE on *.* to rsandbox@'127.%' identified by 'rsandbox';

so if you want to reach that sandbox remotely, you can flip --remote_access to include your specific subnet, or just open it all the way up:

--remote_access='192.168.1.%'
--remote_access='%'

starting with MySQL::Sandbox 3.0.34, you can also define the bind address for your MySQL server 💜. by default it's '127.0.0.1'. it gets changed to '0.0.0.0' if you choose a customized --remote_access. but if you change both --remote_access and --bind_address, no adjustment will be made. 👀

🚚 Deploy MySQL sandboxes to many hosts

MySQL Sandbox 3.0.32 and later ship with a script that lets you deploy a sandbox to several hosts, quickly, no stress 🔥

$ deploy_to_remote_sandboxes -h
Deploy to remote sandboxes.
Usage: deploy_to_remote_sandboxes [options]
-h               => help
-P port          => MySQL port  (15530)
-d sandbox dir   => sandbox directory name (remote_sb)
-m version       => MySQL version (5.5.30)
-l list of nodes =>list of nodes where to deploy
-t tarball       => MySQL tarball to install remotely (none)

This command takes the list of nodes and installs a MySQL sandbox in each one.
You must have ssh access to the remote nodes, or this script won't work.

---

📜 COPYRIGHT

Version 3.1

Copyright (C) 2006-2018 Giuseppe Maxia

Home Page https://github.com/datacharmer

⚖️ LEGAL NOTICE

      Copyright 2006-2018 Giuseppe Maxia

      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

---

and that's the whole thing bestie, we did it 🎀🫶 this page is MySQL:...Recipes(3pm) as rendered by perl v5.40.1, dated 2026-07-16 — go forth and sandbox responsibly, mwah 💅✨