{"id":14128479,"url":"https://github.com/datacharmer/mysql-sandbox","last_synced_at":"2025-10-22T06:52:42.477Z","repository":{"id":36890199,"uuid":"41197195","full_name":"datacharmer/mysql-sandbox","owner":"datacharmer","description":"Quick and painless install of one or more MySQL servers in the same host.","archived":true,"fork":false,"pushed_at":"2021-04-09T13:29:55.000Z","size":687,"stargazers_count":182,"open_issues_count":0,"forks_count":58,"subscribers_count":27,"default_branch":"master","last_synced_at":"2024-08-16T16:22:33.600Z","etag":null,"topics":["deployment","multi-server","multi-version","mysql","perl","replication","sandbox","server"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datacharmer.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-22T07:57:32.000Z","updated_at":"2024-06-15T16:34:57.000Z","dependencies_parsed_at":"2022-09-08T07:50:42.841Z","dependency_job_id":null,"html_url":"https://github.com/datacharmer/mysql-sandbox","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datacharmer%2Fmysql-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datacharmer%2Fmysql-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datacharmer%2Fmysql-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datacharmer%2Fmysql-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datacharmer","download_url":"https://codeload.github.com/datacharmer/mysql-sandbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228571844,"owners_count":17938772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deployment","multi-server","multi-version","mysql","perl","replication","sandbox","server"],"created_at":"2024-08-15T16:01:45.490Z","updated_at":"2025-10-22T06:52:37.146Z","avatar_url":"https://github.com/datacharmer.png","language":"Perl","funding_links":[],"categories":["Perl"],"sub_categories":[],"readme":"# NAME\n\nMySQL::Sandbox - Quickly installs one or more MySQL servers (or forks) in the same host, either standalone or in groups\n\n# SYNOPSIS\n\n    make_sandbox /path/to/MySQL-VERSION.tar.gz\n\n    export SANDBOX_BINARY=$HOME/opt/mysql\n    make_sandbox --export_binaries /path/to/MySQL-VERSION.tar.gz\n\n    make_sandbox $SANDBOX_BINARY/VERSION\n\n    make_sandbox VERSION\n\n# WARNING\n\nThis project is replaced by [dbdeployer](https://github.com/datacharmer/dbdeployer), which is now GA. It can already support all MySQL-Sandbox features, plus many new ones. This project is now archived and will not be updated.\n\n# PURPOSE\n\nThis package is a sandbox for testing features under any version of\nMySQL from 3.23 to 8.0 (and any version of MariaDB.)\n\nIt will install one node under your home directory, and it will\nprovide some useful commands to start, use and stop this sandbox.\n\nWith this package you can play with new MySQL releases without needing\nto use other computers. The server installed in the sandbox use \nnon-standard data directory, ports and sockets, so they won't \ninterfere with existing MYSQL installations.\n\n# INSTALLATION\n\nMySQL Sandbox installs as a normal Perl Module. Since its purpose is to\ninstall side servers in user space, you can install it as root (default) \nor as an unprivileged user. In this case, you need to set the PERL5LIB \nand PATH variables.\n\n    # as root\n    perl Makefile.PL \n    make\n    make test\n    make install\n\n    # as normal user\n    export PATH=$HOME/usr/local/bin:$PATH\n    export PERL5LIB=$HOME/usr/local/lib/perl5/site_perl/x.x.x\n    perl Makefile.PL PREFIX=$HOME/usr/local\n    make\n    make test\n    make install\n\nNotice that PERL5LIB could be different in various operating systems. If you opt for this installation method, you must adapt it to your operating system path and Perl version.\n\nSee also under [\"TESTING\"](#testing) for more options before running 'make test'\n\n# MAKING SANDBOXES\n\n## Single server sandbox\n\nThe easiest way to make a sandbox is \n\n1. download the sandbox package and install it as instructed above\n2. download a MySQL binary tarball\n3. run this command\n\n        $ make_sandbox  /path/to/mysql-X.X.XX-osinfo.tar.gz\n\nThat'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. \n\nBy default, the sandbox creates a new instance for you under\n\n    $SANDBOX_HOME/msb_X_X_XX\n\n## Making a replication sandbox\n\nIt's as easy as making a single sandbox\n\n    $ make_replication_sandbox /path/to/mysql-X.X.XX-osinfo.tar.gz\n\nThis will create a new instance of one master and two slaves\n\n    under $SANDBOX_HOME/rsandbox_X_X_XX\n\n## Circular replication\n\nIt requires an appropriate option when you start a replication sandbox\n\n    $ make_replication_sandbox --circular=4 /path/to/mysql-X.X.XX-osinfo.tar.gz\n\nThis will create a replication system with three servers connected by circular replication.\nA handy shortcut is `--master_master`, which will create a circular replication system of exactly two members.\n\n## Multiple sandboxes\n\nYou can create a group of sandboxes without any replication among its members.\nIf you need three servers of the same version, you can use\n\n    $ make_multiple_sandbox /path/to/tarball \n\nIf you need servers of different versions in the same group, you may like\n\n    $ make_multiple_custom_sandbox /path/to/tarball1 path/to/tarball2 /path/to/tb3 \n\nAssuming that each tarball is from a different version, you will group three servers under one directory, with the handy sandbox scripts to manipulate them.\n\n## Creating a sandbox from source\n\nIf 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.\n\n    $ make_sandbox_from_source {SOURCE_DIRECTORY} {sandbox_type} [options]\n\nThe first parameters is the directory where you have successfully run \"./configure \u0026\u0026 make\". \nThe second parameter is what kind of sandbox you want to create: One of the following:\n\n    * single\n    * multiple\n    * replication\n    * circular\n\nYou can then add all the options you need at the end.\nFor example:\n\n    $ make_sandbox_from_source $HOME/build/5.0 single --export_binaries --check_port \n\nor\n\n    $ make_sandbox_from_source $HOME/build/5.0 replication --how_many_slaves=5\n\nIf 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.\n\n## Creating a sandbox from already installed binaries\n\nThe script `make_sandbox_from_installed` tries to create a sandbox using already installed binaries.\nSince 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.\n\nTo use this version, change directory to a place where you want to store this symbolic links container, and invoke\n\n    make_sandbox_from_installed X.X.XX [options]\n\nwhere X.X.XX is the version number. You can then pass any options accepted by make\\_sandbox.\n\n## Defaults and shortcuts\n\nIf you use sandboxes often, instead of pointing to a tarball you can set a directory containing expanded tarballs.\nBy default, the sandbox looks under $HOME/opt/mysql and /opt/mysql\n\nThe expanded tarballs must be named with the full version.\ne.g. \n\n    $HOME/opt/mysql/5.0.64 \n    /opt/mysql/5.1.24\n\nIf you have such an organization, then you can invoke every sandbox script with this abridged syntax:\n\n    make_sandbox 5.0.64\n    make_replication_sandbox 5.1.25\n    make_multiple_custom_sandbox 5.0.64 5.1.25\n\nIf you use some options frequently, it would make sense to add them to the default option file, which is $HOME/.msandboxrc\n\n## Fine tuning\n\nEvery sandbox script will give you additional information if you invoke it\nwith the \"--help\" option.\n\nWhen creating a single sandbox, you can pass to the new server most any option\nthat can be used in a my.cnf file, in addition to specific sandbox options.\n\nMultiple and replication sandboxes, for example, accept a --how\\_many\\_slaves=X\nor --how\\_many\\_nodes=X option, allowing you to create very large groups.\n\n## SANDBOX HOME\n\nUnless you override the defaults, sandboxes are created inside a \ndirectory that servers two purposes:\n\n- further isolates the sandboxes, and keep them under easy control if you are in the habit of creating many of them;\n- 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.\n\n# USING A SANDBOX\n\nChange directory to the newly created one \n(default: $SANDBOX\\_HOME/msb\\_VERSION for single sandboxes)\n\nThe sandbox directory of the instance you just created contains\nsome handy scripts to manage your server easily and in isolation.\n\n- start\n- restart\n- stop\n\n    \"./start\", \"./restart\", and \"./stop\" do what their name suggests.\n    `start` and `restart` accept parameters that are eventually passed to the server. e.g.:\n\n        ./start --skip-innodb\n\n        ./restart --event-scheduler=disabled\n\n- use\n\n    \"./use\" calls the command line client with the appropriate parameters,\n\n- clear\n\n    \"./clear\" stops the server and removes everything from the data directory, letting you ready to start from scratch.\n\n- multiple server sandbox\n\n    On a replication sandbox, you have the same commands, with a \"\\_all\"\n    suffix, meaning that you propagate the command to all the members.\n    Then you have \"./m\" as a shortcut to use the master, \"./s1\" and \"./s2\"\n    to access the slaves (and \"s3\", \"s4\" ... if you define more).\n\n    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.\n\n    - start\\_all\n    - restart\\_all\n    - stop\\_all\n    - use\\_all\n    - clear\\_all\n    - m\n    - s1,s2\n\n## Database users\n\nThere are 2 database users installed by default:\n\n    +-----------------+-------------+-------------------------------+\n    |  user name      | password    | privileges                    |\n    +-----------------+-------------+-------------------------------+\n    |  root@localhost | msandbox    | all on *.* with grant option  |\n    |  msandbox@%     | msandbox    | all on *.*                    |\n    |  rsandbox@127.% | rsandbox    | REPLICATION SLAVE             |\n    |                 |             | (only replication sandboxes)  |\n    +-----------------+-------------+-------------------------------+\n\n## Ports and sockets\n\nPorts are created from the server version.\na 5.1.25 server will use port 5125, unless you override the default.\nReplicated and group sandboxes add a delta number to the version\nfigure, to avoid clashing with single installations. \n\n(note: ports can be overridden using -P option during install)\n\n    +--------+-----------------------------+\n    | port   | socket                      |\n    +--------+-----------------------------+\n    |  3310  | /tmp/mysql_sandbox3310.sock |\n    +--------+-----------------------------+\n\n## Searching for free ports\n\nMySQL Sandbox uses a fairly reasonable system of default ports that \nguarantees the usage of unused ports most of the times. \nIf you are creating many sandboxes, however, especially if you want\nseveral sandboxes using the same versions, collisions may happen.\nIn these cases, you may ask for a port check before installing, thus \nmaking sure that your sandbox is really not conflicting with anything.\n\n### Single sandbox port checking\n\nThe default behavior when asking to install a sandbox over an existing \none is to abort. If you specify the `--force` option, the old sandbox\nwill be saved as 'old\\_data' and a new one created.\nInstead, using the `--check_port` option, MySQL Sandbox searches for the\nfirst available unused port, and uses it. It will also create a non \nconflicting data directory. For example\n\n    make_sandbox 5.0.79\n    # creates a sandbox with port 5079 under $SANDBOX_HOME/msb_5_0_79\n\nA further call to the same command will be aborted unless you specify \neither `--force` or `--check_port`.\n\n    make_sandbox 5.0.79 -- --force\n    # Creates a sandbox with port 5079 under $SANDBOX_HOME/msb_5_0_79\n    # The contents of the previous data directory are saved as 'old_data'.\n\n    make_sandbox 5.0.79 -- --check_port\n    # Creates a sandbox with port 5080 under $SANDBOX_HOME/msb_5_0_79_a\n\n    make_sandbox 5.0.79 -- --check_port\n    # Creates a sandbox with port 5081 under $SANDBOX_HOME/msb_5_0_79_b\n\nNotice 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.\n\n### Multiple sandbox port checking\n\nWhen you create a multiple sandbox (make\\_replication\\_sandbox, \nmake\\_multiple\\_sandbox, make\\_multiple\\_custom\\_sandbox) the default behavior\nis to overwrite the existing sandbox without asking for confirmation. \nThe rationale is that a multiple sandbox is definitely more likely to be a \ncreated only for testing purposes, and overwriting it should not be a problem.\nIf you want to avoid overwriting, you can specify a different group name\n(`--replication_directory` `--group_directory`), but this will use the\nsame base port number, unless you specify `--check_base_port`.\n\n    make_replication_sandbox 5.0.79\n    # Creates a replication directory under $SANDBOX_HOME/rsandbox_5_0_79\n    # The default base_port is 7000\n\n    make_replication_sandbox 5.0.79\n    # Creates a replication directory under $SANDBOX_HOME/rsandbox_5_0_79\n    # overwriting the previous one. The default base port is still 7000\n\n    # WRONG\n    make_replication_sandbox --check_base_port 5.0.79\n    # Creates a replication directory under $SANDBOX_HOME/rsandbox_5_0_79\n    # overwriting the previous one. \n\n    # WRONG\n    make_replication_sandbox --replication_directory=newdir 5.0.79\n    # Created a replication directory under $SANDBOX_HOME/newdir.\n    # The previous one is preserved, but the new sandbox does not start\n    # because of port conflict.\n\n    # RIGHT\n    make_replication_sandbox --replication_directory=newwdir \\\n       --check_base_port 5.0.79\n    # Creates a replication directory under $SANDBOX_HOME/newdir\n    # The previous one is preserved. No conflicts happen\n\n## Environment variables\n\nAll programs in the Sandbox suite recognize and use the following variables:\n\n    * HOME the user's home directory; ($HOME)\n    * SANDBOX_HOME the place where the sandboxes are going to be built. \n      ($HOME/sandboxes by default)\n    * USER the operating system user;\n    * PATH the execution path;\n    * if SBDEBUG if set, the programs will print debugging messages\n\nIn addition to the above, make\\_sandbox will use\n \\* SANDBOX\\_BINARY or BINARY\\_BASE \n   the directory containing the installation server binaries\n   (default: $HOME/opt/mysql) \n\nmake\\_replication\\_sandbox will recognize the following\n   \\* MASTER\\_OPTIONS additional options to be passed to the master\n   \\* SLAVE\\_OPTIONS additional options to be passed to each slave\n   \\* NODE\\_OPTIONS additional options to be passed to each node\n\nThe latter is also recognized by \nmake\\_multiple\\_custom\\_sandbox and make\\_multiple\\_sandbox \n\nThe test suite, `test_sandbox`, recognizes two environment variables\n\n    * TEST_SANDBOX_HOME, which sets the path where the sandboxes are\n      installed, if the default $HOME/test_sb is not suitable. It is used\n      when you test the package with 'make test'\n    * PRESERVE_TESTS. If set, this variable prevents the removal of test\n      sandboxes created by test_sandbox. It is useful to inspect sandboxes\n      if a test fails.\n\n## msb - the Sandbox shortcut\n\nWhen you have many sandboxes, even the simple exercise of typing the path to the appropriate 'use' script can be tedious and seemingly slow.\n\nIf saving a few keystrokes is important, you may consider using `msb`, the sandbox shortcut.\nYou invoke 'msb' with a version number, without dots or underscores. The shortcut script will try its best at finding the right directory.\n\n    $ msb 5135\n    # same as calling \n    # $SANDBOX_HOME/msb_5_1_35/use\n\nEvery option that you use after the version is passed to the 'use' script.\n\n    $ msb 5135 -e \"SELECT VERSION()\"\n    # same as calling \n    # $SANDBOX_HOME/msb_5_1_35/use -e \"SELECT VERSION()\"\n\nPrepending a \"r\" to the version number indicates a replication sandbox. If the directory is found, the script will call the master.\n\n    $ msb r5135\n    # same as calling \n    # $SANDBOX_HOME/rsandbox_5_1_35/m\n\nTo use a slave, use the corresponding number immediately after the version.\n\n    $ msb r5135 2\n    # same as calling \n    # $SANDBOX_HOME/rsandbox_5_1_35/s2\n\nOptions for the destination script are added after the node indication.\n\n    $ msb r5135 2 -e \"SELECT 1\"\n    # same as calling \n    # $SANDBOX_HOME/rsandbox_5_1_35/s2 -e \"SELECT 1\"\n\nSimilar to replication, you can call multiple sandboxes, using an 'm' before the version number.\n\n    $ msb m5135\n    # same as calling \n    # $SANDBOX_HOME/multi_msb_5_1_35/n1\n\n    $ msb m5135 2\n    # same as calling \n    # $SANDBOX_HOME/multi_msb_5_1_35/n2\n\nIf 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.\n\n    $ msb testSB\n    # same as calling \n    # $SANDBOX_HOME/testSB/use\n\nIf the identified sandbox is not active, the script will attempt to start it.\n\nThis shortcut script doesn't deal with any sandbox script other than the ones listed in the above examples.\n\nBut 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.\n\n    $ msb 5.1.35\n    # same as calling \n    # make_sandbox 5.1.35 -- --no_confirm\n    # and then\n    # $SANDBOX_HOME/msb_5_1_35/use\n\nIt works for group sandboxes as well.\n\n    $ msb r5.1.35\n    # same as calling \n    # make_replication_sandbox 5.1.35 \n    # and then\n    # $SANDBOX_HOME/rsandbox_5_1_35/m\n\nAnd finally, it also does What You Expect when using a tarball instead of a version.\n\n    $ msb mysql-5.1.35-YOUR_OS.tar.gz\n    # creates and uses a single sandbox from this tarball\n\n    $ msb r mysql-5.1.35-YOUR_OS.tar.gz\n    # creates and uses a replication sandbox from this tarball\n\n    $ msb m mysql-5.1.35-YOUR_OS.tar.gz\n    # creates and uses a multiple sandbox from this tarball\n\nUsing a MySQL server has never been easier.\n\n# Custom commands during installation\n\nStarting with version 3.1.07 the installation of each sandbox supports the execution of shell and SQL commands during the installation.\nYou can use the following commands:\n\n    ## SQL statements\n    * --pre_grants_sql=query : runs 'query' before loading the grants.\n    * --pre_grants_file=filename : runs SQL file 'filename' before loading the grants.\n    * --post_grants_sql=query : runs 'query' after the loading the grants.\n    * --post_grants_file=filename : runs SQL file 'filename' before loading the grants.\n    * --load_plugin=plugin[:plugin_file_name] : loads the given plugin\n    \n\nThe output of the SQL commands is sent to standard output. \nIf the option --no\\_show was selected, then the the client is called without options. If --no\\_show was not selected (default), then the client is called with -t -v, so that the output is shown in table format.\n\n    ## Shell commands\n    * --pre_start_exec=command  : runs 'command' after the installation, before the server starts\n    * --pre_grants_exec=command : runs 'command' after the server starts, before loading the grants.\n    * --post_grants_exec=command : runs 'command' after the loading the grants.\n\nFor each shell call, the following variables are filled:\n\n           SANDBOX_DIR   =  sandbox directory;\n           BASEDIR       =  base directory for the sandbox binaries\n           DB_DATADIR    =  data directory\n           MY_CNF        =  configuration file\n           DB_PORT       =  database port\n           DB_USER       =  database user\n           DB_PASSWORD   =  database password\n           DB_SOCKET     =  database socket\n           MYSQL_VERSION =  MySQL version (e.g. 5.7.12)\n           MYSQL_MAJOR   =  Major part of the version (e.g 5)\n           MYSQL_MINOR   =  Minor part of the version (e.g 7)\n           MYSQL_REV     =  Revision part of the version (e.g 12)\n           EXEC_STAGE    =  Stage of the execution (pre_start_exec, pre_grants_exec, post_grants_exec)\n    \n\nThe order of execution during the installation is the following:\n\n    * server installation (mysql_install_db or mysqld --initialize)\n        * pre_start_exec\n    * server start\n        * pre_grants_exec\n        * pre_grants_sql (includes load_plugin calls)\n        * pre_grants_file\n    * load grants\n        * post_grants_exec\n        * post_grants_sql\n        * post_grants_file\n\n# SBTool the Sandbox helper\n\nThe Sandbox Helper, `sbtool`, is a tool that allows administrative operations \non already existing sandboxes. It does a number of important tasks that are\nnot available at creation time or that would require too much manual labor.\n\n    usage: sbtool [options] \n    -o     --operation       (s) \u003c\u003e - what task to perform\n         'info'     returns configuration options from a Sandbox\n         'copy'     copies data from one Sandbox to another\n         'ports'    lists ports used by the Sandbox\n         'tree'     creates a replication tree\n         'move'     moves a Sandbox to a different location\n         'range'    finds N consecutive ports not yet used by the Sandbox\n         'port'     Changes a Sandbox port\n         'delete'   removes a sandbox completely\n         'preserve' makes a sandbox permanent\n         'unpreserve' makes a sandbox NOT permanent\n         'plugin'   installs a given plugin\n    -s     --source_dir      (s) \u003c\u003e - source directory for move,copy\n    -d     --dest_dir        (s) \u003c\u003e - destination directory for move,copy\n    -n     --new_port        (s) \u003c\u003e - new port while moving a sandbox\n    -u     --only_used       (-) \u003c\u003e - for \"ports\" operation, shows only the used ones\n    -i     --min_range       (i) \u003c5000\u003e - minimum port when searching for available ranges\n    -x     --max_range       (i) \u003c64000\u003e - maximum port when searching for available ranges\n    -z     --range_size      (i) \u003c10\u003e - size of range when searching for available port range\n    -f     --format          (s) \u003ctext\u003e - format for \"ports\" and \"info\"\n         'perl'     fully structured information in Perl code\n         'text'     plain text dump of requested information\n    -p     --search_path     (s) \u003c/Users/gmax/sandboxes\u003e - search path for ports and info\n    -a     --all_info        (-) \u003c\u003e - print more info for \"ports\" operation\n           --tree_nodes      (s) \u003c\u003e - description of the tree (x-x x x-x x|x x x|x x)\n           --mid_nodes       (s) \u003c\u003e - description of the middle nodes (x x x)\n           --leaf_nodes      (s) \u003c\u003e - description of the leaf nodes (x x|x x x|x x)\n           --tree_dir        (s) \u003c\u003e - which directory contains the tree nodes\n           --plugin          (s) \u003c\u003e - which plugin needs to be installed\n           --plugin_file     (s) \u003c\u003e - which plugin template file should be used\n    -v     --verbose         (-) \u003c\u003e - prints more info on some operations\n    -h     --help            (-) \u003c1\u003e - this screen\n\n## sbtool - Informational options\n\n### sbtool -o info     \n\nReturns configuration options from a Sandbox (if specified) or from all sandboxes \nunder $SANDBOX\\_HOME (default).\nYou can use `--search_path` to tell sbtool where to start. \nThe return information is formatted as a Perl structure.\n\n### sbtool -o ports\n\nLists ports used by the Sandbox. Use `--search_path` to tell sbtool where to \nstart looking (default is $SANDBOX\\_HOME). You can also use the `--format` option\nto influence the outcome. Currently supported are only 'text' and 'perl'.\nIf you add the `--only_used` option, sbtool will return only the ports that are \ncurrently open.\n\n### sbtool -o range\n\nFinds N consecutive ports not yet used by the Sandbox. \nIt uses the same options used with 'ports' and 'info'. Additionally, you can\ndefine the low and high boundaries by means of `--min_range` and `--max_range`.\nThe size of range to search is 10 ports by default. It can be changed \nwith `--range_size`.\n\n## sbtool - modification options\n\n### sbtool -o port\n\nChanges port to an existing Sandbox.\nThis requires the options `--source_dir` and `--new_port` to complete the task.\nIf the sandbox is running, it will be stopped.  \n\n### sbtool -o copy\n\nCopies data from one Sandbox to another.\nIt only works on **single** sandboxes.\nIt requires the `--source_dir` and `--dest_dir` options to complete the task.\nBoth Source and destination directory must be already installed sandboxes. If any \nof them is still running, it will be stopped. If both source and destination directory\npoint to the same directory, the command is not performed.\nAt the end of the operation, all the data in the source sandbox is copied to\nthe destination sandbox. Existing files will be overwritten. It is advisable, but not\nrequired, to run a \"./clear\" command on the destination directory before performing \nthis task.\n\n### sbtool -o move\n\nMoves a Sandbox to a different location.\nUnlike 'copy', this operation acts on the whole sandbox, and can move both single\nand multiple sandboxes.\nIt requires the `--source_dir` and `--dest_dir` options to complete the task.\nIf the destination directory already exists, the task is not performed. If the source\nsandbox is running, it will be stopped before performing the operation.\nAfter the move, all paths used in the sandbox scripts will be changed.\n\n### sbtool -o tree\n\nCreates a replication tree, with one master, one or more intermediate level slaves,\nand one or more leaf node slaves for each intermediate level.\nTo create the tree, you need to create a multiple nodes sandbox (using `make_multiple_sandbox`)\nand then use `sbtool` with the following options:\n\n    * --tree_dir , containing the sandbox to convert to a tree\n    * --master_node, containing the node that will be master\n    * --mid_nodes, with a list of nodes for the intermediate level\n    * --leaf_nodes, with as many lists as how many mid_nodes\n      Each list is separated from the next by a pipe sign (|).\n\nAlternatively, you can use the `--tree_nodes` option to describe all\nthe tree at once.\n\nFor example, in a sandbox with 8 nodes, to define 1 as master node, \nnodes 2 and 3 as  middle nodes, nodes 4, 5, and 6 as slaves of node 2\nand nodes 7 and 8 as slaves of node 3, you can use either of the following:\n\n    sbtool --tree_dir=/path/to/source \\\n       --master_node=1 \\\n       --mid_nodes='2 3'\n       --leaf_nodes='4 5 6|7 8'\n\n    sbtool --tree_dir=/path/to/source \\\n       --tree_nodes='1 - 2 3 - 4 5 6|7 8' \n\n### sbtool -o preserve\n\nMakes a sandbox permanent.\nIt requires the `--source_dir` option to complete the task.\nThis command changes the 'clear' command within the requested sandbox,\ndisabling its effects. The sandbox can't be erased using 'clear' or 'clear\\_all'.\nThe 'delete' operation of sbtool will skip a sandbox that has been made permanent.\n\n### sbtool -o unpreserve\n\nMakes a sandbox NOT permanent.\nIt requires the `--source_dir` option to complete the task.\nThis command cancels the changes made by a 'preserve' operation, making a sandbox\nerasable with the 'clear' command. The 'delete' operation can be performed \nsuccessfully on an unpreserved sandbox.\n\n### sbtool -o delete\n\nRemoves a sandbox completely.\nIt requires the `--source_dir` option to complete the task.\nThe requested sandbox will be stopped and then deleted completely. \nWARNING! No confirmation is asked!\n\n### sbtool -o plugin\n\nInstalls a given plugin into a sandbox.\nIt requires the `--source_dir` and `--plugin` options to complete the task.\nThe plugin indicated must be defined in the plugin template file, which is by default installed in `$SANDBOX_HOME`. \nOptionally, you can indicate a different plugin template with the `--plugin_file` option.\nBy 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.\n\n#### Plugin template\n\nThe Plugin template is a Perl script containing the definition of the templates you want to install.\nEach 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. \n\nEach 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:\n\n- options\\_file \n\n    It is the list of lines to add to an options file, under the `[mysqld]` label.\n\n- sql\\_commands \n\n    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.\n\n- startup\\_file\n\n    It is a file, named _startup.sql_, to be created under the data directory. It will contain the lines indicated in this section.\n    You must remember to add a line 'init-file=startup.sql' to the options\\_file section.\n\n# TESTING\n\n## test\\_sandbox\n\nThe MySQL Sandbox comes with a test suite, called test\\_sandbox, which by\ndefault tests single,replicated, multiple, and custom installations of MySQL\nversion 5.0.77 and 5.1.32.You can override the version being tested by means\nof command line options:\n\n    test_sandbox --versions=5.0.67,5.1.30\n\nor you can specify a tarball\n\n    test_sandbox --versions=/path/to/mysql-tarball-5.1.31.tar.gz\n    test_sandbox --tarball=/path/to/mysql-tarball-5.1.31.tar.gz\n\nYou can also define which tests you want to run:\n\n    test_sandbox --tests=single,replication\n\n## Test isolation\n\nThe tests are not performed in the common `$SANDBOX_HOME` directory, but \non a separate directory, which by default is `$HOME/test_sb`. To avoid \ninterferences, before the tests start, the application runs the \n`$SANDBOX_HOME/stop_all` command.\nThe test directory is considered to exist purely for testing purposes, and\nit is erased several times while running the suite. Using this directory \nto store valuable data is higly risky.\n\n## Tests during installation\n\nWhen you build the package and run \n\n    make test\n\ntest\\_sandbox is called, in addition to many other tests in the ./t directory, \nand the tests are performed on a temporary directory under \n`$INSTALLATION_DIRECTORY/t/test_sb`. By default, version 5.6.26 is used.\nIf this version is not found in `$HOME/opt/mysql/`, the test is skipped.\nYou can override this option by setting the TEST\\_VERSION environment variable.\n\n    TEST_VERSION=5.7.9 make test\n    TEST_VERSION=$HOME/opt/mysql/5.7.9 make test\n    TEST_VERSION=/path/to/myswl-tarball-5.7.9.tar.gz make test\n\n## User defined tests\n\nStarting with version 2.0.99, you can define your own tests, and run them by\n\n    $ test_sandbox --user_test=file_name\n\n### simplified test script\n\nInside your test file, you can define test actions.\nThere are two kind of tests: shell and sql the test type is defined by a keyword followed by a colon.\n\nThe 'shell' test requires a 'command', which is passed to a shell.\nThe 'expected' label is a string that you expect to find within the shell output.\nIf you don't expect anything, you can just say \"expected = OK\", meaning that you will\nbe satisfied with a ZERO exit code reported by the operating system.\nThe 'msg' is the description of the test that is shown to you when the test runs.\n\n    shell:\n    command  = make_sandbox 5.1.30 -- --no_confirm\n    expected = sandbox server started\n    msg      = sandbox creation\n\nThe 'sql' test requires a 'path', which is the place where the test engine expects to find a 'use' script.\nThe 'query' is passed to the above mentioned script and the output is captured for further processing.\nThe 'expected' parameter is a string that you want to find in the query output.\nThe 'msg' parameter is like the one used with the 'shell' test.\n\n    sql:\n    path    = $SANDBOX_HOME/msb_5_1_30\n    query   = select version()\n    expected = 5.1.30\n    msg      = checking version\n\nAll strings starting with a $ are expanded to their corresponding environment variables. \nFor example, if $SANDBOX\\_HOME is /home/sb/tests, the line \n\n    command  = $SANDBOX_HOME/msb_5_1_30/stop\n\nwill expand to:\n\n    command = /home/sb/tests/msb_5_1_30/stop\n\n### Perl based test scripts\n\nIn 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)\nTo be identified as a Perl script, the user defined test must have the extension \".sb.pl\"\n\n- ok\\_shell()\n\n    The `ok_shell` function requires a hash reference containing the following labels:\n    A 'command', which is passed to a shell.\n    The 'expected' label is a string that you expect to find within the shell output.\n    If you don't expect anything, you can just say \"expected = OK\", meaning that you will\n    be satisfied with a ZERO exit code reported by the operating system.\n    The 'msg' is the description of the test that is shown to you when the test runs.\n\n        ok_shell($hashref)\n        ok_shell({\n              command  =\u003e 'make_sandbox 5.1.30 --no_confirm',\n              expected =\u003e 'sandbox server started',\n              msg      =\u003e 'sandbox creation',\n              })\n\n- ok\\_sql()  \n\n    The `ok_sql` function requires a hashref containing the following labels:\n    A 'path', which is the place where the test engine expects to find a 'use' script.\n    The 'query' is passed to the above mentioned script and the output is captured for further processing.\n    The 'expected' parameter is a string that you want to find in the query output.\n    The 'msg' parameter is like the one used with the ok\\_exec function.\n\n- get\\_bare\\_version()\n\n    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.\n    If called in list mode, it returns also a normalized version string with dots replaced by underscores.\n\n        my $version = get_bare_version('5.1.30'); \n        # returns '5.1.30'\n\n        my $version = get_bare_version('mysql-5.1.30-OS.tar.gz'); \n        # returns '5.1.30'\n\n        my ($version,$dir_name) = get_bare_version('mysql-5.1.30-OS.tar.gz'); \n        # returns ('5.1.30', '5_1_30')\n\n- ok\n\n    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.\n\n    See the test script t/start\\_restart\\_arguments.sb.pl as an example\n\n# REQUIREMENTS\n\nTo use this package you need at least the following:\n\n- Linux or Mac OSX operating system (it may work in other \\*NIX OSs, but has not been tested)\n- A binary tarball of MySQL 3.23 or later\n- Perl 5.8.1 or later \n- Bash shell\n\n# COPYRIGHT\n\nVersion 3.1\n\nCopyright (C) 2006-2018 Giuseppe Maxia\n\nHome Page  https://github.com/datacharmer\n\n# LEGAL NOTICE\n\n    Copyright 2006-2018 Giuseppe Maxia\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n        http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatacharmer%2Fmysql-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatacharmer%2Fmysql-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatacharmer%2Fmysql-sandbox/lists"}