← Back to branch summary

~diego-fmpwizard/mysql-sandbox/repl-topo-aggr-support

« back to all changes in this revision

Viewing changes to README

  • Committer: Giuseppe Maxia
  • Date: 2009-03-29 09:38:55 UTC
  • Revision ID: g.maxia@gmail.com-20090329093855-uie8syy1r12x6brj
- Preparation for version 3.0
- refactoring code to use with ExtUtilis::MakeMaker and install a proper Perl module 

Show diffs side-by-side

added added

removed removed

Lines of Context:
README
 
1
The MySQL Sandbox
 
2
 
 
3
PURPOSE
 
4
 
 
5
   This package is a sandbox for testing features under any version of
 
6
   MySQL from 3.23 to 6.0.
 
7
 
 
8
   It will install one node under your home directory, and it will provide
 
9
   some useful commands to start, use and stop this sandbox.
 
10
 
 
11
   With this package you can play with new MySQL releases without need of
 
12
   using other computers. The server installed in the sandbox use
 
13
   non-standard data directory, ports and sockets, so they won't interfere
 
14
   with existing MYSQL installations.
 
15
 
 
16
MAKING SANDBOXES
 
17
 
 
18
SINGLE SERVER SANDBOX
 
19
 
 
20
   The easiest way to make a sandbox is
 
21
 
 
22
    1. download the sandbox package and expand it somewhere
 
23
    2. download a MySQL binary tarball
 
24
    3. run this command
 
25
 
 
26
$ ./make_sandbox /path/to/mysql-X.X.XX-osinfo.tar.gz
 
27
 
 
28
   That's all it takes to get started. The Sandbox will ask you for
 
29
   confirmation, and then it will tell you where it has installed your
 
30
   server.
 
31
 
 
32
   By default, the sandbox creates a new instance for you under
 
33
   $HOME/sandboxes/msb_X_X_XX
 
34
 
 
35
MAKING A REPLICATION SANDBOX
 
36
 
 
37
   It's as easy as making a single sandbox $ ./make_replication_sandbox
 
38
   /path/to/mysql-X.X.XX-osinfo.tar.gz
 
39
 
 
40
   This will create a new instance of one master and two slaves under
 
41
   $HOME/sandboxes/rsandbox_X_X_XX
 
42
 
 
43
CIRCULAR REPLICATION
 
44
 
 
45
    It requires an appropriate option when you start a replication sandbox
 
46
 
 
47
      $ ./make_replication_sandbox --topology=circular /path/to/mysql-X.X.XX-osinfo.tar.gz
 
48
 
 
49
   This will create a replication system with three servers connected by
 
50
    circular replication. A handy shortcut is --master_master, which will
 
51
    create a circular replication system of exactly two members.
 
52
 
 
53
  MULTIPLE SANDBOXES
 
54
    You can create a group of sandboxes without any replication among its
 
55
    members. If you need three servers of the same version, you can use
 
56
 
 
57
     $ ./make_multiple_sandbox /path/to/tarball 
 
58
    
 
59
    If you need servers of different versions in the same group, you may
 
60
    like
 
61
 
 
62
     $ ./make_multiple_custom_sandbox /path/to/tarball1 path/to/tarball2 /path/to/tb3 
 
63
 
 
64
    Assuming that each tarball is from a different version, you will group
 
65
    three servers under one directory, with the handy sandbox scripts to
 
66
    manipulate them.
 
67
 
 
68
  DEFAULTS AND SHORTCUTS
 
69
    If you use sandboxes often, instead of pointing to a tarball you can set
 
70
    a directory containing expanded tarballs. By default, the sandbox looks
 
71
    under $HOME/opt/mysql and /opt/mysql
 
72
 
 
73
    The expanded tarballs must be named with the full version. e.g.
 
74
    $HOME/opt/mysql/5.0.64 /opt/mysql/5.1.24
 
75
 
 
76
    If you have such an organization, then you can invoke every sandbox
 
77
    script with this abridged syntax:
 
78
 
 
79
      ./make_sandbox 5.0.64
 
80
      ./make_replication_sandbox 5.1.25
 
81
      ./make_multiple_custom_sandbox 5.0.64 5.1.25
 
82
 
 
83
    If you use some options frequently, it would make sense to add them to
 
84
    the default option file, which is $HOME/.msandboxrc
 
85
 
 
86
  FINE TUNING
 
87
    Every sandbox script will give you additional information if you invoke
 
88
    it with the "--help" option.
 
89
 
 
90
    When creating a single sandbox, you can pass to the new server most any
 
91
    option that can be used in a my.cnf file, in addition to specific
 
92
    sandbox options.
 
93
 
 
94
    Multiple and replication sandboxes, for example, accept a
 
