How to Migrate Aerospike from one Cluster to Another

The Aerospike Knowledge Base has moved to Content on is being migrated to either or Maintenance on articles stored in this repository ceased on December 31st 2022 and this article may be stale. If you have any questions, please do not hesitate to raise a case via


This article describes how to clone or migrate data from one cluster to another with no to minimal downtime.


There are situations where you may need to migrate Aerospike from an older cluster to a newer cluster with no to minimal downtime.

Use the following steps:

  1. If you have created user and roles, make sure to check the details and re-create those on the new cluster.

  2. Install Aerospike on the new cluster.

  3. Set up XDR to ship from old data center to new data center. (Must be done on all nodes of the old cluster, can be done in a rolling fashion).

    • Note that XDR will only ship newly written data. Thus, we will have to move the existing data to the new cluster. This can be done a few different ways:

      • Leverage the rewind feature if using XDR 5.0 or above. Refer to the How to rewind XDR for a namespace article.

      • Scan and touch all the records in the original cluster, setting the TTL to -2. Note that last-update-time of records will be changed so incremental backup/truncate features will be affected. An example UDF to do this would be

      function touch(rec)
         record.set_ttl(rec, -2)

      As always, test on your system before using in production.

      • Backup / Restore with the “-u” or “–unique” option (while pausing XDR shipping to avoid overwriting potential deletes). The following steps describe this method.
  4. To avoid potentially overwriting delete transactions, make sure to disable xdr shipping prior to taking the backup. If the use case or setup does not allow disabling xdr shipping prior to taking the backup, any records which would be deleted on the old cluster after the backup is taken would be restored from backup/restore process.

  5. For each namespace:

    1. Take a backup of the old data center, using the asbackup tool.

      # Example
      asbackup --host NODE_IP --namespace NAMESPACE_NAME --directory backups/NAMESPACE_NAME

      With server version 3.12 or above, you can do an incremental backup (“–modified-before” option) to specify only records before XDR has started shipping.

    2. Using the “-u” option, restore the backed up data on the new data center using the asrestore tool.

      Note: “–unique” instructs the asrestore to not overwrite existing records. If you omit this option, then by default, asrestore will check the generation, you may either get ‘generation mismatch’ error or will overwrite the records in the cluster that might be a different copy as shipped by XDR (XDR does not preserve generation when shipping). You can read more on asrestore write policies.

      # Example
      asrestore --host NODE_IP --directory backups/NAMESPACE_NAME --unique
    3. If intermediate files are not needed, the stdout of asbackup can be piped out to the stdin of asrestore: When running the command below, it will backup the data from the full source cluster. One of the nodes to be specified, SOURCE_NODE_IP, will be acting as the entry point to the cluster. The remaining cluster nodes will be automatically discovered. The other node to be specified, TARGET_NODE_IP, is one of the node of the target cluster, which will act as the entry point to the cluster. The remaining cluster nodes will be automatically discovered. Again, this method will not generate any backup files for future reference or use.

      # Example
      asbackup -h SOURCE_NODE_IP -n NAMESPACE_NAME --outputfile - | asrestore -h TARGET_NODE_IP --inputfile - --unique
  6. Re-enable XDR. (Use this Knowledge Base article for pre-5.0.) Monitor the throughput and, if necessary, limit it using the max-throughput configuration parameter (or xdr-max-ship-throughput for pre-5.0).

  7. Allow XDR to synchronize completely, and verify that XDR lag is zero.

  8. Redirect clients to new datacenter.

    1. (Option 1) Redirect all clients to the new datacenter.
    2. (Option 2) Redirect clients to the new datacenter one at a time. This avoid downtime but some updates during the transition will be lost.
  9. You may have to add user/roles if they have not been setup at step 1.

  10. To tune asbackup and restore process, please check this KB - Common asbackup and asrestore questions FAQ - Common asbackup and asrestore questions

Special case:

If the plan is to setup an active-active XDR, then before restoring the backup on the new cluster please disable xdr dynamically for the namespace you are restoring. After you are done restoring you can enable it again.

For versions prior to 3.6.1 Tools release:

Use the older backup and restore conventions -

asrestore -h NODE_IP -d backups/NAMESPACE_NAME -u



backup restore migrate replicate older existing


October 2020

Can I ask two questions? (1) XDR is only in Enterprise version, right? (2) The NODE_IP and directory is old cluster’s, right? Even though for step 3.2 which is run in new cluster?

Yes, XDR is Enterprise only.

In 3.2, NODE_IP is for the new cluster, the directory is the path the the backup taken in step 3.1, you could, optionally, move these files to the new cluster and restore from there.

is it possible only to copy the differences rather than full-set backup files ? Or else, move these files by network is too heavy.

Incremental backup is coming soon… stay tuned.

Incremental Backup

Starting from Server and Tools version 3.12, timestamp can be specified when initiating a backup to indicate the time-period of interest. Only records whose last-update-time satisfies the specified criteria (before time T1 and/or after time T2) will be backed up. An operational routine can be established to do incremental daily backups. Use the --modified-after option.

–modified-after <YYYY-MM-DD_HH:MM:SS> - Backup data with last-update-time after the specified date-time. The system’s local timezone applies. Available in Server 3.12 and above.

See: Backing up and Restoring Data with asbackup and asrestore | Aerospike Documentation See: asbackup command-line options | Aerospike Documentation See: Aerospike Tools Release Note | Download | Aerospike

I can create backup without XDR? And I can will use aerospike commands in bash script for migration to other cluster?

XDR is used so that you can migrate a live cluster to a new cluster. Without it you will need to shut off all traffic to the old cluster while taking the backup and restore and only starting the clients targeting the new cluster after it has been fully restored.

To minimize the downtime, you could take a backup with live traffic and restore it on the new cluster. Then shutdown the write load and take another incremental backup and restore that to the new cluster. Then you could star the clients targeting the new cluster. The downtime would now be the time to take and restore the incremental backup instead of the full backup.