Backup operations: backup, backup-and-apply-log, backup-to-image

Apply operations: apply-log, apply-incremental-backup

Restore operations: copy-back, copy-back-and-apply-log

Validation operation: validate

Single-file backup operations: image-to-backup-dir, backup-dir-to-image, list-image, extract

The following standard options also exist for the mysql command. Full descriptions for these options can be found in the MySQL reference manual, accessible through, e.g., Server Option and Variable Reference. These options must be specified ahead of any other mysqlbackup options, including the rest of the standard options:

--print-defaults             Print the program argument list and exit.
--no-defaults                Don't read default options from any option file.
--defaults-file=PATH         Only read default options from the given file. It has to be the first option to be specified, if used. 
--defaults-extra-file=PATH   Read this file after the global files are read.
--defaults-group-suffix=str  Also read option groups with the usual names and a suffix of str.  

The following options are also common between mysqlbackup and mysql, and full descriptions for them can be found in the MySQL reference manual, accessible through, e.g., Server Option and Variable Reference. However, mysqlbackup does not accept any short forms for these options as mysql does (for example, you must use --help instead of -h for mysqlbackup):

--help      Display help. 
--version   Display version information
--verbose   Print more verbose information. 
--debug     Print debug information.

More standard options are available for mysqlbackup:

--force       Force operations such as overwrite files, create backup directory.
--trace=level Trace level of messages by mysqlbackup.

--force: By default, some of the operations halt rather than overwrite any user data or log files when told to write to existing files. --force allows the overwriting of InnoDB data and log files during the apply-log and apply-incremental-backup operations and allows the replacing of an image file during an backup-to-image or backup-dir-to-image option. For all other operations, the --force option is rejected with an error message.

--trace=level

Trace level of mysqlbackup messages. The permissible levels, in the order of increasing fineness, are:

--no-connection

The --no-connection option supersedes the other connection options and uses file-level operations to perform the backup. When you use this option, you must specify in the configuration file or on the command line many options whose values are normally retrieved automatically through the database connection.

--connect-if-online

By default, a database connection is used for backup operations both during the initial stage to retrieve source repository configuration, and to lock tables while copying non-InnoDB data. This option allows mysqlbackup to make connection attempts in both phases, but continues even if the connection cannot be established. If a connection cannot be established, the processing is the same as with the --no-connection option. This option can be useful in emergency situations: for example, when the database server goes down during the backup operation.

Backup creation operations: backup, backup-and-apply-log, backup-to-image.

Restore operations: copy-back, copy-back-and-apply-log.

datadir=PATH

This is the datadir value used by the MySQL instance. The .frm files live here inside subdirectories named after the databases inside the instance.

When a database connection exists, the value is retrieved automatically and overrides any value you specify. This is a crucial parameter for both the MySQL server and MySQL Enterprise Backup.

innodb_data_home_dir=PATH

Specifies the directory where InnoDB data files live. Usually the same as datadir, but can be different.

This parameter, together with innodb_data_file_path=SIZE, determines where the InnoDB data files such as ibdata1, ibdata2, and so on, are situated within the MySQL server.

Typically, you do not need to specify this option, because its value is retrieved automatically using the database connection.

Its value is derived as follows:

innodb_data_file_path=VALUE

Specifies InnoDB data file names and sizes. Examples:

ibdata1:32M;ibdata2:32M:autoextend
/abs/path/ibdata1:32M:autoextend
innodb-dir/ibdata1:32M:autoextend

When a database connection exists, the value is retrieved automatically and overrides any value you specify.

This parameter together with innodb_data_home_dir determines where the InnoDB data files (such as ibdata1, ibdata2, and so on) live in server repository.

Typically, you do not need to specify this option, because its value is retrieved automatically using the database connection. If no database connection is available, you must specify it.

Whether the initial filename begins with a / character or not, the files are located relative to the innodb_data_home_dir value.

innodb_log_group_home_dir=PATH

Specifies where InnoDB logs live within the server repository. Usually the same as datadir, but can be different.

Its value is derived as follows:

innodb_log_files_in_group=N

Specifies the number of InnoDB log files before being rotated.

Typically, you do not need to specify this option, because its value is retrieved automatically using the database connection. If no database connection is available, you must specify it.

When a database connection exists, the value is retrieved automatically and overrides any value you specify.

innodb_log_file_size=SIZE

Specifies maximum single InnoDB log file size before switching to next log file. Example: 20M.

Typically, you do not need to specify this option, because its value is retrieved automatically using the database connection. If no database connection is available, you must specify it.

When a database connection exists, the value is retrieved automatically and overrides any value you specify.

innodb_page_size=SIZE

Specifies the page size for all InnoDB tablespaces.

Typically, you do not need to specify this option, because its value is retrieved automatically using the database connection. If no database connection is available, you must specify it.

When a database connection exists, the value is retrieved automatically and overrides any value you specify.

