Documentation Home
MySQL Enterprise Backup 3.8 User's Guide
Download this Manual
PDF (US Ltr) - 0.9Mb
PDF (A4) - 0.9Mb
EPUB - 203.0Kb
HTML Download (TGZ) - 158.6Kb
HTML Download (Zip) - 182.5Kb

MySQL Enterprise Backup 3.8 User's Guide  /  ...  /  Changes in MySQL Enterprise Backup 3.8.1 (2013-02-05)

D.2 Changes in MySQL Enterprise Backup 3.8.1 (2013-02-05)

This section documents changes and bug fixes that have been applied in MySQL Enterprise Backup, from version 3.5.1 through version 3.8.1. The 3.8.1 release contains mainly fixes and enhancements compatibility with features of MySQL 5.6.

Functionality Added or Changed

  • Prior to version 3.8.1, mysqlbackup ignores the --slave-info option if the --no-locking option was also used. mysqlbackup now throws an error if the two options are used together. (Bug #16582193)

  • In MySQL 5.6, you can change the physical layout of the InnoDB system tablespace through the configuration options innodb_undo_directory, innodb_undo_tablespaces, and innodb_undo_logs (formerly innodb_rollback_segments). These options move the InnoDB undo log into one or more separate files, possibly outside the MySQL data directory or even on a different storage device. These files are named with sequential numbers: undo001, undo002, undo003, and so on, up to the number specified by innodb_undo_tablespaces.

    The mysqlbackup command recognizes these options during a backup, and retrieves the associated files from the specified location. When the mysqlbackup command creates a backup, it always stores these undo data files in the same directory as the other data files making up the system tablespace. During a restore operation, the files are copied to the appropriate location, depending on the setting for innodb_undo_directory on the server where restore takes place. (Bug #16168947)

  • New server options present in MySQL 5.6 are accepted on the mysqlbackup command line when a database connection is not available, and are stored along with other instance-wide settings in the backup metadata:

    • The page size and checksum algorithm settings for the backed-up instance are recorded in the backup_create.xml file.

    • You can specify --innodb_page_size=SIZE and --innodb_checksum_algorithm=NAME on the command line if a database connection is not available.

    (Bug #16033618, Bug #15951510)

  • MySQL Enterprise Backup can now handle InnoDB tables backed up to non-standard locations using the DATA DIRECTORY clause of the MySQL 5.6 CREATE TABLE statement. For each table created outside the database subdirectory, a .isl file in the database subdirectory contains the absolute pathname of the associated .ibd file, acting like a symbolic link to the actual tablespace file.

    The mysqlbackup command reads the .isl files to locate the associated .ibd files during a backup. It stores the .isl files in the backup directory using the extension .bl. If the server where you restore the backup does not have the same directory structure as the backup server, and you need to put the restored .ibd files in some different location, edit the .bl files before doing the restore. (Bug #15932375)

  • Backups can be taken while online DDL operations are in progress on InnoDB tables. See InnoDB and Online DDL for details about this MySQL 5.6 feature. (Bug #15932180)

  • MySQL Enterprise Backup supports the GTID feature of MySQL 5.6:

    • The GTID feature is compatible with the CSV tables that the mysqlbackup command uses to log job progress and history.

    • When a server using the GTID feature is backed up, mysqlbackup produces a file gtid_executed.sql as part of the backup data. This file contains a SQL statement that sets the GTID_PURGED configuration option. Execute this file using the mysql command line after restoring the backup data on a slave server. Optionally, you can uncomment the CHANGE MASTER command in this file and add any needed authentication parameters to it, before running it through mysql.

    • For servers not using GTIDs, you can use the --slave-info option as before, then edit and execute the ibbackup_slave_info file afterward.

    For more information about using MySQL Enterprise Backup with replication, see Chapter 6, Using MySQL Enterprise Backup with Replication. (Bug #14767426, Bug #14797808, Bug #14722659)

  • MySQL 5.6 includes the innodb_page_size configuration option to set a page size other than the traditional 16KB default. The page size is set permanently when the instance is created, and cannot be changed afterward.

    The mysqlbackup command can back up MySQL instances that use any of the new page sizes (8KB, 4KB, 2KB, or 1KB). When restoring, set innodb_page_size to the same value as on the server that was backed up; otherwise, the restore operation halts with an error. (Bug #14761559, Bug #16070834)

  • Normally, the InnoDB system tablespace is extended by one or more megabytes at a time. Under some circumstances, particularly in a disk-full or almost-full situation, MySQL can extend the InnoDB system tablespace by some amount less than a megabyte, and this trailing portion is unused. Now the mysqlbackup command backs up such oddly sized system tablespaces even though the size does not precisely match the specified size. This condition causes a warning rather than an error. The unused fractional megabyte is removed from the backup data. (This particular file-size feature applies only to the system tablespace, not to the file-per-table tablespaces in the .ibd files.)

  • The mysqlbackup command now supports the UNC (Universal or Uniform Naming Convention) syntax for specifying locations on shared disks. This feature lets you start backups to shared drives using Windows Task Scheduler, when shared drives cannot be mapped to a drive letter.

    The UNC syntax for Windows systems has the generic form:


    You can use either forward or backward slashes in the path names.

    The mysqlbackup command does not support the "long UNC" syntax:


    The UNC path names can be specified with any backup command and option.


    Do not use UNC paths to specify the location of InnoDB data files and log files to be backed up. Such files cannot be reliably backed up over a network file system. MySQL Enterprise Backup does not issue any warning in this case.

Bugs Fixed

  • Important Change: When backing up a slave server using the --slave-info option, updates could be lost when restoring the backup and starting replication using the command in the meta/ibbackup_slave_info file. This issue could arise if the replication SQL thread was not in synch with the replication I/O thread.

    Prior to this fix, the workaround for backups with the --slave-info option was to stop the I/O thread and wait for the SQL thread to catch up before starting the backup. (Bug #13588571, Bug #15865869)

  • An apply-log operation could fail if the server used an innodb_page_size setting different from the default of 16KB. (Bug #16084912)

  • The --suspend-at-end and --exec-when-locked options did not work properly in MySQL Enterprise Backup 3.8. The suspension code has been rewritten to work in conjunction with the multithreaded system of readers and writers. (Bug #16078126, Bug #16168131)

  • MySQL Enterprise Backup 3.8.1 now supports the different checksum settings of the innodb_checksum_algorithm configuration option in MySQL 5.6.

    Prior to MySQL Enterprise Backup 3.8.1, when the value of the innodb_checksum_algorithm was strict_crc32 or strict_none, the server could not be started after a sequence of backup, apply-log, and restore operations. Checksums were created in the InnoDB data files during the apply-log phase that were incompatible with the checksum algorithms required in the server.

    With this fix in place, there are still some restrictions regarding the settings for the innodb_checksum_algorithm during backup and restore:

    • A server backed up while the strict_crc32, strict_innodb, or strict_none setting is in effect for innodb_checksum_algorithm must be restored to a server with that same innodb_checksum_algorithm setting.

    • If a server contains data produced under different innodb_checksum_algorithm settings, because the option setting was changed during the lifetime of the server, that data cannot be restored to a server with one of the strict_* options for innodb_checksum_algorithm.

    (Bug #15951510)

  • When a slave server was backed up with the --slave-info option, the meta file backup_content.xml contained incorrect data in the section underneath the <binlog_file> tag. (Bug #15926218)

  • The mysqlbackup command could encounter a severe error during the apply-log step, or the corresponding phase of apply-incremental-backup, if DML or DDL had been done during the backup. (The apply log algorithm rounded the size of data files to the next lower 1MB border, if the size was not an exact number of megabytes. The apply log algorithm also did not ignore temporary data files and failed when it detected duplicate tablespace IDs.) (Bug #15841875, Bug #14704347, Bug #15932180)

  • A backup operation could fail with a serious error (segmentation fault) if the --connect-if-online option was specified and the MySQL server was not online. (Bug #14788375)

  • There are 2 database connections used by the mysqlbackup command. The first connection is used for reading server configuration, and locking and updating the history table. The second connection is used for reading incremental base details during incremental backup. The second connection did not specify an autocommit setting, possibly causing a stall when the server had the setting autocommit=0. Now mysqlbackup specifies autocommit=1 automatically in this connection. (Bug #14637052)

  • If the .ibd file for an InnoDB table created under the innodb_file_per_table option was renamed or removed while a backup was in progress, the mysqlbackup command could fail. This issue primarily affected tables with a size greater than 60 MB that were dropped or renamed during the backup operation. (Bug #14590007)

  • The password specified by the --password option was printed in mysqlbackup command output, rather than being masked. This issue affected the mysqlbackup command, but any password parameters recorded in the backup_history table were masked correctly. (Bug #14576054)

  • The default for the option --only-innodb-with-frm was mistakenly set to all when it was intended to be related. The default for that option is now related. (Bug #14507779)

  • This fix addresses problems doing a single-file backup (using the --backup-image option) when the innodb_data_file_path or innodb_data_home_dir configuration options contained absolute paths. This issue typically affected configurations with InnoDB files split across multiple storage devices. The symptoms and associated fixes are:

    • The backup operation failed if InnoDB data files were placed in a subdirectory of datadir. Now mysqlbackup creates all required subdirectories in the backup_dir directory.

    • The backup operation failed if InnoDB data files were placed in a sub-subdirectory of datadir. It refused to work if any directory was found in the database directories. The error is now a warning instead.

    • InnoDB data files were copied twice, if they were in a subdirectory of datadir: once during the phase the copies InnoDB files and again in the phase that copies non-InnoDB files. During this second phase, all files in the database directories are copied, which mistakenly included the InnoDB files from subdirectories of datadir. Now mysqlbackup compares each filename from the datadir subdirectories against each InnoDB data file name from the system tablespace, to avoid copying the files a second time. .ibd files were not affected by this issue, as they are recognized by their file name extension.

    • MEB can now back up system tablespace data files inside the source datadir if backup_innodb_data_home_dir and backup_innodb_data_file_path were configured accordingly. Fixed by checking each backup target system tablespace data file against the server's datadir.

    (Bug #14499912)

  • On a busy server with a high write workload, the mysqlbackup command could fail with an error such as:

    mysqlbackup: ERROR: Page at offset 0 number in 
    /path/db_name#table_name.ibd seems corrupt!

    The problem was due to a race condition where a checksum was written just as the page was being backed up, before the corresponding data was stored on the page. Now mysqlbackup waits and re-tries the read operation when a checksum mismatch occurs. The new mysqlbackup options --page-reread-time and --page-reread-count let you adjust the mechanism for re-trying page reads. If you continue to encounter such errors, re-try the backup with higher values for these options to reduce the possibility of encountering the race condition. (Bug #14489495)

  • A configuration file with --ssl-* options in the [client] section caused the mysqlbackup command to fail, rather than being ignored as with most other unused options. A workaround was to copy the configuration file, remove the --ssl-* parameters, and run mysqlbackup with the --defaults-file option to use the smaller configuration file.

    The fix causes mysqlbackup to recognize and handle all the SSL options currently recognized by the server: --ssl, --ssl-key, --ssl-cert, --ssl-ca, --ssl-capath, --ssl-cipher, and --ssl-verify-server-cert. (Bug #13520946)

  • The --slave-info option is not compatible with --only-innodb-with-frm, --only-innodb-with-frm=all, or --only-innodb-with-frm=related. Now the mysqlbackup command reports a command-line error if you specify those options in combination. (Bug #13414742, Bug #63355)

  • If the MySQL server had a low value for the wait_timeout configuration option, large backups (particularly for large MyISAM tables) could fail due to timeout errors. The timeout could also prevent the mysql.backup_progress table from recording the final details of the failed backup. The fix raises the value of wait_timeout to the maximum value within the session opened by the mysqlbackup command. The maximum timeout value is platform-specific: approximately 24 days on Windows systems, and 1 year for other platforms. (Bug #13258784, Bug #13416025, Bug #14468879)

Download this Manual
PDF (US Ltr) - 0.9Mb
PDF (A4) - 0.9Mb
EPUB - 203.0Kb
HTML Download (TGZ) - 158.6Kb
HTML Download (Zip) - 182.5Kb
User Comments
Sign Up Login You must be logged in to post a comment.