5.8.2 The backup cluster Command

5.8.2 The `backup cluster` Command

backup cluster [{--backupid=|-I }backup_id]
    [{--snapshotstart|-S} | {--snapshotend|-E}]
    [{--waitstarted|-w} | {--waitcompleted|-W}]
    [{--password-file=|-F }filepath]
    cluster_name

This command creates a backup of the MySQL NDB Cluster named cluster_name. backup cluster takes a backup of the cluster's NDB tables only; tables using other MySQL storage engines (such as InnoDB or MyISAM) are ignored.

By default, this command uses the backup ID assigned and returned by ndb_mgmd (see the discussions on backup_id in Using The NDB Cluster Management Client to Create a Backup for more information); you can override this behavior by specifying a backup ID using the --backupid option (short form is -I).

The --snapshotstart option (short form is -S) causes the backup to match the state of the cluster when the backup began.

The --snapshotend option (short form is -E) causes the backup to reflect the state of the cluster when the backup was finished. If neither option is specified, the MySQL Cluster Manager client acts as though --snapshotend had been used.

When the --waitstarted option (short form is -w) is used, the MySQL Cluster Manager client waits until the backup has started before returning control to the user, after which the user can check the backup process's status with the show status command and the --backup option.

When the --waitcompleted option (short form is -W) is used, the MySQL Cluster Manager client waits until the backup process is complete before returning control to the user. If neither --waitstarted or --waitcompleted is specified, the client behaves as if --waitcompleted had been used.

mcm> backup cluster mycluster;
+-------------------------------+
| Command result                |
+-------------------------------+
| Backup completed successfully |
+-------------------------------+
1 row in set (33.50 sec)

You can verify that the backup was performed by checking the output of list backups, as shown here:

mcm> list backups mycluster;
+----------+--------+---------+----------------------+-------+---------+
| BackupId | NodeId | Host    | Timestamp            | Parts | Comment |
+----------+--------+---------+----------------------+-------+---------+
| 1        | 1      | tonfisk | 2016-10-24 22:24:54Z | 1     |         |
| 1        | 2      | tonfisk | 2016-10-24 22:24:54Z | 1     |         |
| 2        | 1      | tonfisk | 2016-10-24 22:24:54Z | 1     |         |
| 2        | 2      | tonfisk | 2016-10-24 22:24:54Z | 1     |         |
+----------+--------+---------+----------------------+-------+---------+
4 rows in set (0.02 sec)

Each row in the output represents a backup image—that is, a set of backup files specific to a given backup of a named cluster on a given data node. Timestamp values are in UTC. The backup image is saved in the folder BackupDataDir/BACKUP/BACKUP-Id, where BackupDataDir is a cluster parameter. If BackupDataDir is not specified, it takes up the value of DataDir, so that the image is stored in the directory Datadir/BACKUP/BACKUP-backup_id.

It is possible to remove an unwanted backup from a given node by deleting this image directory and its contents. To remove a given backup completely, you must remove the corresponding image from each data node's BACKUP directory. You can do this as long as a backup or restore operation is not in progress. It is not necessary to stop the cluster or MySQL Cluster Manager agent prior to removing the images.

The BackupId is used with abort backup and restore cluster.

MySQL Cluster Manager supports the creation of NDB native encrypted cluster backups using AES-256-CBC. To create an encrypted backup, use the --password-file option (short form is -F) to provide a file that contains the password. See Using The NDB Cluster Management Client to Create a Backup for restrictions on the choice of passwords. The password file must satisfy the following requirements:

The file must be present on the same host as the mcmd agent that the client issuing the backup cluster command is connected to.
A relative file path is considered relative to the working directory of the mcmd agent mentioned in the last bullet.
On Unix-like platforms, the file should only be readable and writable by the file owner; on Windows platforms, it should not be readable by the Everyone group.

Logical Backup for NDB Table Metadata

To allow more flexibility for cluster reconfiguration during a restore, the backup cluster command also creates a logical backup for the metadata of the NDB tables in the cluster. Use the --all option with the list backups command to list all backups, including the logical backups for the NDB tables' metadata, which are marked by the comment “Schema”:

mcm> list backups --all newcluster;
+----------+--------+---------+----------------------+------+---------+
| BackupId | NodeId | Host    | Timestamp            | Part | Comment |
+----------+--------+---------+----------------------+------+---------+
| 1        | 1      | tonfisk | 2016-08-12 16:55:52Z | 1    |         |
| 1        | 2      | tonfisk | 2016-08-12 16:55:52Z | 1    |         |
| 1        | 3      | tonfisk | 2016-08-12 16:55:52Z | 1    |         |
| 1        | 4      | tonfisk | 2016-08-12 16:55:52Z | 1    |         |
| 1        | 50     | tonfisk | 2016-08-12 16:55:55Z |      | Schema  |
+----------+--------+---------+----------------------+------+---------+
5 rows in set (0.02 sec)

The logical backup was created using the mysqldump utility. The backup is saved with the file name BACKUP-BackupID.mysql_nodeid.schema.sql extension, to be found in the folder backupdatadir/BACKUP/BACKUP-id, where backupdatadir (notice that the name is in lowercase) is a mysqld parameter used only for specifying the location of the logical backup created by MySQL Cluster Manager. If backupdatadir is not specified using the set command with the mcm client, the default value of /mcm_data_repository/clusters/clustername/mysqld_nodeid/ is used, so that the logical backup is saved in the folder /mcm_data_repository/clusters/clustername/mysqld_nodeid/BACKUP/BACKUP-Id.

The following restrictions apply for the creation of the logical backups for NDB table metadata:

At least one mysqld node must be running on the cluster for the logical backup to be performed
No backup was created for any mysqld node that was not running.
Metadata for non-NDB tables are not backed up.
The logical backup is NOT a proper point-in-time backup—no DDL operations should be performed on the cluster when the backup process is running on the cluster, or the backed-up metadata will become inconsistent with the backed-up data.

The backup for the NDB table metadata is helpful for restoring data from a cluster to another one with a different configuration (for example, when the target cluster for restore has a different number of data nodes); see Section 4.6.2.4, “Partial restore—data nodes added” and Section 4.6.2.5, “Restoring a Backup to a Cluster with Fewer Data Nodes” for some use cases.