innodb_checksum_algorithm=NAME

Specifies the name of the checksum algorithm used for validating InnoDB tablespaces. Default is innodb.

Typically, you do not need to specify this option, because its value is retrieved automatically using the database connection. If no database connection is available, you must specify it.

When a database connection exists, the value is retrieved automatically and overrides any value you specify.

Backup creation operations: backup, backup-and-apply-log, backup-to-image.

Restore operations: copy-back, copy-back-and-apply-log.

--backup_dir=PATH

Same as --backup-dir. The directory under which to store the backup data. This is a crucial parameter required for most kinds of backup operations. It cannot be a subdirectory of the directory specified by --datadir. An additional level of subdirectory is created when the --with-timestamp option is also specified.

Also, when restoring a single-file backup with copy-back-and-apply-log, --backup-dir is used for supplying the location of a folder that will be used for storing temporary files produced during the restoration process.

backup_innodb_data_home_dir=PATH

Specifies the directory where backup InnoDB data files live. Usually same as backup-dir, but can be different.

This parameter together with backup_innodb_data_file_path determines where the InnoDB data files (such as ibdata1, ibdata2, ...) are stored inside the backup directory structure.

This parameter is applicable only for backup operations, not restore.

For the backup operations (such as backup, backup-and-apply-log, backup-to-image), the value of the backup destination directory is derived as follows:

To make it easy to relocate the backup directory and avoid editing the backup-my.cnf file, the backup operation writes this value into backup-my.cnf only if it is different than the backup-dir value, and using a relative path if possible.

For backup-to-image operations, the final value of the backup_innodb_data_home_dir option must be a relative path, so that the single-file backup is machine-independent.

backup_innodb_data_file_path=VALUE

Specifies InnoDB data file names and sizes. Examples:

ibdata1:32M;ibdata2:32M:autoextend
/abs/path/ibdata1:32M:autoextend
innodb-dir/ibdata1:32M:autoextend

This parameter together with backup_innodb_data_home_dir determines where the InnoDB data files (such as ibdata1, ibdata2, ...) live in the backup repository.

Within the backup directory, any data files specified with relative paths are located relative to the backup_dir path. Any data files specified with absolute paths are placed inside the backup_innodb_data_home directory.

When the parameter is not specified, it inherits the value from the value of the innodb_data_file_path option. If both source and destination attempt to use an absolute path that resolve to the same files, the backup is cancelled.

To specify absolute paths for InnoDB datafiles in backup, you must also set the backup_innodb_data_home option to "".

backup_innodb_log_group_home_dir=PATH

Specifies where backup InnoDB logs live. Usually the same as backup-dir, but can be different.

The names of the log files are fixed and not reconfigurable.

This parameter is applicable only for backup operations (not restore).

The backup operation uses this value and writes it as innodb_log_group_home_dir=value in backup-my.cnf.

For copy-back and apply-log operations, innodb_log_group_home_dir in backup-my.cnf is treated in a way that is compatible with how it was created.

backup_innodb_log_files_in_group=N

Specifies the number of InnoDB log files in backup before being rotated. Example: 5.

Usually same as innodb_log_files_in_group, but can be different.

The value for this parameter is derived as:

backup_innodb_log_file_size=SIZE

Specifies maximum single InnoDB log file size in backup before switching to next log file. Example: 20M.

Usually the same as innodb_log_file_size, but can be different.

The value for this parameter is derived as:

backup_innodb_page_size=SIZE

The page size for all InnoDB tablespaces in a MySQL instance. The page size must be the same value as in MySQL instance. By default, it assumes the innodb page size in server.

backup_innodb_checksum_algorithm=NAME

The name of the checksum algorithm used for validating InnoDB tablespaces. Default is 'innodb'.

backup_innodb_undo_directory=PATH

The relative or absolute directory path where InnoDB creates separate tablespaces for the undo logs. Typically used to place those logs on a different storage device.

backup_innodb_undo_logs=NUMBER

Number of rollback segments in the system tablespace that InnoDB uses within a transaction. This setting is appropriate for tuning performance if you observe mutex contention related to the undo logs.

backup_innodb_undo_tablespaces=NUMBER

The number of tablespace files that the undo logs are divided between, when you use a non-zero innodb_undo_logs setting. By default, all the undo logs are part of the system tablespace and the system tablespace will always contain one undo tablespace in addition to those configured by innodb_undo_tablespaces.

--with-timestamp

Creates a subdirectory underneath the backup directory, with a name formed from the timestamp of the backup operation. Useful to maintain a single backup directory containing many backup snapshots.

Default: no timestamped subdirectory is created. To reuse the same backup directory for a new backup, either remove the previous backup files manually or specify the --force option to overwrite them.

--no-history-logging

Turns off the recording of backup progress and history in logging tables inside the backed-up database. See Section 11.3, “Using the MySQL Enterprise Backup Logs” for details about these tables.

