oak-purge-master-logs

NAME

oak-purge-master-logs: purge master logs, depending on the state of replicating slaves.

SYNOPSIS

Retain only three binary logs:
oak-purge-master-logs --retain-logs=3
Retain three binary logs, expect two slaves, purge logs even if slaves are not up to date:
oak-purge-master-logs --retain-logs=3 --expect-num-slaves=2 --pro-master
Retain at least three binary logs, expect at least two slaves, do not delete logs which were not read by all slaves, abort if less than two slaves are found:
oak-purge-master-logs -r 3 --expect-num-slaves=2 --pro-slaves
Retain at least three binary logs, expect two slaves, do not delete logs which were not read by at least one slave:
oak-purge-master-logs -r 3 -n 2 --pro-master --pro-slaves
Same as above, but first flush logs:
oak-purge-master-logs --flush-logs --retain-logs=3 --expect-num-slaves=2 --pro-master --pro-slaves --print-only
Same as above, do not actually purge, just print out the PURGE statement:
oak-purge-master-logs --flush-logs --retain-logs=3 --expect-num-slaves=2 --pro-master --pro-slaves --print-only
Same as above, provide connection parameters, prompt for password:
oak-purge-master-logs --host=192.168.2.103 --user=root --ask-pass --socket=/tmp/mysql.sock -f -r 3 -n 2 --pro-master --pro-slaves
Same as above, use defaults file:
oak-purge-master-logs --defaults-file=/home/myuser/.my-oak.cnf -f -r 3 -n 2 --pro-master --pro-slaves

DESCRIPTION

oak-purge-master-logs is a sophisticated tool which purges master logs while considering the replicating slaves. Purging master logs is essential in order to maintain free disk space on the master. However, purging logs which have not yet been replicated to slaves (due to slave lag, or temporary being offline) will break slave replication. This utility can handle the trade off between the master's space requirement and the slaves' replication requirement. Breaking of replication is undesired, as it it may be a lengthy process to restore it. There are essentially three modes in which this tool can be operated:
  • --pro-master: the mater gets the higher priority. Master logs files will be purged even if some or all slaves are not up to date. When master disk space is low, this may be a proper setting.
  • --pro-slaves: slaves get the higher priority: oak-purge-master-logs will only purge logs files which are not required by any replicating slave. This means it ensures that all slaves will safely continue replicating. When master is high on disk space, this is the proper setting.
  • --pro-master with --pro-slaves: the combination of the two flags ensures that at least one slave is considered when purging master logs. This means that after running the utility, at least one slave will keep replicating. This setting is appropriate when master disk space is reasonable, and when at least one slave is known to be functional (while others may go offline for long periods, for example). Restoring replication on lost slaves when an existing, working replication is present is relatively easy and non-interrupting.
With --print-only, nothing is actually performed: instead, the PURGE statement is printed to standard output. For this utility to run, the SUPER, REPLICATION CLIENT privileges are required.

OPTIONS

--ask-pass

Prompt for password. The same password is expected to apply for the master and the slaves.

--defaults-file=DEFAULTS_FILE

Read from MySQL configuration file. Overrides --user, --password, --socket, --port.

The same user name & password are expected to apply for the master and the slaves.

Configuration needs to be in the following format:

[client]
user=my_user
password=my_pass
socket=/tmp/mysql.sock
port=3306

-f, --flush-logs

Perform FLUSH LOGS on startup

-H HOST, --host=HOST

MySQL master host (default: localhost)

-n EXPECT_NUM_SLAVES, --expect-num-slaves=EXPECT_NUM_SLAVES

Number of slaves to expect (default: 0). When --pro-slaves flag is specified, and less than expect-num-slaves slaves are found, master logs files are not purged.

-p PASSWORD, --password=PASSWORD

MySQL password. The same password is expected to apply for the master and the slaves.

-P PORT, --port=PORT

TCP/IP port (default: 3306)

--pro-master

Force purging of logs, even if slaves are not up to date and will cease to replicate (this may ensure that disk space on master does not run out).

See also: --pro-slaves together with --pro-master

--pro-slaves

Do not purge master logs which are not replicated by all slaves. This will ensure that even if slaves are lagging far behind, replication is not broken: master will keep all required logs to maintain replication for all slaves.

Together with --pro-master: master logs may be purged only as long as there is at least one slave whose replication will not break.

-r RETAIN_LOGS, --retain-logs=RETAIN_LOGS

Number of logs to retain on master (default: 5). The utility will keep at least that many logs files on master.

--sentinel=SENTINEL_FILE

When the given file exists, oak-purge-master-logs exits without doing anything. Default: /tmp/oak-purge-master-logs.sentinel

--skip-show-slave-hosts

When SHOW SLAVE HOSTS returns rows, these are considered the only slave hosts. Otherwise slaves are found looking at SHOW PROCESSLIST. With --skip-show-slave-hosts, only SHOW PROCESSLIST is used.

-S SOCKET, --socket=SOCKET

MySQL socket file. Only applies when host is localhost

-u USER, --user=USER

MySQL user. The same user is expected to apply for the master and the slaves.

ENVIRONMENT

Requires MySQL 5.0 or newer, python 2.3 or newer. python-mysqldb must be installed in order to use this tool. You can
apt-get install python-mysqldb
or
yum install mysql-python

SEE ALSO

oak-show-replication-status

LICENSE

This tool is released under the BSD license. 
Copyright (c) 2008 - 2010, Shlomi Noach
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of the organization nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

AUTHOR

Shlomi Noach
 
openark kit documentation