Options for mariadb-backup & mariabackup in MariaDB Community Server 10.6

Overview

The mariadb-backup utility is the newer name for mariabackup, though you can still run it using either name.

Option

Description

--aria-log-dir-path

Path to individual files and their sizes.

--backup

take backup to target-dir

--binlog-info

This option controls how MariaDB Backup should retrieve server's binary log coordinates corresponding to the backup. Possible values are OFF, ON, LOCKLESS and AUTO. However, LOCKLESS is not safe to use with MariaDB Server. See the documentation for more information.

--check-privileges

Check database user privileges fro the backup user (Defaults to on; use --skip-check-privileges to disable.)

--close-files

do not keep files opened. Use at your own risk.

--compress

Compress individual backup files using the specified compression algorithm. Currently the only supported algorithm is 'quicklz'. It is also the default algorithm, i.e., the one used when --compress is used without an argument.

--compress-chunk-size

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

--compress-threads

Number of threads for parallel data compression. The default value is 1.

--copy-back

Copy all the files in a previously made backup from the backup directory to their original locations.

--core-file

Write core on fatal signals

--databases

filtering by list of databases.

--databases-exclude

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

--databases-file

filtering by list of databases in the file.

--datadir (-h)

Path to the database root.

--decompress

Decompresses all files with the .qp extension in a backup previously made with the --compress option.

--defaults-extra-file

Read this file after the global files are read.

--defaults-file

Only read default options from the given file #.

--defaults-group

defaults group in config file (default "mysqld").

--defaults-group-suffix

Additionally read default groups with # appended as a suffix.

--encrypted-backup

In --backup, assume that nonzero key_version implies that the page is encrypted. Use --backup --skip-encrypted-backup to allow copying unencrypted that were originally created before MySQL 5.1.48. (Defaults to on; use --skip-encrypted-backup to disable.)

--export

create files to import to another database when prepare.

--extended-validation

Enable extended validation for Innodb data pages during backup phase. Will slow down backup considerably, in case encryption is used. May fail if tables are created during the backup.

--extra-lsndir

(for --backup): save an extra copy of the xtrabackup_checkpoints file in this directory.

--force-non-empty-directories

This option, when specified, makes --copy-back or --move-back transfer files to non-empty directories. Note that no existing files will be overwritten. If --copy-back or --move-back has to copy a file from the backup directory which already exists in the destination directory, it will still fail with an error.

--ftwrl-wait-query-type

This option specifies which types of queries are allowed to complete before mariadb-backup will issue the global lock. Default is all.. One of: ALL, UPDATE, SELECT

--ftwrl-wait-threshold

This option specifies the query run time threshold which is used by mariadb-backup to detect long-running queries with a non-zero value of --ftwrl-wait-timeout. FTWRL is not started until such long-running queries exist. This option has no effect if --ftwrl-wait-timeout is 0. Default value is 60 seconds.

--ftwrl-wait-timeout

This option specifies time in seconds that mariadb-backup should wait for queries that would block FTWRL before running it. If there are still such queries when the timeout expires, mariadb-backup terminates with an error. Default is 0, in which case mariadb-backup does not wait for queries to complete and starts FTWRL immediately.

--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 MariaDB Galera Cluster. Has no effect when backup locks are used to create the backup.

--help (-?)

Display this help and exit.

--history

This option enables the tracking of backup history in the PERCONA_SCHEMA.xtrabackup_history table. An optional history series name may be specified that will be placed with the history record for the current backup being taken.

--host (-H)

This option specifies the host to use when connecting to the database server with TCP/IP. The option accepts a string argument. See mysql --help for details.

--incremental-basedir

(for --backup): copy only .ibd pages newer than backup at specified directory.

--incremental-dir

(for --prepare): apply .delta files and logfile in the specified directory.

--incremental-force-scan

Perform a full-scan incremental backup even in the presence of changed page bitmap data

--incremental-history-name

This option specifies the name of the backup series stored in the PERCONA_SCHEMA.xtrabackup_history history record to base an incremental backup on. MariaDB Backup will search the history table looking for the most recent (highest innodb_to_lsn), successful backup in the series and take the to_lsn value to use as the starting lsn for the incremental backup. This will be mutually exclusive with --incremental-history-uuid, --incremental-basedir and --incremental-lsn. If no valid lsn can be found (no series by that name, no successful backups by that name) MariaDB Backup will return with an error. It is used with the --incremental option.

--incremental-history-uuid