Default: history logging is enabled. When --no-connection is specified, history logging is automatically disabled. When --connect-if-online is specified, history logging only works if a database connection is successfully established during the backup.

--comments=STRING

Specifies a comment string that describes or identifies the backup. Surround multi-word comments with appropriate quotation marks. The string is saved in a file meta/comments.txt in the backup. For example: --comments="Backup of HR data on 2010/12/10".

--comments-file=PATH

Specifies path to a file containing comments describing the backup. This file is saved as meta/comments.txt in the backup. For example: --comments-file=/path/to/comments.txt.

This option overrides the --comments option if both are specified.

--compress

Create backup in compressed format. For a regular backup, only the InnoDB data files are compressed, and they bear the .ibz extension after the compression. Similarly, for a single-image backup, only the InnoDB data files inside the backup image are compressed.

Default: compression is disabled.

--compress-method=ALGORITHM

Specifies the compression algorithm. The supported arguments for the option and the algorithms they represent are:

Default: lz4. Explicitly specifying a value for the option through a configuration file or command line automatically enables the --compress option.

--compress-level=LEVEL

Specifies the level of compression, ranging from “0” to “9”: “0 ”disables compression; “1” is fastest compression, and “9” is highest (and slowest) compression. The option is only meaningful for compression using the ZLIB or LZMA algorithm; it is ignored when any other algorithms are selected by the --compress-method option.

Default: 1 (lowest and fastest compression). Explicitly specifying a non-zero value through a configuration file or command line automatically enables the --compress option.

--uncompress

When used with the apply-log or copy-back-and-apply-log operation, uncompresses the compressed backup before applying the InnoDB log.

--incremental

Specifies that the associated backup or backup-to-image operation is incremental. Also requires either the --incremental-base option, or the combination of the --start-lsn and --incremental-backup-dir options.

The incremental aspect applies only to InnoDB tables. By default, all non-InnoDB and .frm files are also included in incremental backup. To exclude non-InnoDB data in an incremental backup, use the --only-innodb option.

--incremental-with-redo-log-only

Specifies an alternative form of incremental backup for a backup or backup-to-image operation. Also requires either the --incremental-base option, or the combination of the --start-lsn and --incremental-backup-dir options.

The incremental backup performed by this option has different performance characteristics and operational limitations than with the --incremental option:

As with the --incremental option, the incremental aspect applies only to InnoDB tables. By default, all non-InnoDB and .frm files are also included in incremental backup. To exclude non-InnoDB data in an incremental backup, use the --only-innodb option.

--incremental-base=mode:argument

With this option, the mysqlbackup retrieves the information needed to perform incremental backups from the metadata inside the backup directory rather than from the --start-lsn option. It saves you from having to specify an ever-changing, unpredictable LSN value when doing a succession of incremental backups. Instead, you specify a way to locate the previous backup directory through the combination of mode and argument in the option syntax. The alternatives are:

--start-lsn=LSN

In an incremental backup, specifies the highest LSN value included in a previous backup. You can get this value from the output of the previous backup operation, or from the backup_history table's end_lsn column for the previous backup operation. Always used in combination with the --incremental option; not needed when you use the --incremental-base option; not recommended when you use the --incremental-with-redo-log-only mechanism for incremental backups.

--incremental-backup-dir=PATH

Specifies the location under which to store data from an incremental backup. This is the same location you specify with --incremental-base if you use that option for a subsequent incremental backup.

--include-tables=REGEXP

Include for backup or restoration only those tables (both innodb and non-innodb) whose fully qualified names (in the form of db_name.table_name) match the regular expression REGEXP. The regular expression syntax used is the extended form specified in the POSIX 1003.2 standard. For example, --include-tables=^mydb\.t[12]$ matches the tables t1 and t2 in the database mydb. On Unix-like systems, quote the regular expression appropriately to prevent interpretation of shell meta-characters. Some limitations apply when using the option to select database names or file names that contain special characters (spaces, dashes, periods, etc.); see this description in Appendix A, MySQL Enterprise Backup Limitations for details. mysqlbackup throws an error when the option is used without a regular expression being supplied with it.

While the option can be used for different kinds of backups, selective restore is only supported for backups created using transportable tablespaces (TTS) (that is, backups created with the --use-tts option).

The option cannot be used together with the legacy --include, --databases, --databases-list-file, or --only-innodb-with-frm option.

When used together with the --exclude-tables option, --include-tables is applied first, meaning mysqlbackup first selects all tables specified by --include-tables and then excludes from the set those tables specified by --exclude-tables.

--exclude-tables=REGEXP