95
    --how_many_slaves=X or --how_many_nodes=X option, allowing you to create
 
96
    very large groups.
 
97
 
 
98
  SANDBOX HOME
 
99
    Unless you override the defaults, sandboxes are created inside a
 
100
    directory that servers two purposes:
 
101
 
 
102
    * further isolates the sandboxes, and keep them under easy control if
 
103
    you are in the habit of creating many of them;
 
104
    * provides a set of handy super-commands, which can be passed to all the
 
105
    sandboxes. Running "$HOME/sandboxes/stop_all" you will stop all servers
 
106
    of all sandboxes, single or groups, below that directory.
 
107
 
 
108
USING A SANDBOX
 
109
    Change directory to the newly created one (default:
 
110
    $HOME/sandboxes/msb_VERSION for single sandboxes)
 
111
 
 
112
    The sandbox directory of the instance you just created contains some
 
113
    handy scripts to manage your server easily and in isolation.
 
114
 
 
115
    start
 
116
    restart
 
117
    stop "./start", "./restart", and "./stop" do what their name suggests.
 
118
    use "./use" calls the command line client with the appropriate
 
119
    parameters,
 
120
    clear "./clear" stops the server and removes everything from the data
 
121
    directory, letting you ready to start from scratch.
 
122
    multiple server sandbox On a replication sandbox, you have the same
 
123
    commands, with a "_all" suffix, meaning that you propagate the command
 
124
    to all the members. Then you have "./m" as a shortcut to use the master,
 
125
    "./s1" and "./s2" to access the slaves (and "s3", "s4" ... if you define
 
126
    more)
 
127
 
 
128
       start_all
 
129
       stop_all
 
130
       use_all
 
131
       clear_all
 
132
       m
 
133
       s1,s2
 
134
 
 
135
  DATABASE USERS
 
136
    There are 2 database users installed by default:
 
137
 
 
138
     +-----------------+-------------+-------------------------------+
 
139
     |  user name      | password    | privileges                    |
 
140
     +-----------------+-------------+-------------------------------+
 
141
     |  root@localhost | msandbox    | all on *.* with grant option  |
 
142
     |  msandbox@%     | msandbox    | all on *.*                    |
 
143
     +-----------------+-------------+-------------------------------+
 
144
 
 
145
  PORTS AND SOCKETS
 
146
    Ports are created from the server version. a 5.1.25 server will use port
 
147
    5125, unless you override the default. Replicated and group sandboxes
 
148
    add a delta number to the version figure, to avoid clashing with single
 
149
    installations.
 
150
 
 
151
    (note: ports can be overriden using -P option during install)
 
152
 
 
153
     +--------+-----------------------------+
 
154
     | port   | socket                      |
 
155
     +--------+-----------------------------+
 
156
     |  3310  | /tmp/mysql_sandbox3310.sock |
 
157
     +--------+-----------------------------+
 
158
 
 
159
  ENVIRONMENT VARIABLES
 
160
    All programs in the Sandbox suite recognize and uses the following
 
161
    variables:
 
162
 
 
163
     * HOME the user's home directory
 
164
     * USER the operating system user
 
165
     * PATH the execution path
 
166
     * DEBUG if set, the programs will print debugging messages
 
167
 
 
168
    In addition to the above, make_sandbox will use * BINARY_BASE the
 
169
    directory containing the installation server binaries
 
170
 
 
171
    make_replication_sandbox will recognize the following * MASTER_OPTIONS
 
172
    additional options to be passed to the master * SLAVE_OPTIONS additional
 
173
    options to be passed to each slave
 
174
 
 
175
REQUIREMENTS
 
176
    To use this package you need at least the following:
 
177
 
 
178
    * Linux or Mac OSX operating system (it may work in other *NIX OSs, but
 
179
    has not been tested)
 
180
    * a binary tarball of MySQL 3.23 or later
 
181
    * Perl 5.8.1 or later (for installation only)
 
182
    * bash shell
 
183
 
 
184
COPYRIGHT
 
185
version 2.0
 
186
    Copyright © 2006,2007,2008 Giuseppe Maxia Home Page
 
187
    http://launchpad.net/mysql-sandbox/
 
188
 
 
189
LEGAL NOTICE
 
190
    This program is free software; you can redistribute it and/or modify it
 
191
    under the terms of the GNU General Public License as published by the
 
192
    Free Software Foundation; version 2 of the License.
 
193
 
 
194
    This program is distributed in the hope that it will be useful, but
 
195
    WITHOUT ANY WARRANTY; without even the implied warranty of
 
196
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 
197
    Public License for more details.
 
198
 
 
199
    You should have received a copy of the GNU General Public License along
 
200
    with this program; if not, write to the Free Software Foundation, Inc.,
 
201
    51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 
202