The xtrabackup Option Reference¶

Options¶

--apply-log-only¶

This option causes only the redo stage to be performed when preparing a backup. It is very important for incremental backups.

--backup¶

Make a backup and place it in xtrabackup --target-dir. See Creating a backup.

--binlog-info¶

This option controls how Percona XtraBackup should retrieve server’s binary log coordinates corresponding to the backup. Possible values are OFF, ON, LOCKLESS and AUTO. See the Percona XtraBackup Lockless binary log information manual page for more information.

--check-privileges¶

This option checks if Percona XtraBackup has all required privileges to take the backup. When this option is used backup may terminate right after starting if some of the required privileges are missing. However, there is a level of uncertainty and some missing privileges may not be required to perform a backup, those are marked as warnings and backup is not aborted. In case of missing privileges the output can look like this:

xtrabackup: Error: missing required privilege LOCK TABLES on *.*
xtrabackup: Warning: missing required privilege REPLICATION CLIENT on *.*

--close-files¶

Do not keep files opened. When xtrabackup opens tablespace it normally doesn’t close its file handle in order to handle the DDL operations correctly. However, if the number of tablespaces is really huge and can not fit into any limit, there is an option to close file handles once they are no longer accessed. Percona XtraBackup can produce inconsistent backups with this option enabled. Use at your own risk.

--compact¶

Create a compact backup by skipping secondary index pages.

--compress¶

This option tells xtrabackup to compress all output data, including the transaction log file and meta data files, using the specified compression algorithm. The only currently supported algorithm is quicklz. The resulting files have the qpress archive format, i.e. every *.qp file produced by xtrabackup is essentially a one-file qpress archive and can be extracted and uncompressed by the qpress file archiver.

--compress-chunk-size=#¶

Size of working buffer(s) for compression threads in bytes. The default value is 64K.

--compress-threads=#¶

This option specifies the number of worker threads used by xtrabackup for parallel data compression. This option defaults to 1. Parallel compression (:option:` xtrabackup –compress-threads`) can be used together with parallel file copying (xtrabackup --parallel). For example, --parallel=4 --compress --compress-threads=2 will create 4 I/O threads that will read the data and pipe it to 2 compression threads.

--copy-back¶

Copy all the files in a previously made backup from the backup directory to their original locations. This option will not copy over existing files unless xtrabackup --force-non-empty-directories option is specified.

--create-ib-logfile¶

This option is not currently implemented. To create the InnoDB log files, you must prepare the backup twice at present.

--databases=#¶

This option specifies the list of databases and tables that should be backed up. The option accepts the list of the form "databasename1[.table_name1] databasename2[.table_name2] . . .".

--databases-exclude=name¶

Excluding databases based on name, Operates the same way as xtrabackup --databases, but matched names are excluded from backup. Note that this option has a higher priority than xtrabackup --databases.

--databases-file=#¶

This option specifies the path to the file containing the list of databases and tables that should be backed up. The file can contain the list elements of the form databasename1[.table_name1], one element per line.

--datadir=DIRECTORY¶

The source directory for the backup. This should be the same as the datadir for your MySQL server, so it should be read from my.cnf if that exists; otherwise you must specify it on the command line.

--decompress¶

Decompresses all files with the .qp extension in a backup previously made with the xtrabackup --compress option. The xtrabackup --parallel option will allow multiple files to be decrypted simultaneously. In order to decompress, the qpress utility MUST be installed and accessible within the path. Percona XtraBackup doesn’t automatically remove the compressed files. In order to clean up the backup directory users should use xtrabackup --remove-original option.

--decrypt=ENCRYPTION-ALGORITHM¶

Decrypts all files with the .xbcrypt extension in a backup previously made with xtrabackup --encrypt option. The xtrabackup --parallel option will allow multiple files to be decrypted simultaneously. Percona XtraBackup doesn’t automatically remove the encrypted files. In order to clean up the backup directory users should use xtrabackup --remove-original option.

--defaults-extra-file=[MY.CNF]¶

Read this file after the global files are read. Must be given as the first option on the command-line.

--defaults-file=[MY.CNF]¶

Only read default options from the given file. Must be given as the first option on the command-line. Must be a real file; it cannot be a symbolic link.