Exclude for backup or restoration all tables (both innodb and non-innodb) whose fully qualified names (in the form of db_name.table_name) match the regular expression REGEXP. The regular expression syntax is the extended form specified in the POSIX 1003.2 standard. For example, --exclude-tables=^mydb\.t[12]$ matches the tables t1 and t2 in the database mydb. On Unix-like systems, quote the regular expression appropriately to prevent interpretation of shell meta-characters. Some limitations apply when using the option to select database names or file names that contain special characters (spaces, dashes, periods, etc.); see this description in Appendix A, MySQL Enterprise Backup Limitations for details. mysqlbackup throws an error when the option is used without a regular expression being supplied with it.

While the option can be used for different kinds of backups, selective restore is only supported for backups created using transportable tablespaces (TTS) (that is, backups created with the --use-tts option).

The option cannot be used together with the --include, --databases, --databases-list-file, or --only-innodb-with-frm option.

When used together with the --include-tables option, --include-tables is applied first, meaning mysqlbackup first select all tables specified by --include-tables, and then exclude from the set those tables specified by --exclude-tables for backup.

--only-known-file-types

For back up only. By default, all files in the database subdirectories under the data directory of the server are included in the backup (see Section 1.4, “Files that Are Backed Up” for details). If the --only-known-file-types option is specified, mysqlbackup only backs up those types of files that are data files for MySQL or its built-in storage engines, which have the following extensions:

--only-innodb

For back up only. Back up only InnoDB data and log files. All files created by other storage engines are excluded. Typically used when no connection to mysqld is allowed or when there is no need to copy MyISAM.

The option is not compatible with the --slave-info option.

Default: backups include files from all storage engines.

--use-tts[={with-minimum-locking|with-full-locking}]

Enable selective backup of InnoDB tables using transportable tablespaces (TTS). This is to be used in conjunction with the --include-tables and --exclude-tables options to select the InnoDB tables to be backed up by regular expressions. Using TTS for backups offers the following advantages:

However, the option has the following limitations:

There are two possible values for the option:

Default: back up with minimum locking

To use the --use-tts option, extra privileges are required of the user through which mysqlbackup connects to the server; see Section 3.1.2, “Grant MySQL Privileges to Backup Administrator” for details.

There are some special requirements for restoring backups created with the --use-tts option; see Restoring Backups Created with the --use-tts Option for details.

--include=REGEXP

This option is for filtering InnoDB tables for backup. The InnoDB tables' fully qualified names are checked against the regular expression specified by the option. If the REGEXP matches db_name.table_name, the table is included. The regular expression syntax used is the extended form specified in the POSIX 1003.2 standard. For example, --include=mydb\.t[12] matches the tables t1 and t2 in the database mydb. mysqlbackup throws an error when the option is used without a regular expression being supplied with it.

This option only applies to InnoDB tables created with the MySQL option innodb_file_per_table enabled (which is the default setting for MySQL 5.6 and after), in which case the tables are in separate files that can be included or excluded from the backup. All tables in the InnoDB system tablespace are always backed up.

When no InnoDB table names match the specified regular expression, an error is thrown with a message indicating there are no matches.

Default: Backs up all InnoDB tables.

--databases=LIST

Specifies the list of non-InnoDB tables to back up. The argument specifies a space-separated list of database or table names of the following form:

"db_name[.table_name] db_name1[.table_name1] ...".

If the specified values do not match any database or table, then no non-InnoDB data files are backed up. See Making a Partial Backup with the Legacy Options for details.

By default, all non-InnoDB tables from all databases are backed up.

--databases-list-file=PATH

Specifies the pathname of a file that lists the non-InnoDB tables to be backed up. The file contains entries for databases or fully qualified table names separated by newline or space. The format of the entries is the same as for the --databases option:

   db_name[.table_name]
   db_name1[.table_name1]
   ...

Remove any whitespaces surrounding the database or table names, as the whitespaces are not removed automatically. Begin a line with the # character to include a comment. No regular expressions are allowed.

If the specified entries do not match any database or table, then no non-InnoDB data files are backed up.

--only-innodb-with-frm[={all|related}]

Back up only InnoDB data, log files, and the .frm files associated with the InnoDB tables.

This option saves you having to script the backup step for InnoDB .frm files, which you would normally do while the server is put into a read-only state by a FLUSH TABLES WITH READ LOCK statement. The .frm files are copied without putting the server into a read-only state, so that the backup operation is a true hot backup and does not interrupt database processing. You must ensure that no ALTER TABLE or other DDL statements change .frm files for InnoDB tables while the backup is in progress. If the mysqlbackup command detects changes to any relevant .frm files during the backup operation, it halts with an error. If it is not practical to forbid DDL on InnoDB tables during the backup operation, use the --only-innodb option instead and use the traditional method of copying the .frm files while the server is locked.

All files created by other storage engines are excluded. Typically used when no connection to mysqld is allowed or when there is no need to copy MyISAM files, for example, when you are sure there are no DDL changes during the backup. See Making a Partial Backup with the Legacy Options for instructions and examples.

The option is not compatible with the --slave-info option.

Default: backups include files from all storage engines.

