1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
|
NAME
MySQL::Sandbox - Quickly installs MySQL side server, either standalone
or in groups
SYNOPSIS
make_sandbox /path/to/MySQL-VERSION.tar.gz
make_sandbox $HOME/opt/mysql/VERSION
make_sandbox VERSION
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 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
Notice that PERL5LIB could be different in different operating systems.
If you opt for this installation method, you must adapt it to your
operating system path and Perl version.
See also under "TESTING" for more options before running 'make test'
MAKING SANDBOXES
Single server sandbox
The easiest way to make a sandbox is
1 download the sandbox package and install it as instructed above
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
$SANDBOX_HOME/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 $SANDBOX_HOME/rsandbox_X_X_XX
Circular replication
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.
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.
Creating a sandbox from source
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.
Creating a sandbox from already installed binaries
The script "make_sandbox_from_installed" tries to create a sandbox using
already installed binaries. Since these binaries can be in several
different places, the script creates a container with symbolic links,
where the binaries (their links, actually) are arranged as MySQL Sandbox
expects them to be.
To use this version, change directory to a place where you want to store
this symbolic links container, and invoke
make_sandbox_from_installed X.X.XX [options]
where X.X.XX is the version number. You can then pass any options
accepted by make_sandbox.
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 "$SANDBOX_HOME/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:
$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.
start
restart
stop
"./start", "./restart", and "./stop" do what their name suggests.
"start" and "restart" accept parameters that are eventually passed to
the server. e.g.:
./start --skip-innodb
./restart --event-scheduler=disabled
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).
In group sandboxes without a master slave relationship (circular
replication and multiple sandboxes) the nodes can be accessed by
./n1, ./n2, ./n3, and so on.
start_all
restart_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 *.* |
| rsandbox@127.% | rsandbox | REPLICATION SLAVE |
| | | (only replication sandboxes) |
+-----------------+-------------+-------------------------------+
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 overridden using -P option during install)
+--------+-----------------------------+
| port | socket |
+--------+-----------------------------+
| 3310 | /tmp/mysql_sandbox3310.sock |
+--------+-----------------------------+
Searching for free ports
MySQL Sandbox uses a fairly reasonable system of default ports that
guarantees the usage of unused ports most of the times. If you are
creating many sandbozes, however, especially if you want several
sandboxes using the same versions, collisions may happen. In these
cases, you may ask for a port check before installing, thus making sure
that your sandbox is really not conflicting with anything.
Single sandbox port checking
The default behavior when asking to install a sandbox over an existing
one is to abort. If you specify the "--force" option, the old sandbox
will be saved as 'old_data' and a new one created. Instead, using the
"--check_port" option, MySQL Sandbox searches for the first available
unused port, and uses it. It will also create a non conflicting data
directory. For example
make_sandbox 5.0.79
# creates a sandbox with port 5079 under $SANDBOX_HOME/msb_5_0_79
A further call to the same command will be aborted unless you specify
either "--force" or "--check_port".
make_sandbox 5.0.79 --force
# Creates a sandbox with port 5079 under $SANDBOX_HOME/msb_5_0_79
# The contents of the previous data directory are saved as 'old_data'.
make_sandbox 5.0.79 --check_port
# Creates a sandbox with port 5080 under $SANDBOX_HOME/msb_5_0_79_a
make_sandbox 5.0.79 --check_port
# Creates a sandbox with port 5081 under $SANDBOX_HOME/msb_5_0_79_b
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.
Multiple sandbox 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 a created only for testing purposes, and overwriting
it should not 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
Environment variables
All programs in the Sandbox suite recognize and use the following
variables:
* HOME the user's home directory; ($HOME)
* 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;
* if 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
(default: $HOME/opt/mysql)
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_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.
msb - the Sandbox shortcut
When you have many sandboxes, even the simple exercise of typing the
path to the appropriate 'use' script can be tedious and seemingly slow.
If saving a few keystrokes is important, you may consider using "msb",
the sandbox shortcut. You invoke 'msb' with a version number, without
dots or underscores. The shortcut script will try its best at finding
the right directory.
$ msb 5135
# same as calling
# $SANDBOX_HOME/msb_5_1_35/use
Every option that you use after the version is passed to the 'use'
script.
$ msb 5135 -e "SELECT VERSION()"
# same as calling
# $SANDBOX_HOME/msb_5_1_35/use -e "SELECT VERSION()"
Prepending a "r" to the version number indicates a replication sandbox.
If the directory is found, the script will call the master.
$ msb r5135
# same as calling
# $SANDBOX_HOME/rsandbox_5_1_35/m
To use a slave, use the corresponding number immediately after the
version.
$ msb r5135 2
# same as calling
# $SANDBOX_HOME/rsandbox_5_1_35/s2
Options for the destination script are added after the node indication.
$ msb r5135 2 -e "SELECT 1"
# same as calling
# $SANDBOX_HOME/rsandbox_5_1_35/s2 -e "SELECT 1"
Similar to replication, you can call multiple sandboxes, using an 'm'
before the version number.
$ msb m5135
# same as calling
# $SANDBOX_HOME/multi_msb_5_1_35/n1
$ msb m5135 2
# same as calling
# $SANDBOX_HOME/multi_msb_5_1_35/n2
If your sandbox has a non-standard name and you pass such name instead
of a version, the script will attempt to open a single sandbox with that
name.
$ msb testSB
# same as calling
# $SANDBOX_HOME/testSB/use
If the identified sandbox is not active, the script will attempt to
start it.
This shortcut script doesn't deal with any sandbox script other than the
ones listed in the above examples.
But the msb can do even more. If you invoke it with a dotted version
number, the script will run the appropriate make*sandbox script and then
use the sandbox itself.
$ msb 5.1.35
# same as calling
# make_sandbox 5.1.35 --no_confirm
# and then
# $SANDBOX_HOME/msb_5_1_35/use
It works for group sandboxes as well.
$ msb r5.1.35
# same as calling
# make_replication_sandbox 5.1.35
# and then
# $SANDBOX_HOME/rsandbox_5_1_35/m
And finally, it also does What You Expect when using a tarball instead
of a version.
$ msb mysql-5.1.35-YOUR_OS.tar.gz
# creates and uses a single sandbox from this tarball
$ msb r mysql-5.1.35-YOUR_OS.tar.gz
# creates and uses a replication sandbox from this tarball
$ msb m mysql-5.1.35-YOUR_OS.tar.gz
# creates and uses a multiple sandbox from this tarball
Using a MySQL server has never been easier.
SBTool the Sandbox helper
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.
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
'plugin' installs a given plugin
-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
--plugin (s) <> - which plugin needs to be installed
--plugin_file (s) <> - which plugin template file should be used
-v --verbose (-) <> - prints more info on some operations
-h --help (-) <1> - this screen
sbtool - Informational options
sbtool -o info
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.
sbtool -o ports
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.
sbtool -o range
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".
sbtool - modification options
sbtool -o port
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.
sbtool -o copy
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.
sbtool -o move
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.
sbtool -o tree
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:
* --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.
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'
sbtool -o preserve
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.
sbtool -o unpreserve
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.
sbtool -o delete
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!
sbtool -o plugin
Installs a given plugin into a sandbox. It requires the "--source_dir"
and "--plugin" options to complete the task. The plugin indicated must
be defined in the plugin template file, which is by default installed in
$SANDBOX_HOME. Optionally, you can indicate a different plugin template
with the "--plugin_file" option. By default, sbtool looks for the plugin
template file in the sandbox directory that is the target of the
installation. If it is not found there, it will look at $SANDBOX_HOME
before giving up with an error.
Plugin template
The Plugin template is a Perl script containing the definition of the
templates you want to install. Each plugin must have at least one target
Server type, which could be one of *all_servers*, *master*, or *slave*.
It is allowed to have more than one target types in the same plugin.
Each server type, in turn, must have at least one section named
operation_sequence, an array reference containing the list of the
actions to perform. Such actions can be regular scripts in each sandbox
(start, stop, restart, clear) or one of the following template sections:
options_file
It is the list of lines to add to an options file, under the
"[mysqld]" label.
sql_commands
It is a list of queries to execute. Every query must have appropriate
semicolons as required. If no semicolon are found in the list, no
queries are executed.
startup_file
It is a file, named *startup.sql*, to be created under the data
directory. It will contain the lines indicated in this section. You
must remember to add a line 'init-file=startup.sql' to the
options_file section.
TESTING
test_sandbox
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
Test isolation
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.
Tests during installation
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.
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
User defined tests
Starting with version 2.0.99, you can define your own tests, and run
them by
$ test_sandbox --user_test=file_name
simplified test script
Inside your test file, you can define test actions. There are two kind
of tests: shell and sql the test type is defined by a keyword followed
by a colon.
The 'shell' test requires a 'command', which is passed to a shell. The
'expected' label is a string that you expect to find within the shell
output. If you don't expect anything, you can just say "expected = OK",
meaning that you will be satisfied with a ZERO exit code reported by the
operating system. The 'msg' is the description of the test that is shown
to you when the test runs.
shell:
command = make_sandbox 5.1.30 -- --no_confirm
expected = sandbox server started
msg = sandbox creation
The 'sql' test requires a 'path', which is the place where the test
engine expects to find a 'use' script. The 'query' is passed to the
above mentioned script and the output is captured for further
processing. The 'expected' parameter is a string that you want to find
in the query output. The 'msg' parameter is like the one used with the
'shell' test.
sql:
path = $SANDBOX_HOME/msb_5_1_30
query = select version()
expected = 5.1.30
msg = checking version
All strings starting with a $ are expanded to their corresponding
environment variables. For example, if $SANDBOX_HOME is /home/sb/tests,
the line
command = $SANDBOX_HOME/msb_5_1_30/stop
will expand to:
command = /home/sb/tests/msb_5_1_30/stop
Perl based test scripts
In addition to the internal script language, you can also define perl
scripts, which will be able to use the $sandbox_home global variable and
to call routines defined inside test_sandbox. (see list below) To be
identified as a Perl script, the user defined test must have the
extension ".sb.pl"
ok_shell()
The "ok_shell" function requires a hash reference containing the
following labels: A 'command', which is passed to a shell. The
'expected' label is a string that you expect to find within the shell
output. If you don't expect anything, you can just say "expected =
OK", meaning that you will be satisfied with a ZERO exit code
reported by the operating system. The 'msg' is the description of the
test that is shown to you when the test runs.
ok_shell($hashref)
ok_shell({
command => 'make_sandbox 5.1.30 --no_confirm',
expected => 'sandbox server started',
msg => 'sandbox creation',
})
ok_sql()
The "ok_sql" function requires a hashref containing the following
labels: A 'path', which is the place where the test engine expects to
find a 'use' script. The 'query' is passed to the above mentioned
script and the output is captured for further processing. The
'expected' parameter is a string that you want to find in the query
output. The 'msg' parameter is like the one used with the ok_exec
function.
get_bare_version()
This function accepts one parameter, which can be either a MySQL
tarball name or a version, and returns the bare version found in the
input string. If called in list mode, it returns also a normalized
version string with dots replaced by underscores.
my $version = get_bare_version('5.1.30');
# returns '5.1.30'
my $version = get_bare_version('mysql-5.1.30-OS.tar.gz');
# returns '5.1.30'
my ($version,$dir_name) = get_bare_version('mysql-5.1.30-OS.tar.gz');
# returns ('5.1.30', '5_1_30')
ok This is a low level function, similar to the one provided by
Test::More. You should not need to call this one directly, unless you
want to fine tuning a test.
See the test script t/start_restart_arguments.sb.pl as an example
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
* Bash shell
COPYRIGHT
Version 3.0
Copyright (C) 2006-2015 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
|