--defaults-group=GROUP-NAME¶

This option is to set the group which should be read from the configuration file. This is used by innobackupex if you use the xtrabackup --defaults-group option. It is needed for mysqld_multi deployments.

--encrypt=ENCRYPTION_ALGORITHM¶

This option instructs xtrabackup to encrypt backup copies of InnoDB data files using the algorithm specified in the ENCRYPTION_ALGORITHM. It is passed directly to the xtrabackup child process. See the xtrabackup documentation for more details.

--encrypt-key=ENCRYPTION_KEY¶

This option instructs xtrabackup to use the given ENCRYPTION_KEY when using the xtrabackup --encrypt option. It is passed directly to the xtrabackup child process. See the xtrabackup documentation for more details.

--encrypt-key-file=ENCRYPTION_KEY_FILE¶

This option instructs xtrabackup to use the encryption key stored in the given ENCRYPTION_KEY_FILE when using the xtrabackup --encrypt option. It is passed directly to the xtrabackup child process. See the xtrabackup documentation for more details.

--encrypt-threads=#¶

This option specifies the number of worker threads that will be used for parallel encryption. It is passed directly to the xtrabackup child process. See the xtrabackup documentation for more details.

--encrypt-chunk-size=#¶

This option specifies the size of the internal working buffer for each encryption thread, measured in bytes. It is passed directly to the xtrabackup child process. See the xtrabackup documentation for more details.

--export¶

Create files necessary for exporting tables. See Restoring Individual Tables.

--extra-lsndir=DIRECTORY¶

(for –backup): save an extra copy of the xtrabackup_checkpoints and xtrabackup_info files in this directory.

--force-non-empty-directories¶

When specified, it makes :option`xtrabackup –copy-back` and xtrabackup --move-back option transfer files to non-empty directories. No existing files will be overwritten. If files that need to be copied/moved from the backup directory already exist in the destination directory, it will still fail with an error.

--ftwrl-wait-timeout=SECONDS¶

This option specifies time in seconds that xtrabackup should wait for queries that would block FLUSH TABLES WITH READ LOCK before running it. If there are still such queries when the timeout expires, xtrabackup terminates with an error. Default is 0, in which case it does not wait for queries to complete and starts FLUSH TABLES WITH READ LOCK immediately. Where supported (Percona Server 5.6+) xtrabackup will automatically use Backup Locks as a lightweight alternative to FLUSH TABLES WITH READ LOCK to copy non-InnoDB data to avoid blocking DML queries that modify InnoDB tables.

--ftwrl-wait-threshold=SECONDS¶

This option specifies the query run time threshold which is used by xtrabackup to detect long-running queries with a non-zero value of xtrabackup --ftwrl-wait-timeout. FLUSH TABLES WITH READ LOCK is not started until such long-running queries exist. This option has no effect if xtrabackup --ftwrl-wait-timeout is 0. Default value is 60 seconds. Where supported (Percona Server 5.6+) xtrabackup will automatically use Backup Locks as a lightweight alternative to FLUSH TABLES WITH READ LOCK to copy non-InnoDB data to avoid blocking DML queries that modify InnoDB tables.

--ftwrl-wait-query-type=all|update¶

This option specifies which types of queries are allowed to complete before xtrabackup will issue the global lock. Default is all.

--galera-info¶

This options creates the xtrabackup_galera_info file which contains the local node state at the time of the backup. Option should be used when performing the backup of Percona XtraDB Cluster. It has no effect when backup locks are used to create the backup.

--incremental-basedir=DIRECTORY¶

When creating an incremental backup, this is the directory containing the full backup that is the base dataset for the incremental backups.

--incremental-dir=DIRECTORY¶

When preparing an incremental backup, this is the directory where the incremental backup is combined with the full backup to make a new full backup.

--incremental-force-scan¶

When creating an incremental backup, force a full scan of the data pages in the instance being backuped even if the complete changed page bitmap data is available.

--incremental-lsn=LSN¶

When creating an incremental backup, you can specify the log sequence number (LSN) instead of specifying xtrabackup --incremental-basedir. For databases created in 5.1 and later, specify the LSN as a single 64-bit integer. ATTENTION: If a wrong LSN value is specified (a user error which Percona XtraBackup is unable to detect), the backup will be unusable. Be careful!