--use-tts[={with-minimum-locking|with-full-locking}]

Enable selective backup of InnoDB tables using transportable tablespaces (TTS). This is to be used in conjunction with the --include option, which selects the InnoDB tables to be backed up by a regular expression. Using TTS for backups offers the following advantages:

However, the option has the following limitations:

There are two possible values for the option:

Default: back up with minimum locking

There are some special requirements for restoring backups created with the --use-tts option; see the explanations in Section 4.2, “Performing a Restore Operation” for details.

--backup-image=IMAGE

Specify the path name of the file used for a single-file backup. By default, the single-file backup is streamed to standard output, so that you can pipe it directly to other commands such as tape backup or ssh-related network commands.

You can optionally prefix the image name with file: to signify file I/O (the default). For tape backups, prefix the image name withsbt:. See Section 3.3.5.2, “Backing Up to Tape” for details about tape backups.

--src-entry=PATH

Identifies a file or directory to extract from a single-file backup. This option is used with the extract command. If the argument is a directory, all its files and subdirectory contents are extracted. No pattern matching expression is allowed for the argument. Optionally, you can also specify the --dst-entry option to extract the file or directory in a location different from its original path name.

For example: src-entry=meta/comments.txt extracts only one file, comments.txt, while src-entry=meta extracts the entire directory tree for the meta subdirectory.

Default: All entries are extracted.

--dst-entry=PATH

Used with single-file backups to extract a single file or directory to a user-specified path. Use of this option requires specifying the --src-entry option. This option specifies the destination path for the selected entry in backup image corresponding to entry specified by -src-entry=PATH option. The entry could point to a single file or single directory. For example, to retrieve the comments file from a backup image and store it as /tmp/my-comments.txt, use a command like the following:

mysqlbackup --src-entry=meta/comments.txt \
  --dst-entry=/tmp/my-comments.txt \
  --backup-image=/var/myimage.bki  extract

Similarly, to extract all the contents of the meta directory in a single-file backup as /data/my-meta, use a command like the following:

mysqlbackup --src-entry=meta \
  --dst-entry=/data/my-meta \
  --backup-image=/var/myimage.bki  extract

The specified path is a simple path name without any wildcard expansion or regular expressions.

Default: By default, original pathnames are used to create files in the local file system.

--sbt-database-name=NAME

For tape backups, this option can be used as a hint to the Media Management Software (MMS) for the selection of media and policies. This name has nothing to do with MySQL database names. It is a term used by the MMS. See Section 3.3.5.2, “Backing Up to Tape” for usage details.

--sbt-lib-path=PATH

Path name of the SBT library used by software that manages tape backups. If this is not specified, operating system-specific search methods are used to locate libobk.so (UNIX) or orasbt.dll (Windows). See Section 3.3.5.2, “Backing Up to Tape” for usage details.

--sbt-environment=VAR=value,...

Passes product-specific environment variables to Oracle Secure Backup or another SBT-compliant backup management product, as an alternative to setting and unsetting environment variables before and after each mysqlbackup invocation.

The parameter to this option is a comma-separated list of key-value pairs, using syntax similar to that of the RMAN tool for the Oracle Database. For example, --sbt-environment=VAR1=val1,VAR2=val2,VAR3=val3.

Consult the documentation for your backup management product to see which of its features can be controlled through environment variables. For example, the Oracle Secure Backup product defines environment variables such as OB_MEDIA_FAMILY, OB_DEVICE, and OB_RESOURCE_WAIT_TIME. You might set such variables with the mysqlbackup by specifying an option such as --sbt-environment="OB_MEDIA_FAMILY=my_mf,OB_DEVICE=my_tape".

If the argument string contains any whitespace or special characters recognized by the command shell, enclose the entire argument string in quotation marks. To escape an equals sign or comma, use the \ character. For example, --sbt-environment="VAR1=multiple words,VAR2=<angle_brackets>,VAR3=2+2\=4".

--disable-manifest

Disable generation of manifest files for a backup operation, which are backup_create.xml and backup_content.xml present in the meta subdirectory.

--number-of-buffers=num_buffers

Specifies the number of buffers, each 16MB in size, to use during multithreaded options.

Use a high number for CPU-intensive processing such as backup, particularly when using compression. Use a low number for disk-intensive processing such as restoring a backup. This value should be at least as high as the number of read threads or write threads, depending on the type of operation.

Default: currently 14.

For compression or incremental backup operations, the buffer size is slightly more than 16MB to accommodate the headers.

One additional buffer is used for single-file incremental backup and single-file compressed backup.

Compressed backup, compressed single-file backup, and uncompress apply-log operations require one additional buffer for each process thread.

If you change the number of read, write, and processing threads, you can experiment with changing this value so that it is slightly larger than the total number of threads specified by those other options. See Section 7.1, “Optimizing Backup Performance” and Section 7.2, “Optimizing Restore Performance” for additional advice about recommended combinations of values for this and other performance-related options for various hardware configurations, such as RAID or non-RAID storage devices.