This option specifies the UUID of the specific history record stored in the PERCONA_SCHEMA.xtrabackup_history to base an incremental backup on. --incremental-history-name, --incremental-basedir and --incremental-lsn. If no valid lsn can be found (no success record with that uuid) MariaDB Backup will return with an error. It is used with the --incremental option.

--incremental-lsn

(for --backup): copy only .ibd pages newer than specified LSN 'high:low'. ##ATTENTION##: If a wrong LSN value is specified, it is impossible to diagnose this, causing the backup to be unusable. Be careful!

--innodb

Ignored option for MySQL option compatibility

--innodb-adaptive-hash-index

Enable InnoDB adaptive hash index (disabled by default).

--innodb-autoextend-increment

Data file autoextend increment in megabytes

--innodb-buffer-pool-filename

Ignored for mysqld option compatibility

--innodb-checksum-algorithm

The algorithm InnoDB uses for page checksumming. [CRC32, STRICT_CRC32, FULL_CRC32, STRICT_FULL_CRC32]. One of: crc32, strict_crc32, full_crc32, strict_full_crc32

--innodb-compression-level

Compression level used for zlib compression.

--innodb-data-file-path

Path to individual files and their sizes.

--innodb-data-home-dir

The common part for InnoDB table spaces.

--innodb-doublewrite

Enable InnoDB doublewrite buffer during --prepare.

--innodb-file-io-threads

Number of file I/O threads in InnoDB.

--innodb-file-per-table

Stores each InnoDB table to an .ibd file in the database dir.

--innodb-flush-method

With which method to flush data.. One of: fsync, O_DSYNC, littlesync, nosync, O_DIRECT, O_DIRECT_NO_FSYNC

--innodb-force-recovery

(for --prepare): Crash recovery mode (ignores page corruption; for emergencies only).

--innodb-io-capacity

Number of IOPs the server can do. Tunes the background IO rate

--innodb-log-buffer-size

The size of the buffer which InnoDB uses to write log to the log files on disk.

--innodb-log-file-size

Ignored for mysqld option compatibility

--innodb-log-group-home-dir

Path to InnoDB log files.

--innodb-max-dirty-pages-pct

Percentage of dirty pages allowed in bufferpool.

--innodb-page-size

The universal page size of the database.

--innodb-read-io-threads

Number of background read I/O threads in InnoDB.

--innodb-undo-directory

Directory where undo tablespace files live, this path can be absolute.

--innodb-undo-tablespaces

Number of undo tablespaces to use.

--innodb-use-native-aio

Use native AIO if supported on this platform. (Defaults to on; use --skip-innodb-use-native-aio to disable.)

--innodb-write-io-threads

Number of background write I/O threads in InnoDB.

--kill-long-queries-timeout

This option specifies the number of seconds mariadb-backup waits between starting FLUSH TABLES WITH READ LOCK and killing those queries that block it. Default is 0 seconds, which means mariadb-backup will not attempt to kill any queries.

--kill-long-query-type

This option specifies which types of queries should be killed to unblock the global lock. Default is "all".. One of: ALL, UPDATE, SELECT

--lock-ddl-per-table

This option tells MariaDB Backup to obtain a read metadata lock for each table, which can prevent concurrent DDL from occurring during the backup. Before the backup starts, MariaDB Backup acquires a metadata lock for each individual table on the system. The metadata locks are released when the backup completes.

--log

Ignored option for MySQL option compatibility

--log-bin

Base name for the log sequence

--log-copy-interval

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

--log-innodb-page-corruption

Continue backup if innodb corrupted pages are found. The pages are logged in innodb_corrupted_pages and backup is finished with error. --prepare will try to fix corrupted pages. If innodb_corrupted_pages exists after --prepare in base backup directory, backup still contains corrupted pages and can not be considered as consistent.

--move-back

Move all the files in a previously made backup from the backup directory to the actual datadir location. Use with caution, as it removes backup files.

--mysqld-args

All arguments that follow this argument are considered as server options, and if some of them are not supported by mariabackup, they will be ignored.

--no-backup-locks

This option is related to special backup locks in Percona Server. This option is not supported with MariaDB Server.

--no-defaults

Don't read default options from any option file.

--no-lock

Use this option to disable table lock with "FLUSH TABLES WITH READ LOCK". Use it only if ALL your tables are InnoDB and you DO NOT CARE about the binary log position of the backup. This option shouldn't be used if there are any DDL statements being executed or if any updates are happening on non-InnoDB tables (this includes the system MyISAM tables in the mysql database), otherwise it could lead to an inconsistent backup. If you are considering to use --no-lock because your backups are failing to acquire the lock, this could be because of incoming replication events preventing the lock from succeeding. Please try using --safe-slave-backup to momentarily stop the replication slave thread, this may help the backup to succeed and you then don't need to resort to using this option.