--innodb-log-arch-dir=DIRECTORY¶

This option is used to specify the directory containing the archived logs. It can only be used with the xtrabackup --prepare option.

--innodb-miscellaneous¶

There is a large group of InnoDB options that are normally read from the my.cnf configuration file, so that xtrabackup boots up its embedded InnoDB in the same configuration as your current server. You normally do not need to specify these explicitly. These options have the same behavior that they have in InnoDB or XtraDB. They are as follows:

--innodb-adaptive-hash-index
--innodb-additional-mem-pool-size
--innodb-autoextend-increment
--innodb-buffer-pool-size
--innodb-checksums
--innodb-data-file-path
--innodb-data-home-dir
--innodb-doublewrite-file
--innodb-doublewrite
--innodb-extra-undoslots
--innodb-fast-checksum
--innodb-file-io-threads
--innodb-file-per-table
--innodb-flush-log-at-trx-commit
--innodb-flush-method
--innodb-force-recovery
--innodb-io-capacity
--innodb-lock-wait-timeout
--innodb-log-buffer-size
--innodb-log-files-in-group
--innodb-log-file-size
--innodb-log-group-home-dir
--innodb-max-dirty-pages-pct
--innodb-open-files
--innodb-page-size
--innodb-read-io-threads
--innodb-write-io-threads

--keyring-file-data=FILENAME¶

The path to the keyring file.

--lock-ddl¶

Issue LOCK TABLES FOR BACKUP if it is supported by server at the beginning of the backup to block all DDL operations.

--lock-ddl-per-table¶

Lock DDL for each table before xtrabackup starts to copy it and until the backup is completed.

--lock-ddl-timeout¶

If LOCK TABLES FOR BACKUP does not return within given timeout, abort the backup.

--log-copy-interval=#¶

This option specifies time interval between checks done by log copying thread in milliseconds (default is 1 second).

--move-back¶

Move all the files in a previously made backup from the backup directory to their original locations. As this option removes backup files, it must be used with caution.

--no-defaults¶

Don’t read default options from any option file. Must be given as the first option on the command-line.

--parallel=#¶

This option specifies the number of threads to use to copy multiple data files concurrently when creating a backup. The default value is 1 (i.e., no concurrent transfer).

--password=PASSWORD¶

This option specifies the password to use when connecting to the database. It accepts a string argument. See mysql –help for details.

--prepare¶

Makes xtrabackup perform recovery on a backup created with xtrabackup --backup, so that it is ready to use. See preparing a backup.

--print-defaults¶

Print the program argument list and exit. Must be given as the first option on the command-line.

--print-param¶

Makes xtrabackup print out parameters that can be used for copying the data files back to their original locations to restore them. See Scripting Backups With xtrabackup.

--rebuild_indexes¶

Rebuild secondary indexes in InnoDB tables after applying the log. Only has effect with –prepare.

--rebuild_threads=#¶

Use this number of threads to rebuild indexes in a compact backup. Only has effect with –prepare and –rebuild-indexes.

--reencrypt-for-server-id=<new_server_id>¶

Use this option to start the server instance with different server_id from the one the encrypted backup was taken from, like a replication slave or a galera node. When this option is used, xtrabackup will, as a prepare step, generate a new master key with ID based on the new server_id, store it into keyring file and re-encrypt the tablespace keys inside of tablespace headers. Option should be passed for --prepare (final step).

--remove-original¶

Implemented in Percona XtraBackup 2.4.6, this option when specified will remove .qp, .xbcrypt and .qp.xbcrypt files after decryption and decompression.

--safe-slave-backup¶

When specified, xtrabackup will stop the slave SQL thread just before running FLUSH TABLES WITH READ LOCK and wait to start backup until Slave_open_temp_tables in SHOW STATUS is zero. If there are no open temporary tables, the backup will take place, otherwise the SQL thread will be started and stopped until there are no open temporary tables. The backup will fail if Slave_open_temp_tables does not become zero after xtrabackup --safe-slave-backup-timeout seconds. The slave SQL thread will be restarted when the backup finishes. This option is implemented in order to deal with replicating temporary tables and isn’t neccessary with Row-Based-Replication.