--read-threads=num_threads

Specifies the number of threads to use for reading data from disk.

Default: currently 1. This default applies to these kinds of operations: copy-back, extract, and backup. If you specify a value of 0, it is silently adjusted to 1. The maximum is 15; if you supply a negative value, it is silently adjusted to 15. For apply-log operations, the number of read threads is always 1 regardless of this option setting. See Section 7.1, “Optimizing Backup Performance” and Section 7.2, “Optimizing Restore Performance” for advice about recommended combinations of values for --read-threads, --process-threads, and --write-threads for various hardware configurations, such as RAID or non-RAID storage devices.

--process-threads=num_threads

Specifies the number of threads to use for processing data, such as compressing or uncompressing backup files.

Default: currently 6. This default applies to these kinds of operations: extract, and backup. It is ignored when you use any of the options --incremental-with-redo-log-only, apply-incremental-backup, copy-back, or backup-dir-to-image.

If you specify a value of 0, it is silently adjusted to 1. The maximum is 15; if you supply a negative value, it is silently adjusted to 15. For apply-log operations, the number of process threads is always 1 regardless of this option setting. See Section 7.1, “Optimizing Backup Performance” and Section 7.2, “Optimizing Restore Performance” for advice about recommended combinations of values for --read-threads, --process-threads, and --write-threads for various hardware configurations, such as RAID or non-RAID storage devices.

--write-threads=num_threads

Specifies the number of threads to use for writing data to disk.

Default: currently 1. This default applies to these kinds of operations: copy-back, extract, and backup. It is ignored when you use any of the single-file backup options list-image or validate.

If you specify a value of 0, it is silently adjusted to 1. The maximum is 15; if you supply a negative value, it is silently adjusted to 15. For apply-log operations, the number of write threads is always 0 regardless of this option setting. See Section 7.1, “Optimizing Backup Performance” and Section 7.2, “Optimizing Restore Performance” for advice about recommended combinations of values for --read-threads, --process-threads, and --write-threads for various hardware configurations, such as RAID or non-RAID storage devices.

--limit-memory=MB

Specify maximum memory in megabytes that can be used by the mysqlbackup command. Formerly applied only to apply-log operation, but in MySQL Enterprise Backup 3.8 and higher it applies to all operations. Do not include any suffixes such as mb or kb in the option value.

Default: 100 for apply-log not used with --uncompress, 300 for all operations (in megabytes).

The memory limit specified by this option also caps the number of 16MB buffers available for multithreaded processing. For example, with a 300 MB limit, the maximum number of buffers is 18. If additional buffers are required because you increase the values for --read-threads, --process-threads, --write-threads, and/or --number-of-buffers, increase the --limit-memory value proportionally.

--sleep=MS

Specify the number in milliseconds to sleep after copying a certain amount of data from InnoDB tables. Each block of data is 1024 InnoDB data pages, typically totalling 16MB. This is to limit the CPU and I/O overhead on the database server.

Default: 0 (no voluntary sleeps).

--no-locking

Disables locking during backup of non-InnoDB files, even if a connection is available. Can be used to copy non-InnoDB data with less disruption to normal database processing. There could be inconsistencies in non-InnoDB data if any changes are made while those files are being backed up.

--page-reread-time=MS

Interval in milliseconds that mysqlbackup waits before re-reading a page that fails a checksum test. A busy server could be writing a page at the same moment that mysqlbackup is reading it. Can be a floating-point number, such as 0.05 meaning 50 microseconds. Best possible resolution is 1 microsecond, but it could be worse on some platforms. Default is 100 milliseconds (0.1 seconds).

--page-reread-count=retry_limit

Maximum number of re-read attempts, when a page fails a checksum test. A busy server could be writing a page at the same moment that mysqlbackup is reading it. If the same page fails this many checksum tests consecutively, with a pause based on the --page-reread-time option between each attempt, the backup fails. Default is 500.

--on-disk-full={abort|abort_and_remove|warn}

Specifies the behavior when a backup process encounters a disk-full condition. This option is only for backup operations (backup, backup-and-apply-log, and backup-to-image).

Default: abort.

--skip-unused-pages

Skip unused pages in tablespaces when backing up InnoDB tables. This option is applicable to the backup and backup-to-image operations, but not to incremental backups. The option is ignored by the backup-and-apply-log operation.

Note that backups created with the --skip-unused-pages option cannot be restored using copy-back-and-apply-log.

Unused pages are free pages often caused by bulk delete of data. By skipping the unused pages during backups, this option can reduce the backup sizes and thus the required disk space and I/O resources for the operations. However, subsequent apply-log operations on the backups will take more time to complete, as the unused pages are inserted back into the tables during the operations.

--skip-binlog