--no-version-check

This option disables the version check which is enabled by the --version-check option.

--open-files-limit

the maximum number of file descriptors to reserve with setrlimit().

--parallel

Number of threads to use for parallel datafiles transfer. The default value is 1.

--password (-p)

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

--plugin-dir

Server plugin directory. Used to load encryption plugin during 'prepare' phase.Has no effect in the 'backup' phase (plugin directory during backup is the same as server's)

--port (-P)

This option specifies the port to use when connecting to the database server with TCP/IP. The option accepts a string argument. See mysql --help for details.

--prepare

prepare a backup for starting mysql server on the backup.

--print-defaults

Print the program argument list and exit.

--print-param

print parameter of mysqld needed for copyback.

--protocol

The protocol to use for connection (tcp, socket, pipe, memory).

--remove-original

Remove .qp files after decompression.

--rocksdb-backup

Backup rocksdb data, if rocksdb plugin is installed.Used only with --backup option. Can be useful for partial backups, to exclude all rocksdb data (Defaults to on; use --skip-rocksdb-backup to disable.)

--rocksdb-datadir

RocksDB data directory.This option is only used with --copy-back or --move-back option

--rsync

Uses the rsync utility to optimize local file transfers. When this option is specified, mariadb-backup uses rsync to copy all non-InnoDB files instead of spawning a separate cp for each file, which can be much faster for servers with a large number of databases or tables. This option cannot be used together with --stream.

--safe-slave-backup

Stop slave SQL thread 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 --safe-slave-backup-timeout seconds. The slave SQL thread will be restarted when the backup finishes.

--safe-slave-backup-timeout

How many seconds --safe-slave-backup should wait for Slave_open_temp_tables to become zero. (default 300)

--secure-auth

Refuse client connecting to server if it uses old (pre-4.1.1) protocol. (Defaults to on; use --skip-secure-auth to disable.)

--slave-info

This option is useful when backing up a replication slave server. It prints the binary log position and name 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.

--socket (-S)

This option specifies the socket to use when connecting to the local database server with a UNIX domain socket. The option accepts a string argument. See mysql --help for details.

--ssl

Enable SSL for connection (automatically enabled with other flags).

--ssl-ca

CA file in PEM format (check OpenSSL docs, implies --ssl).

--ssl-capath

CA directory (check OpenSSL docs, implies --ssl).

--ssl-cert

X509 cert in PEM format (implies --ssl).

--ssl-cipher

SSL cipher to use (implies --ssl).

--ssl-crl

Certificate revocation list (implies --ssl).

--ssl-crlpath

Certificate revocation list path (implies --ssl).

--ssl-key

X509 key in PEM format (implies --ssl).

--ssl-verify-server-cert

Verify server's "Common Name" in its cert against hostname used when connecting. This option is disabled by default.

--stream

Stream all backup files to the standard output in the specified format.Supported format is 'mbstream' or 'xbstream'.

--tables

filtering by regexp for table names.

--tables-exclude

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

--tables-file

filtering by list of the exact database.table name in the file.

--target-dir

destination directory

--throttle

limit count of IO operations (pairs of read&write) per second to IOS values (for '--backup')

--tls-version

TLS protocol version for secure connection.

--tmpdir (-t)

Path for temporary files. Several paths may be specified, separated by a colon (:), in this case they are used in a round-robin fashion.

--use-memory

The value is used in place of innodb_buffer_pool_size. This option is only relevant when the --prepare option is specified.

--user (-u)

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.

--verbose (-V)

display verbose output

--version (-v)

This option tells MariaDB Backup to print version information and then quit.

The following Command-line Options are not present in MariaDB Community Server 10.6.14 but are present in one or more older 10.6 CS versions. Click on an item to see its details, including when it was removed.

Option

Description

--debug-sleep-before-unlock

This is a debug-only option used by the MariaDB Backup test suite.

--debug-sync

Debug sync point. This is only used by the MariaDB Backup test suite.

--sst-max-binlogs

Number of recent binary logs to be included in the backup. Setting this parameter to zero normally disables transmission of binary logs to the joiner nodes during SST using Galera. But sometimes a single current binlog can still be transmitted to the joiner even with sst_max_binlogs=0, because it is required for Galera to work properly with GTIDs support.