--safe-slave-backup-timeout=SECONDS¶

How many seconds xtrabackup --safe-slave-backup should wait for Slave_open_temp_tables to become zero. Defaults to 300 seconds.

--secure-auth¶

Refuse client connecting to server if it uses old (pre-4.1.1) protocol. (Enabled by default; use –skip-secure-auth to disable.)

--server-id=#¶

The server instance being backed up.

--slave-info¶

This option is useful when backing up a replication slave server. It prints the binary log position of the master server. It also writes this information to the xtrabackup_slave_info file as a CHANGE MASTER command. A new slave for this master can be set up by starting a slave server on this backup and issuing a CHANGE MASTER command with the binary log position saved in the xtrabackup_slave_info file.

--ssl¶

Enable secure connection. More information can be found in –ssl MySQL server documentation.

--ssl-ca¶

Path of the file which contains list of trusted SSL CAs. More information can be found in –ssl-ca MySQL server documentation.

--ssl-capath¶

Directory path that contains trusted SSL CA certificates in PEM format. More information can be found in –ssl-capath MySQL server documentation.

--ssl-cert¶

Path of the file which contains X509 certificate in PEM format. More information can be found in –ssl-cert MySQL server documentation.

--ssl-cipher¶

List of permitted ciphers to use for connection encryption. More information can be found in –ssl-cipher MySQL server documentation.

--ssl-crl¶

Path of the file that contains certificate revocation lists. More information can be found in –ssl-crl MySQL server documentation.

--ssl-crlpath¶

Path of directory that contains certificate revocation list files. More information can be found in –ssl-crlpath MySQL server documentation.

--ssl-key¶

Path of file that contains X509 key in PEM format. More information can be found in –ssl-key MySQL server documentation.

--ssl-mode¶

Security state of connection to server. More information can be found in –ssl-mode MySQL server documentation.

--ssl-verify-server-cert¶

Verify server certificate Common Name value against host name used when connecting to server. More information can be found in –ssl-verify-server-cert MySQL server documentation.

--stats¶

Causes xtrabackup to scan the specified data files and print out index statistics.

--stream=name¶

Stream all backup files to the standard output in the specified format. Currently supported formats are xbstream and tar.

--tables=name¶

A regular expression against which the full tablename, in databasename.tablename format, is matched. If the name matches, the table is backed up. See partial backups.

--tables-exclude=name¶

Filtering by regexp for table names. Operates the same way as xtrabackup --tables, but matched names are excluded from backup. Note that this option has a higher priority than xtrabackup --tables.

--tables-file=name¶

A file containing one table name per line, in databasename.tablename format. The backup will be limited to the specified tables. See Scripting Backups With xtrabackup.

--target-dir=DIRECTORY¶

This option specifies the destination directory for the backup. If the directory does not exist, xtrabackup creates it. If the directory does exist and is empty, xtrabackup will succeed. xtrabackup will not overwrite existing files, however; it will fail with operating system error 17, file exists.

If this option is a relative path, it is interpreted as being relative to the current working directory from which xtrabackup is executed.

--throttle=#¶

This option limits xtrabackup --backup to the specified number of read+write pairs of operations per second. See throttling a backup.

--tmpdir=name¶

This option is currently not used for anything except printing out the correct tmpdir parameter when xtrabackup --print-param is used.

--to-archived-lsn=LSN¶

This option is used to specify the LSN to which the logs should be applied when backups are being prepared. It can only be used with the xtrabackup --prepare option.

--use-memory=#¶

This option affects how much memory is allocated for preparing a backup with xtrabackup --prepare, or analyzing statistics with xtrabackup --stats. Its purpose is similar to innodb_buffer_pool_size. It does not do the same thing as the similarly named option in Oracle’s InnoDB Hot Backup tool. The default value is 100MB, and if you have enough available memory, 1GB to 2GB is a good recommended value. Multiples are supported providing the unit (e.g. 1MB, 1M, 1GB, 1G).

--user=USERNAME¶

This option specifies the MySQL username used when connecting to the server, if that’s not the current user. The option accepts a string argument. See mysql –help for details.

--version¶

This option prints xtrabackup version and exits.