Do not include binary log files in a backup. Binary log files are included by default for all kinds of online backups (full, incremental, compressed, partial, single-file, etc.). See Section 1.4, “Files that Are Backed Up”, for details. Use this option to skip backing up binary logs if resource, performance, or other issues arise.

--skip-relaylog

Do not include relay log files in a backup. Relay log files are included by default for all kinds of online backups (full, incremental, compressed, partial, single-file, etc.) of a slave server. See Section 1.4, “Files that Are Backed Up”, for details. Use this option to skip backing up relay logs if resource, performance, or other issues arise.

--log-bin-index[=PATH]

For MySQL 5.5 and earlier, as well as all offline backups: specify the absolute path (including filename and extension) of the index file on the MySQL server that lists all the used binary log files, if it is different from the default path given below, in order to include the binary log files in the backup.

Default: data_dir/host_name-bin.index.

--relay-log-index[=PATH]

For offline backups of salve servers only: specify the absolute path (including filename and extension) of the index file on the MySQL server that lists all the used relay log files, if it is different from the default path given below, in order to include the relay log files in the backup.

Default: data_dir/host_name-relay-bin.index.

--master-info-file[=PATH]

For offline backups of salve servers only: specify the absolute path (including filename and extension) of the information file in which a slave records information about its master, if it is different from the default path given below, in order to include the information file in the backup.

Default: data_dir/master.info.

--relaylog-info-file[=PATH]

For offline backups of salve servers only: specify the absolute path (including filename and extension) of the information file in which a slave records information about the relay logs, if it is different from the default path given below, in order to include the information file in the backup.

Default: data_dir/relay-log.info.

--optimistic-time[=DATE-TIME]

Perform an optimistic backup with the value specified with the option as the “optimistic time”—a time after which the tables that have not been modified are taken as “inactive tables.” The “inactive tables”are believed to be unlikely to change during the backup process. The inactive tables are backed up in the optimistic phase of the backup, and all other tables are backed up in the normal phase. See Section 3.3.6, “Making an Optimistic Backup” for details on the concept, use cases, and command samples for an optimistic backup.

Accepted formats for specifying the option include:

When both the optimistic-time and the optimistic-busy-tables options are used and they come into conflict on determining which tables are to be backed up in the optimistic phase, optimistic-busy-tables takes precedence over optimistic-time.

--optimistic-busy-tables=REGEXP

Perform an optimistic backup, using the regular expression specified with the option to select tables that will be skipped in the first phase of an optimistic backup, because they are likely to be modified during the backup process. Tables whose fully qualified names (in the form of database_name.table_name) are matched by the regular expression are taken as “busy tables”, which will be backed up in the second or the “normal” phase of the backup. Tables whose fully qualified names are NOT matched by the regular expression are taken as “inactive tables”, which will be backed up in the first or the “optimistic” phase of the backup. See Section 3.3.6, “Making an Optimistic Backup” for details on the concept, use cases, and command samples for an optimistic backup.

MySQL Enterprise Backup will throw an error if the option is used but no regular expression is supplied with it.

When both the optimistic-time and the optimistic-busy-tables options are used and they come into conflict on determining which tables are to be “optimistic”, optimistic-busy-tables takes precedence over optimistic-time.

--skip-messages-logdir

Skip message logging. Logging is turned on by default (except for the list-image and validate operations; see the description for the --messages-logdir option for details), and it is turned off by this option.

--messages-logdir=path

Specifies the path name of an existing directory for storing the message log. If the specified directory does not exist, message logging fails and returns an error message. When this option is omitted, the default directory of backup_dir/meta is used.

--show-progress[={stderr|stdout|file:FILENAME|fifo:FIFONAME|table|variable}]

The option instructs mysqlbackup to periodically output short progress reports known as progress indicators on its operation.

The argument of the option controls the destination to which the progress indicators are sent:

When there is no argument specified for --show-progress, progress indicators are sent to stderr.

Progress can be reported to multiple destinations by specifying the --show-progress option several times on the command line. For example the following command line reports progress of the backup command to stderr and to a file called meb_output:

mysqlbackup --show-progress --show-progress=file:meb_output --backup-dir=/full-backup
            backup

The progress indicators are short strings that indicate how far the execution of a mysqlbackup operation has progressed. A progress indicator consists of one or more meters that measure the progress of the operation. For example:

Progress: 100 of 1450 MB; state: Copying .ibd files

This shows that 100 megabytes of a total of 1450 megabytes have been copied or processed so far, and mysqlbackup is currently copying InnoDB data files (.ibd files).

The progress indicator string begins with Progress:, followed by one or more meters measuring the progress. If multiple meters are present, they are separated by semicolons. The different types of meters include:

Here are some examples of progress indicators with different meters:

Progress: 300 of 1540 MB; state: Waiting for locks 

Progress: 400 of 1450 MB; state: Copying InnoDB data: compression: 30%

