5.1.5 Backup Repository Options

These options specify various parameters related to the layout of the backup directory.

The --backup-dir option is the only one from this group that you typically specify. Values for all the backup_innodb_* options can be derived automatically from the corresponding configuration options without the backup_ prefix (see descriptions for individual options below). Those options need to be specified only if, during a backup, the user wants to specify particular values for those options that are to be used during restorations of the backup. Values specified by backup_innodb_* options are stored in the backup_my.cnf file, to be used during future restorations.

When a database connection is available during a backup, those backup_innodb_* options are ignored, with their values overridden by the corresponding values retrieved from the database connection. .

These options are used only with the following operations:

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

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

The following parameters describe the layout of files in the backup directory:

• --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:

  • If backup_innodb_data_home_dir is not specified, it inherits the value of backup-dir.

  • If backup_innodb_data_home_dir is a relative path, that path is located relative to (that is, underneath) the backup-dir value.

  • An backup_innodb_data_home_dir of "" refers to the / root directory.

  • If backup_innodb_data_home_dir is an absolute path, its value is used as-is.

  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:

  • Specified backup_innodb_log_files_in_group value from command line or configuration file.

  • Else innodb_log_files_in_group value from the database connection, if available.

  • Else the innodb_log_files_in_group value from the command line or configuration file.

• 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:

  • Specified backup_innodb_log_file_size value from command line or configuration file.

  • Else innodb_log_file_size value from database connection, if available.

  • Else specified innodb_log_file_size value from command line or configuration file.

• 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.