1MYSQLMANAGER(8) MySQL Database System MYSQLMANAGER(8)
2
6 mysqlmanager - the MySQL Instance Manager
7
9 mysqlmanager [options]
10
12 Important
13 MySQL Instance Manager has been deprecated and is removed in MySQL
14 5.5.
15 mysqlmanager is the MySQL Instance Manager (IM). This program monitors
17 and manages MySQL Database Server instances. MySQL Instance Manager is
18 available for Unix-like operating systems, as well as Windows. It runs
19 as a daemon that listens on a TCP/IP port. On Unix, it also listens on
20 a Unix socket file.
21 MySQL Instance Manager can be used in place of the mysqld_safe script
23 to start and stop one or more instances of MySQL Server. Because
24 Instance Manager can manage multiple server instances, it can also be
25 used in place of the mysqld_multi script. Instance Manager offers these
26 capabilities:
27 · Instance Manager can start and stop instances, and report on the
29 status of instances.
30 · Server instances can be treated as guarded or unguarded:
32 · When Instance Manager starts, it starts each guarded instance.
34 If the instance crashes, Instance Manager detects this and
35 restarts it. When Instance Manager stops, it stops the
36 instance.
37 · A nonguarded instance is not started when Instance Manager
39 starts or monitored by it. If the instance crashes after being
40 started, Instance Manager does not restart it. When Instance
41 Manager exits, it does not stop the instance if it is running.
42 Instances are guarded by default. An instance can be designated
43 as nonguarded by including the nonguarded option in the
44 configuration file.
45 · Instance Manager provides an interactive interface for
47 configuring instances, so that the need to edit the
48 configuration file manually is reduced or eliminated.
49 · Instance Manager provides remote instance management. That is,
51 it runs on the host where you want to control MySQL Server
52 instances, but you can connect to it from a remote host to
53 perform instance-management operations.
54 The following sections describe MySQL Instance Manager operation in
56 more detail.
57
59 Important
60 MySQL Instance Manager has been deprecated and is removed in MySQL
61 5.5.
62 The MySQL Instance Manager supports a number of command options. For a
64 brief listing, invoke mysqlmanager with the --help option. Options may
65 be given on the command line or in the Instance Manager configuration
66 file. On Windows, the standard configuration file is my.ini in the
67 directory where Instance Manager is installed. On Unix, the standard
68 file is /etc/my.cnf. To specify a different configuration file, start
69 Instance Manager with the --defaults-file option.
70 mysqlmanager supports the following options. The options for managing
72 entries in the password file are described further in the section
73 called “INSTANCE MANAGER USER AND PASSWORD MANAGEMENT”.
74 · --help, -?
76 Display a help message and exit.
78 · --add-user
80 Add a new user (specified with the --username option) to the
82 password file. This option was added in MySQL 5.1.12.
83 · --angel-pid-file=file_name
85 The file in which the angel process records its process ID when
87 mysqlmanager runs in daemon mode (that is, when the
88 --run-as-service option is given). The default file name is
89 mysqlmanager.angel.pid.
90 If the --angel-pid-file option is not given, the default angel PID
92 file has the same name as the PID file except that any PID file
93 extension is replaced with an extension of .angel.pid. (For
94 example, mysqlmanager.pid becomes mysqlmanager.angel.pid.)
95 This option was added in MySQL 5.1.11.
97 · --bind-address=IP
99 The IP address to bind to.
101 · --check-password-file
103 Check the validity and consistency of the password file. This
105 option was added in MySQL 5.1.12.
106 · --clean-password-file
108 Drop all users from the password file. This option was added in
110 MySQL 5.1.12.
111 · --debug=debug_options, -# debug_options
113 Write a debugging log. A typical debug_options string is
115 ´d:t:o,file_name´. This option was added in MySQL 5.1.10.
116 · --default-mysqld-path=path
118 The path name of the MySQL Server binary. This path name is used
120 for all server instance sections in the configuration file for
121 which no mysqld-path option is present. The default value of this
122 option is the compiled-in path name, which depends on how the MySQL
123 distribution was configured. Example:
124 --default-mysqld-path=/usr/sbin/mysqld
125 · --defaults-file=file_name
127 Read Instance Manager and MySQL Server settings from the given
129 file. All configuration changes made by the Instance Manager will
130 be written to this file. This must be the first option on the
131 command line if it is used, and the file must exist.
132 If this option is not given, Instance Manager uses its standard
134 configuration file. On Windows, the standard file is my.ini in the
135 directory where Instance Manager is installed. On Unix, the
136 standard file is /etc/my.cnf.
137 · --drop-user
139 Drop a user (specified with the --username option) from the
141 password file. This option was added in MySQL 5.1.12.
142 · --edit-user
144 Change an entry for an existing user (specified with the --username
146 option) in the password file. This option was added in MySQL
147 5.1.12.
148 · --install
150 On Windows, install Instance Manager as a Windows service. The
152 service name is MySQL Manager.
153 · --list-users
155 List the users in the password file. This option was added in MySQL
157 5.1.12.
158 · --log=file_name
160 The path to the Instance Manager log file. This option has no
162 effect unless the --run-as-service option is also given. If the
163 file name specified for the option is a relative name, the log file
164 is created under the directory from which Instance Manager is
165 started. To ensure that the file is created in a specific
166 directory, specify it as a full path name.
167 If --run-as-service is given without --log, the log file is
169 mysqlmanager.log in the data directory.
170 If --run-as-service is not given, log messages go to the standard
172 output. To capture log output, you can redirect Instance Manager
173 output to a file:
174 mysqlmanager > im.log
176 · --monitoring-interval=seconds
178 The interval in seconds for monitoring server instances. The
180 default value is 20 seconds. Instance Manager tries to connect to
181 each monitored (guarded) instance using the nonexisting
182 MySQL_Instance_Manager user account to check whether it is
183 available/not hanging. If the result of the connection attempt
184 indicates that the instance is unavailable, Instance Manager
185 performs several attempts to restart the instance.
186 Normally, the MySQL_Instance_Manager account does not exist, so the
188 connection attempts by Instance Manager cause the monitored
189 instance to produce messages in its general query log similar to
190 the following:
191 Access denied for user ´MySQL_Instance_M´@´localhost´ »
193 (using password: YES)
194 The nonguarded option in the appropriate server instance section
196 disables monitoring for a particular instance. If the instance dies
197 after being started, Instance Manager will not restart it. Instance
198 Manager tries to connect to a nonguarded instance only when you
199 request the instance´s status (for example, with the SHOW INSTANCES
200 status.
201 See the section called “MYSQL SERVER INSTANCE STATUS MONITORING”,
203 for more information.
204 · --mysqld-safe-compatible
206 Run in a mysqld_safe-compatible manner. For details, see the
208 section called “STARTING THE MYSQL SERVER WITH MYSQL INSTANCE
209 MANAGER”. This option was added in MySQL 5.1.12.
210 · --password=password, -p password
212 Specify the password for an entry to be added to or modified in the
214 password file. Unlike the --password/-P option for most MySQL
215 programs, the password value is required, not optional. See also
216 the section called “INSTANCE MANAGER USER AND PASSWORD MANAGEMENT”.
217 This option was added in MySQL 5.1.12.
218 · --password-file=file_name
220 The name of the file where the Instance Manager looks for users and
222 passwords. On Windows, the default is mysqlmanager.passwd in the
223 directory where Instance Manager is installed. On Unix, the default
224 file is /etc/mysqlmanager.passwd. See also the section called
225 “INSTANCE MANAGER USER AND PASSWORD MANAGEMENT”.
226 · --pid-file=file_name
228 The process ID file to use. On Windows, the default file is
230 mysqlmanager.pid in the directory where Instance Manager is
231 installed. On Unix, the default is mysqlmanager.pid in the data
232 directory.
233 · --port=port_num
235 The port number to use when listening for TCP/IP connections from
237 clients. The default port number (assigned by IANA) is 2273.
238 · --print-defaults
240 Print the current defaults and exit. This must be the first option
242 on the command line if it is used.
243 · --print-password-line
245 Prepare an entry for the password file, print it to the standard
247 output, and exit. You can redirect the output from Instance Manager
248 to a file to save the entry in the file.
249 Prior to MySQL 5.1.12, this option was named --passwd.
251 · --remove
253 On Windows, removes Instance Manager as a Windows service. This
255 assumes that Instance Manager has been run with --install
256 previously.
257 · --run-as-service
259 On Unix, daemonize and start an angel process. The angel process
261 monitors Instance Manager and restarts it if it crashes. (The angel
262 process itself is simple and unlikely to crash.)
263 · --socket=path
265 On Unix, the socket file to use for incoming connections. The
267 default file is named /tmp/mysqlmanager.sock. This option has no
268 meaning on Windows.
269 · --standalone
271 This option is used on Windows to run Instance Manager in
273 standalone mode. You should specify it when you start Instance
274 Manager from the command line.
275 · --user=user_name
277 On Unix, the user name of the system account to use for starting
279 and running mysqlmanager. This option generates a warning and has
280 no effect unless you start mysqlmanager as root (so that it can
281 change its effective user ID), or as the named user. It is
282 recommended that you configure mysqlmanager to run using the same
283 account used to run the mysqld server. (“User” in this context
284 refers to a system login account, not a MySQL user listed in the
285 grant tables.)
286 · --username=user_name, -u user_name
288 Specify the user name for an entry to be added to or modified in
290 the password file. This option was added in MySQL 5.1.12.
291 · --version, -V
293 Display version information and exit.
295 · --wait-timeout=N
297 The number of seconds to wait for activity on an incoming
299 connection before closing it. The default is 28800 seconds (8
300 hours).
301 This option was added in MySQL 5.1.7. Before that, the timeout is
303 30 seconds and cannot be changed.
304
306 Important
307 MySQL Instance Manager has been deprecated and is removed in MySQL
308 5.5.
309 Instance Manager uses its standard configuration file unless it is
311 started with a --defaults-file option that specifies a different file.
312 On Windows, the standard file is my.ini in the directory where Instance
313 Manager is installed. On Unix, the standard file is /etc/my.cnf.
314 Instance Manager reads options for itself from the [manager] section of
316 the configuration file, and options for server instances from [mysqld]
317 or [mysqldN] sections. The [manager] section contains any of the
318 options listed in the section called “MYSQL INSTANCE MANAGER COMMAND
319 OPTIONS”, except for those specified as having to be given as the first
320 option on the command line. Here is a sample [manager] section:
321 # MySQL Instance Manager options section
323 [manager]
324 default-mysqld-path = /usr/local/mysql/libexec/mysqld
325 socket=/tmp/manager.sock
326 pid-file=/tmp/manager.pid
327 password-file = /home/cps/.mysqlmanager.passwd
328 monitoring-interval = 2
329 port = 1999
330 bind-address = 192.168.1.5
331 Each [mysqld] or [mysqldN] instance section specifies options given by
333 Instance Manager to a server instance at startup. These are mainly
334 common MySQL Server options (see Section 5.1.2, “Server Command
335 Options”). In addition, a [mysqldN] section can contain the options in
336 the following list, which are specific to Instance Manager. These
337 options are interpreted by Instance Manager itself; it does not pass
338 them to the server when it attempts to start that server.
339 Warning
341 The Instance Manager-specific options must not be used in a
342 [mysqld] section. If a server is started without using Instance
343 Manager, it will not recognize these options and will fail to start
344 properly.
345 · mysqld-path = path
347 The path name of the mysqld server binary to use for the server
349 instance.
350 · nonguarded
352 This option disables Instance Manager monitoring functionality for
354 the server instance. By default, an instance is guarded: At
355 Instance Manager start time, it starts the instance. It also
356 monitors the instance status and attempts to restart it if it
357 fails. At Instance Manager exit time, it stops the instance. None
358 of these things happen for nonguarded instances.
359 · shutdown-delay = seconds
361 The number of seconds Instance Manager should wait for the server
363 instance to shut down. The default value is 35 seconds. After the
364 delay expires, Instance Manager assumes that the instance is
365 hanging and attempts to terminate it. If you use InnoDB with large
366 tables, you should increase this value.
367 Here are some sample instance sections:
369 [mysqld1]
371 mysqld-path=/usr/local/mysql/libexec/mysqld
372 socket=/tmp/mysql.sock
373 port=3307
374 server_id=1
375 skip-stack-trace
376 core-file
377 log-bin
378 log-error
379 log=mylog
380 log-slow-queries
381 [mysqld2]
382 nonguarded
383 port=3308
384 server_id=2
385 mysqld-path= /home/cps/mysql/trees/mysql-5.1/sql/mysqld
386 socket = /tmp/mysql.sock5
387 pid-file = /tmp/hostname.pid5
388 datadir= /home/cps/mysql_data/data_dir1
389 language=/home/cps/mysql/trees/mysql-5.1/sql/share/english
390 log-bin
391 log=/tmp/fordel.log
392
394 Important
395 MySQL Instance Manager has been deprecated and is removed in MySQL
396 5.5.
397 This section discusses how Instance Manager starts server instances
399 when it starts. However, before you start Instance Manager, you should
400 set up a password file for it. Otherwise, you will not be able to
401 connect to Instance Manager to control it after it starts. For details
402 about creating Instance Manager accounts, see the section called
403 “INSTANCE MANAGER USER AND PASSWORD MANAGEMENT”.
404 On Unix, the mysqld MySQL database server normally is started with the
406 mysql.server script, which usually resides in the /etc/init.d/ folder.
407 That script invokes the mysqld_safe script by default. However, you can
408 use Instance Manager instead if you modify the /etc/my.cnf
409 configuration file by adding use-manager to the [mysql.server] section:
410 [mysql.server]
412 use-manager
413 Before MySQL 5.1.12, Instance Manager always tries to start at least
415 one server instance: When it starts, it reads its configuration file if
416 it exists to find server instance sections and prepare a list of
417 instances. Instance sections have names of the form [mysqld] or
418 [mysqldN], where N is an unsigned integer (for example, [mysqld1],
419 [mysqld2], and so forth).
420 After preparing the list of instances, Instance Manager starts the
422 guarded instances in the list. If there are no instances, Instance
423 Manager creates an instance named mysqld and attempts to start it with
424 default (compiled-in) configuration values. This means that the
425 Instance Manager cannot find the mysqld program if it is not installed
426 in the default location. (Section 2.1.5, “Installation Layouts”,
427 describes default locations for components of MySQL distributions.) If
428 you have installed the MySQL server in a nonstandard location, you
429 should create the Instance Manager configuration file.
430 The startup behavior just described is similar to that of mysqld_safe,
432 which always attempts to start a server. However, it lacks the
433 flexibility required for some operations because it is not possible to
434 run Instance Manager in such a way that it refrains from starting any
435 server instances. For example, you cannot invoke Instance Manager for
436 the purpose of configuring an instance without also starting it (a task
437 that a MySQL installer application might want to perform).
438 Consequently, MySQL 5.1.12 introduces the following changes:
439 · A new option, --mysqld-safe-compatible, may be used to cause
441 Instance Manager to run with startup behavior similar to that used
442 before MySQL 5.1.12: If Instance Manager finds a [mysqld] instance
443 section in the configuration file, it will start it. If Instance
444 Manager finds no [mysqld] section, it creates one using default
445 configuration values, writes a [mysqld] section to the
446 configuration file if it is accessible, and starts the mysqld
447 instance. Instance Manager also starts any other guarded instances
448 listed in the configuration file.
449 · Without --mysqld-safe-compatible, Instance Manager reads its
451 configuration file if it exists and starts instances for any
452 guarded instance sections that it finds. If there are none, it
453 starts no instances.
454 Instance Manager also stops all guarded server instances when it shuts
456 down.
457 The permissible options for [mysqldN] server instance sections are
459 described in the section called “MYSQL INSTANCE MANAGER CONFIGURATION
460 FILES”. In these sections, you can use a special
461 mysqld-path=path-to-mysqld-binary option that is recognized only by
462 Instance Manager. Use this option to let Instance Manager know where
463 the mysqld binary resides. If there are multiple instances, it may also
464 be necessary to set other options such as datadir and port, to ensure
465 that each instance has a different data directory and TCP/IP port
466 number. Section 5.6, “Running Multiple MySQL Instances on One
467 Machine”, discusses the configuration values that must differ for each
468 instance when you run multiple instance on the same machine.
469 Warning
471 The [mysqld] instance section, if it exists, must not contain any
472 Instance Manager-specific options.
473 The typical Unix startup/shutdown cycle for a MySQL server with the
475 MySQL Instance Manager enabled is as follows:
476 1. The /etc/init.d/mysql script starts MySQL Instance Manager.
478 2. Instance Manager starts the guarded server instances and monitors
480 them.
481 3. If a server instance fails, Instance Manager restarts it.
483 4. If Instance Manager is shut down (for example, with the
485 /etc/init.d/mysql stop command), it shuts down all server
486 instances.
487
489 Important
490 MySQL Instance Manager has been deprecated and is removed in MySQL
491 5.5.
492 The Instance Manager stores its user information in a password file. On
494 Windows, the default is mysqlmanager.passwd in the directory where
495 Instance Manager is installed. On Unix, the default file is
496 /etc/mysqlmanager.passwd. To specify a different location for the
497 password file, use the --password-file option.
498 If the password file does not exist or contains no password entries,
500 you cannot connect to the Instance Manager.
501 Note
503 Any Instance Manager process that is running to monitor server
504 instances does not notice changes to the password file. You must
505 stop it and restart it after making password entry changes.
506 Entries in the password file have the following format, where the two
508 fields are the account user name and encrypted password, separated by a
509 colon:
510 petr:*35110DC9B4D8140F5DE667E28C72DD2597B5C848
512 Instance Manager password encryption is the same as that used by MySQL
514 Server. It is a one-way operation; no means are provided for decrypting
515 encrypted passwords.
516 Instance Manager accounts differ somewhat from MySQL Server accounts:
518 · MySQL Server accounts are associated with a host name, user name,
520 and password (see Section 5.5.1, “User Names and Passwords”).
521 · Instance Manager accounts are associated with a user name and
523 password only.
524 This means that a client can connect to Instance Manager with a given
526 user name from any host. To limit connections so that clients can
527 connect only from the local host, start Instance Manager with the
528 --bind-address=127.0.0.1 option so that it listens only to the local
529 network interface. Remote clients will not be able to connect. Local
530 clients can connect like this:
531 shell> mysql -h 127.0.0.1 -P 2273
533 Before MySQL 5.1.12, the only option for creating password file entries
535 is --passwd, which causes Instance Manager to prompt for user name and
536 password values and display the resulting entry. You can save the
537 output in the /etc/mysqlmanager.passwd password file to store it. Here
538 is an example:
539 shell> mysqlmanager --passwd >> /etc/mysqlmanager.passwd
541 Creating record for new user.
542 Enter user name: mike
543 Enter password: mikepass
544 Re-type password: mikepass
545 At the prompts, enter the user name and password for the new Instance
547 Manager user. You must enter the password twice. It does not echo to
548 the screen, so double entry guards against entering a different
549 password than you intend (if the two passwords do not match, no entry
550 is generated).
551 The preceding command causes the following line to be added to
553 /etc/mysqlmanager.passwd:
554 mike:*BBF1F551DD9DD96A01E66EC7DDC073911BAD17BA
556 Use of the --password option fails if mysqlmanager is invoked directly
558 from an IBM 5250 terminal. To work around this, use a command like the
559 following from the command line to generate the password entry:
560 shell> mysql -B --skip-column-name \
562 -e ´SELECT CONCAT("user_name",":",PASSWORD("pass_val"));´
563 The output from the command can be used an entry in the
565 /etc/mysqlmanager.passwd file.
566 Beginning with MySQL 5.1.12, the --passwd option is renamed to
568 --print-password-line and there are several other options for managing
569 user accounts from the command line. For example, the --username and
570 --password options are available on the command line for specifying the
571 user name and password for an account entry. You can use them to
572 generate an entry with no prompting like this (type the command on a
573 single line):
574 shell> mysqlmanager --print-password-line
576 --username=mike --password=mikepass >> /etc/mysqlmanager.passwd
577 If you omit the --username or --password option, Instance Manager
579 prompts for the required value.
580 --print-password-line causes Instance Manager to send the resulting
582 account entry to its output, which you can append to the password file.
583 The following list describes other account-management options that
584 cause Instance Manager to operate directly on the password file. (These
585 options make Instance Manager scriptable for account-management
586 purposes.) For operations on the password file to succeed, the file
587 must exist and it must be accessible by Instance Manager. (The
588 exception is --clean-password-file, which creates the file if it does
589 not exist. Alternatively, if there is no password file, manually create
590 it as an empty file and ensure that its ownership and access modes
591 permit it to be read and written by Instance Manager.) The default
592 password file is used unless you specify a --password-file option.
593 To ensure consistent treatment of the password file, it should be owned
595 by the system account that you use for running Instance Manager to
596 manage server instances, and you should invoke it from that account
597 when you use it to manage accounts in the password file.
598 · Create a new user:
600 mysqlmanager --add-user --username=user_name [--password=password]
602 This command adds a new entry with the given user name and password
604 to the password file. The --username (or -u) option is required.
605 mysqlmanager prompts for the password if it is not given on the
606 command line with the --password (or -p) option. The command fails
607 if the user already exists.
608 · Drop an existing user:
610 mysqlmanager --drop-user --username=user_name
612 This command removes the entry with the given user name from the
614 password file. The user name is required. The command fails if the
615 user does not exist.
616 · Change the password for an existing user:
618 mysqlmanager --edit-user --username=user_name [--password=password]
620 This command changes the given user´s password in the password
622 file. The user name is required. mysqlmanager prompts for the
623 password it is not given on the command line. The command fails if
624 the user does not exist.
625 · List existing users:
627 mysqlmanager --list-users
629 This command lists the user names of the accounts in the password
631 file.
632 · Check the password file:
634 mysqlmanager --check-password-file
636 This command performs a consistency and validity check of the
638 password file. The command fails if there is something wrong with
639 the file.
640 · Empty the password file:
642 mysqlmanager --clean-password-file
644 This command empties the password file, which has the effect of
646 dropping all users listed in it. The option creates the password
647 file if it does not exist, so it can be used to initialize a new
648 password file to be used for other account-management operations.
649 Take care not to use this option to reinitialize a file containing
650 accounts that you do not want to drop.
651
653 Important
654 MySQL Instance Manager has been deprecated and is removed in MySQL
655 5.5.
656 To monitor the status of each guarded server instance, the MySQL
658 Instance Manager attempts to connect to the instance at regular
659 intervals using the MySQL_Instance_Manager@localhost user account with
660 a password of check_connection.
661 You are not required to create this account for MySQL Server; in fact,
663 it is expected that it will not exist. Instance Manager can tell that a
664 server is operational if the server accepts the connection attempt but
665 refuses access for the account by returning a login error. However,
666 these failed connection attempts are logged by the server to its
667 general query log (see Section 5.2.3, “The General Query Log”).
668 Instance Manager also attempts a connection to nonguarded server
670 instances when you use the SHOW INSTANCES or SHOW INSTANCE STATUS
671 command. This is the only status monitoring done for nonguarded
672 instances.
673 Instance Manager knows if a server instance fails at startup because it
675 receives a status from the attempt. For an instance that starts but
676 later crashes, Instance Manager receives a signal because it is the
677 parent process of the instance.
678 Beginning with MySQL 5.1.12, Instance Manager tracks instance states so
680 that it can determine which commands are permitted for each instance.
681 For example, commands that modify an instance´s configuration are
682 permitted only while the instance is offline.
683 Each instance is in one of the states described in the following table.
685 Guarded instances can be in any of the states. Nonguarded instances can
686 only be offline or online. Instance state information is displayed in
687 the status column of the SHOW INSTANCES and SHOW INSTANCE STATUS
688 commands.
689 ┌──────────┬─────────────────────────────┐
691 │State │ Meaning │
692 ├──────────┼─────────────────────────────┤
693 │offline │ The instance has not been │
694 │ │ started and is not │
695 │ │ running. │
696 ├──────────┼─────────────────────────────┤
697 │starting │ The instance is starting │
698 │ │ (initializing). Nonguarded │
699 │ │ instances cannot be │
700 │ │ in this │
701 │ │ state. A nonguarded │
702 │ │ instance goes directly │
703 │ │ from │
704 │ │ offline to │
705 │ │ online. │
706 ├──────────┼─────────────────────────────┤
707 │stopping │ The instance is stopping. │
708 │ │ Nonguarded instances │
709 │ │ cannot be in this state. │
710 │ │ A │
711 │ │ nonguarded instance goes │
712 │ │ directly from online to │
713 │ │ offline, │
714 │ │ or stays offline if │
715 │ │ startup fails. │
716 ├──────────┼─────────────────────────────┤
717 │online │ The instance has started │
718 │ │ and is running. │
719 ├──────────┼─────────────────────────────┤
720 │failed │ The instance was online │
721 │ │ but it crashed and is │
722 │ │ being restarted by │
723 │ │ Instance │
724 │ │ Manager, or else the │
725 │ │ instance failed to start │
726 │ │ at all and │
727 │ │ Instance Manager is again │
728 │ │ attempting to start │
729 │ │ it. │
730 │ │ Nonguarded instances │
731 │ │ cannot be in this state. │
732 ├──────────┼─────────────────────────────┤
733 │crashed │ Instance Manager failed to │
734 │ │ start the instance after │
735 │ │ several attempts. │
736 │ │ (Instance │
737 │ │ Manager will try again │
738 │ │ later.) Nonguarded │
739 │ │ instances │
740 │ │ cannot be in this state. │
741 ├──────────┼─────────────────────────────┤
742 │abandoned │ Instance Manager was not │
743 │ │ able to start the │
744 │ │ instance, has given up, │
745 │ │ and │
746 │ │ will make │
747 │ │ no further attempts until │
748 │ │ instructed │
749 │ │ otherwise. │
750 │ │ To tell Instance Manager │
751 │ │ to try again, you │
752 │ │ must first │
753 │ │ use STOP INSTANCE to put │
754 │ │ the │
755 │ │ instance in offline state, │
756 │ │ and then use │
757 │ │ START │
758 │ │ INSTANCE to start the │
759 │ │ instance. │
760 │ │ If it is │
761 │ │ necessary to make │
762 │ │ configuration changes for │
763 │ │ the │
764 │ │ instance, │
765 │ │ you must do so after │
766 │ │ putting the instance │
767 │ │ offline │
768 │ │ and before starting it. │
769 │ │ (Instance Manager │
770 │ │ accepts │
771 │ │ configuration-changing │
772 │ │ commands only for offline │
773 │ │ instances.) │
774 │ │ Nonguarded instances │
775 │ │ cannot be in this │
776 │ │ state. │
777 └──────────┴─────────────────────────────┘
778
780 Important
781 MySQL Instance Manager has been deprecated and is removed in MySQL
782 5.5.
783 After you set up a password file for the MySQL Instance Manager and
785 Instance Manager is running, you can connect to it. The MySQL
786 client/server protocol is used to communicate with the Instance
787 Manager. For example, you can connect to it using the standard mysql
788 client program:
789 shell> mysql --port=2273 --host=im.example.org --user=mysql --password
791 Instance Manager supports the version of the MySQL client/server
793 protocol used by the client tools and libraries distributed with MySQL
794 4.1 or later, so other programs that use the MySQL C API also can
795 connect to it.
796
798 Important
799 MySQL Instance Manager has been deprecated and is removed in MySQL
800 5.5.
801 After you connect to MySQL Instance Manager, you can issue commands.
803 The following general principles apply to Instance Manager command
804 execution:
805 · Commands that take an instance name fail if the name is not a valid
807 instance name.
808 · Commands that take an instance name (other than CREATE INSTANCE)
810 fail if the instance does not exist.
811 · As of MySQL 5.1.12, commands for an instance require that the
813 instance be in an appropriate state. You cannot configure or start
814 an instance that is not offline. You cannot start an instance that
815 is online.
816 · Instance Manager maintains information about instance configuration
818 in an internal (in-memory) cache. Initially, this information comes
819 from the configuration file if it exists, but some commands change
820 the configuration of an instance. Commands that modify the
821 configuration file fail if the file does not exist or is not
822 accessible to Instance Manager.
823 As of MySQL 5.1.12, configuration-changing commands modify both the
825 in-memory cache and the server instance section recorded in the
826 configuration file to maintain consistency between them. For this
827 to occur, the instance must be offline and the configuration file
828 must be accessible and not malformed. If the configuration file
829 cannot be updated, the command fails and the cache remains
830 unchanged.
831 · On Windows, the standard file is my.ini in the directory where
833 Instance Manager is installed. On Unix, the standard configuration
834 file is /etc/my.cnf. To specify a different configuration file,
835 start Instance Manager with the --defaults-file option.
836 · If a [mysqld] instance section exists in the configuration file, it
838 must not contain any Instance Manager-specific options (see the
839 section called “MYSQL INSTANCE MANAGER CONFIGURATION FILES”).
840 Therefore, you must not add any of these options if you change the
841 configuration for an instance named mysqld.
842 The following list describes the commands that Instance Manager
844 accepts, with examples.
845 · CREATE INSTANCE instance_name [option_name[=option_value], ...]
847 This command configures a new instance by creating an
849 [instance_name] section in the configuration file. The command
850 fails if instance_name is not a valid instance name or the instance
851 already exists.
852 The created section instance is empty if no options are given.
854 Otherwise, the options are added to the section. Options should be
855 given in the same format used when you write options in option
856 files. (See Section 4.2.3.3, “Using Option Files” for a description
857 of the permissible syntax.) If you specify multiple options,
858 separate them by commas.
859 For example, to create an instance section named [mysqld98], you
861 might write something like this were you to modify the
862 configuration file directly:
863 [mysqld98]
865 basedir=/var/mysql98
866 To achieve the same effect using CREATE INSTANCE, issue this
868 command to Instance Manager:
869 mysql> CREATE INSTANCE mysqld98 basedir="/var/mysql98";
871 Query OK, 0 rows affected (0,00 sec)
872 CREATE INSTANCE creates the instance but does not start it.
874 If the instance name is the (deprecated) name mysqld, the option
876 list cannot include any options that are specific to Instance
877 Manager, such as nonguarded (see the section called “MYSQL INSTANCE
878 MANAGER CONFIGURATION FILES”).
879 This command was added in MySQL 5.1.12.
881 · DROP INSTANCE instance_name
883 This command removes the configuration for instance_name from the
885 configuration file.
886 mysql> DROP INSTANCE mysqld98;
888 Query OK, 0 rows affected (0,00 sec)
889 The command fails if instance_name is not a valid instance name,
891 the instance does not exist, or is not offline.
892 This command was added in MySQL 5.1.12.
894 · START INSTANCE instance_name
896 This command attempts to start an offline instance. The command is
898 asynchronous; it does not wait for the instance to start.
899 mysql> START INSTANCE mysqld4;
901 Query OK, 0 rows affected (0,00 sec)
902 · STOP INSTANCE instance_name
904 This command attempts to stop an instance. The command is
906 synchronous; it waits for the instance to stop.
907 mysql> STOP INSTANCE mysqld4;
909 Query OK, 0 rows affected (0,00 sec)
910 · SHOW INSTANCES
912 Shows the names and status of all loaded instances.
914 mysql> SHOW INSTANCES;
916 +---------------+---------+
917 | instance_name | status |
918 +---------------+---------+
919 | mysqld3 | offline |
920 | mysqld4 | online |
921 | mysqld2 | offline |
922 +---------------+---------+
923 · SHOW INSTANCE STATUS instance_name
925 Shows status and version information for an instance.
927 mysql> SHOW INSTANCE STATUS mysqld3;
929 +---------------+--------+---------+
930 | instance_name | status | version |
931 +---------------+--------+---------+
932 | mysqld3 | online | unknown |
933 +---------------+--------+---------+
934 · SHOW INSTANCE OPTIONS instance_name
936 Shows the options used by an instance.
938 mysql> SHOW INSTANCE OPTIONS mysqld3;
940 +---------------+---------------------------------------------------+
941 | option_name | value |
942 +---------------+---------------------------------------------------+
943 | instance_name | mysqld3 |
944 | mysqld-path | /home/cps/mysql/trees/mysql-4.1/sql/mysqld |
945 | port | 3309 |
946 | socket | /tmp/mysql.sock3 |
947 | pid-file | hostname.pid3 |
948 | datadir | /home/cps/mysql_data/data_dir1/ |
949 | language | /home/cps/mysql/trees/mysql-4.1/sql/share/english |
950 +---------------+---------------------------------------------------+
951 · SHOW instance_name LOG FILES
953 The command lists all log files used by the instance. The result
955 set contains the path to the log file and the log file size. If no
956 log file path is specified in the instance section of the
957 configuration file (for example, log=/var/mysql.log), the Instance
958 Manager tries to guess its placement. If Instance Manager is unable
959 to guess the log file placement you should specify the log file
960 location explicitly by using a log option in the appropriate
961 instance section of the configuration file.
962 mysql> SHOW mysqld LOG FILES;
964 +-------------+------------------------------------+----------+
965 | Logfile | Path | Filesize |
966 +-------------+------------------------------------+----------+
967 | ERROR LOG | /home/cps/var/mysql/owlet.err | 9186 |
968 | GENERAL LOG | /home/cps/var/mysql/owlet.log | 471503 |
969 | SLOW LOG | /home/cps/var/mysql/owlet-slow.log | 4463 |
970 +-------------+------------------------------------+----------+
971 SHOW ... LOG FILES displays information only about log files. If a
973 server instance uses log tables (see Section 5.2.1, “Selecting
974 General Query and Slow Query Log Output Destinations”), no
975 information about those tables is shown.
976 Log options are described in Section 5.1.2, “Server Command
978 Options”.
979 · SHOW instance_name LOG {ERROR | SLOW | GENERAL}
981 size[,offset_from_end]
982 This command retrieves a portion of the specified log file. Because
984 most users are interested in the latest log messages, the size
985 parameter defines the number of bytes to retrieve from the end of
986 the log. To retrieve data from the middle of the log file, specify
987 the optional offset_from_end parameter. The following example
988 retrieves 21 bytes of data, starting 23 bytes before the end of the
989 log file and ending 2 bytes before the end:
990 mysql> SHOW mysqld LOG GENERAL 21, 2;
992 +---------------------+
993 | Log |
994 +---------------------+
995 | using password: YES |
996 +---------------------+
997 · SET instance_name.option_name[=option_value]
999 This command edits the specified instance´s configuration section
1001 to change or add instance options. The option is added to the
1002 section is it is not already present. Otherwise, the new setting
1003 replaces the existing one.
1004 mysql> SET mysqld2.port=3322;
1006 Query OK, 0 rows affected (0.00 sec)
1007 As of MySQL 5.1.12, you can specify multiple options (separated by
1009 commas), and SET can be used only for offline instances. Each
1010 option must indicate the instance name:
1011 mysql> SET mysqld2.port=3322, mysqld3.nonguarded;
1013 Query OK, 0 rows affected (0.00 sec)
1014 Before MySQL 5.1.12, only a single option can be specified. Also,
1016 changes made to the configuration file do not take effect until the
1017 MySQL server is restarted. In addition, these changes are not
1018 stored in the instance manager´s local cache of instance settings
1019 until a FLUSH INSTANCES command is executed.
1020 · UNSET instance_name.option_name
1022 This command removes an option from an instance´s configuration
1024 section.
1025 mysql> UNSET mysqld2.port;
1027 Query OK, 0 rows affected (0.00 sec)
1028 As of MySQL 5.1.12, you can specify multiple options (separated by
1030 commas), and UNSET can be used only for offline instances. Each
1031 option must indicate the instance name:
1032 mysql> UNSET mysqld2.port, mysqld4.nonguarded;
1034 Query OK, 0 rows affected (0.00 sec)
1035 Before MySQL 5.1.12, only a single option can be specified. Also,
1037 changes made to the configuration file do not take effect until the
1038 MySQL server is restarted. In addition, these changes are not
1039 stored in the instance manager´s local cache of instance settings
1040 until a FLUSH INSTANCES command is executed.
1041 · FLUSH INSTANCES
1043 As of MySQL 5.1.12, FLUSH INSTANCES cannot be used unless all
1045 instances are offline. The command causes Instance Manager to
1046 reread the configuration file, update its in-memory configuration
1047 cache, and start any guarded instances.
1048 Before MySQL 5.1.12, this command forces Instance Manager reread
1050 the configuration file and to refresh internal structures. This
1051 command should be performed after editing the configuration file.
1052 The command does not restart instances.
1053 mysql> FLUSH INSTANCES;
1055 Query OK, 0 rows affected (0.04 sec)
1056
1058 Copyright © 1997, 2011, Oracle and/or its affiliates. All rights
1059 reserved.
1060 This documentation is free software; you can redistribute it and/or
1062 modify it only under the terms of the GNU General Public License as
1063 published by the Free Software Foundation; version 2 of the License.
1064 This documentation is distributed in the hope that it will be useful,
1066 but WITHOUT ANY WARRANTY; without even the implied warranty of
1067 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1068 General Public License for more details.
1069 You should have received a copy of the GNU General Public License along
1071 with the program; if not, write to the Free Software Foundation, Inc.,
1072 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA or see
1073 http://www.gnu.org/licenses/.
1074
1077 For more information, please refer to the MySQL Reference Manual, which
1078 may already be installed locally and which is also available online at
1079 http://dev.mysql.com/doc/.
1080
1082 Oracle Corporation (http://dev.mysql.com/).
1083MySQL 5.1 10/26/2011 MYSQLMANAGER(8)