The exact set of meters included in the progress indicator depends on the command and the options used for it.

--progress-interval=SECONDS

Interval between progress reports in seconds. Default value is two seconds. The shortest interval is 1 second and the longest allowed interval is 100000 seconds.

--encrypt

Encrypt the data when creating a backup image by a backup-to-image operation, or when packing a backup directory into a single file with the backup-dir-to-image subcommand. It cannot be used with the backup or backup-and-apply-log subcommand.

--decrypt

Decrypt an encrypted backup image when performing an extract, image-to-backup-dir, or copy-back-and-apply-log operation. It is also used for performing a validate or list-image operation on an encrypted backup image.

The option cannot be used in a apply-log, backup-and-apply-log, or copy-back operation. For restoration using the copy-back subcommand, the encrypted backup image has to be unpacked and decrypted first using the image-to-backup-dir or extract subcommand, together with the --decrypt option.

--key=STRING

The symmetric key for encryption and decryption of a backup image. It should be a 256-bit key, encoded as a string of 64 hexadecimal digits. See Chapter 8, Encryption for Backups on how to create a key. The option is incompatible with the --key-file option.

--key-file=PATH

The pathname to file that contains a 256-bit key, encoded as a string of 64 hexadecimal digits, for encryption and decryption of a backup image. The option is incompatible with the --key option.

--cloud-service

Cloud service for data backup or restoration. Currently, only the Amazon S3 service is supported, and “s3” is the only value mysqlbackup accepts for this option.

--cloud-bucket

The storage bucket on Amazon S3 for the backup image. The option only has meaning if Amazon S3 is used for cloud backup.

In order to perform cloud backups and restores with the bucket, the user identified by the --cloud-access-key-id option must have at least the following permissions on the bucket:

--cloud-object-key

The Amazon S3 object key for the backup image. The option only has meaning if Amazon S3 is used for cloud backup.

--cloud-access-key-id

AWS access key ID for logging onto Amazon S3. The option only has meaning if Amazon S3 is used for cloud backup.

--cloud-secret-access-key

AWS secret access key that goes with the AWS access key id used in --cloud-access-key-id. The option only has meaning if Amazon S3 is used for cloud backup.

--cloud-aws-region

Region for Amazon Web Services that mysqlbackup accesses for S3. The option only has meaning if Amazon S3 is used for cloud backup.

--cloud-trace

Print trace information for cloud operations. It works independently of --trace, which specifies the trace level for the non-cloud operations of mysqlbackup.

Any non-zero value for the option enables the trace function. Default value is “0.”

--cloud-proxy=proxy-url:port

Proxy address and port number for overriding the environment's default proxy settings for accessing Amazon S3.

--slave-info

When backing up a replication slave server, this option captures information needed to set up an identical slave server. It creates a file meta/ibbackup_slave_info inside the backup directory, containing a CHANGE MASTER statement with the binary log position and name of the binary log file of the master server. This information is also printed in the mysqlbackup output. To set up a new slave for this master, restore the backup data on another server, start a slave server on the backup data, and issue a CHANGE MASTER command with the binary log position saved in the ibbackup_slave_info file. See Section 6.1, “Setting Up a New Replication Slave” for instructions.

--suspend-at-end

This option pauses the mysqlbackup command when the backup procedure is close to ending. It creates a file called ibbackup_suspended in the backup log group home directory and waits until you delete that file before proceeding. This option is useful to customize locking behavior and backup of non-InnoDB files through custom scripting.

All tables are locked before suspending, putting the database into a read-only state, unless you turn off locking with the --no-locking or --no-connection option. The --only-innodb and --only-innodb-with-frm options also prevent the locking step. Because locking all tables could be problematic on a busy server, you might use a combination of --only-innodb and --suspend-at-end to back up only certain InnoDB tables.

--exec-when-locked="utility arg1 arg2 ..."

You can use this option to run a script that backs up any information that is not included as part of the usual backup. For example, with --exec-when-locked, you can use mysqldump to back up tables from the MEMORY storage engine, which are not on disk.

Set any variable you want to use within your script before you run mysqlbackup. In the following example, the BACKUP_DIR environment variable is set to point to the current backup directory (quotes are used for the argument of --exec-when-locked, to prevent premature expansion of the variable BACKUP_DIR):

On Unix or Linux systems:

export BACKUP_DIR=path_to_backupdir
mysqlbackup --exec-when-locked='mysqldump mydb t1 > $BACKUP_DIR/t1.sql' other_options mysqlbackup_command

Or on Windows systems:

set BACKUP_DIR=path_to_backupdir
mysqlbackup --exec-when-locked="mysqldump mydb t1 > %BACKUP_DIR%/t1.sql" other_options mysqlbackup_command

If the utility cannot be executed or returns a non-zero exit status, the whole backup process is cancelled. If you also use the --suspend-at-end option, the utility specified by --exec-when-locked is executed after the suspension is lifted.