Backup and restore overview

Aerospike provides several tools for backing up and restoring data in your database clusters.

Available tools

Tool	Description	Best for
Aerospike Backup Service (ABS)	REST API service for scheduled backups	Automated backup routines, continuous incremental backups, enterprise environments
Aerospike Backup Control (absctl)	Go-based CLI tool for on-demand backup and restore operations	Ad-hoc backups and restores, scripted jobs
asbackup / asrestore (Legacy)	C-based CLI tools	Legacy systems, Aerospike Database versions before 5.7.0

Aerospike Backup Service

Aerospike Backup Service (ABS) runs as a standalone service and provides REST API endpoints for backup and restore operations. ABS is ideal for automated backup routines with configurable schedules and policies.

Key features:

Scheduled backups: Configure full and incremental backup schedules
Multiple backup policies: Define different retention periods, compression settings, and storage locations
REST API to trigger backups on demand
Monitoring integration
Works with Aerospike Kubernetes Operator (AKO)

For installation and configuration, see Aerospike Backup Service.

Aerospike Backup Control

Aerospike Backup Control (absctl) is a Go-based command-line tool for backup and restore operations. Use absctl backup to create backups and absctl restore to restore or validate backups.

Key features:

Native support for AWS S3, Google Cloud Storage, and Azure Blob Storage, including storage classes and access tiers
Zone-aware backups to minimize cross-datacenter traffic
Configurable JSON log output for integration with monitoring systems
YAML configuration files for repeatable backup operations

For installation and usage, see:

Legacy tools

The legacy asbackup and asrestore tools are C-based command-line utilities used for:

Aerospike Database versions before 5.7.0
Existing automation scripts not yet migrated to the newer tools

Architecture

Backup file format

All Aerospike backup tools use the .asb file format, which stores:

Record data (keys, bins, metadata)
Secondary index definitions
User-defined function (UDF) modules

Backups created with any Aerospike backup tool can be restored with any compatible restore tool.

ASB protocol version 3.2 supports expression-based secondary indexes. When backing up to a directory, metadata (UDFs and secondary indexes) is stored in separate metadata_*.asb files. When using --output-file, all data is written to a single file.

Full and incremental backups

Full backups create a complete copy of all data.

Incremental backups copy only the data that changed since the most recent full or incremental backup.

For example, if you create a full backup at 2:00 PM and an incremental backup at 2:30 PM, the incremental backup contains only records modified between 2:00 and 2:30 PM. When you restore from the 3:00 PM backup, the restore process combines the full backup data with all subsequent incremental changes.

Compression and encryption

All backup tools support ZSTD compression and AES-128 or AES-256 encryption.

When restoring compressed or encrypted backups, you must specify the same compression and encryption settings that were used to create the backup.

Cloud storage support

Provider	ABS	absctl	Legacy asbackup/asrestore
AWS S3	✓	✓	✓
Google Cloud Storage	✓	✓	✗
Azure Blob Storage	✓	✓	✗
Local storage	✓	✓	✓

absctl backup and absctl restore both support storage classes and access tiers:

AWS S3: Use --s3-storage-class to specify STANDARD, GLACIER, DEEP_ARCHIVE, and other storage classes
Azure: Use --azure-access-tier to specify Hot, Cool, Cold, or Archive tiers
Restore from archive: Both absctl restore and ABS can restore files from archived storage tiers

Frequently asked questions

Which tool should I use?

Use Aerospike Backup Service when:

You need automated scheduled backups
You want to manage multiple backup policies through a REST API
You’re running Aerospike Database on Kubernetes with AKO
You need continuous incremental backups with managed retention

Use absctl when:

You need ad-hoc or scripted backup and restore operations
You need zone-aware backups with rack filtering (with absctl backup)
You’re migrating from existing backup workflows using the legacy tools

Use legacy tools (asbackup/asrestore) only when:

You’re running Aerospike Database versions before 5.7.0
You have existing automation that hasn’t been migrated

How is Aerospike Backup Service different from absctl?

ABS runs as a separate service that listens for REST API requests to trigger backup and restore operations. absctl runs as a CLI command (for example, absctl backup or absctl restore) and exits when the operation completes.

Backups made with ABS can be restored with absctl restore, and backups made with absctl backup can be restored with ABS.

Both backup solutions use the same Go-based backup library.

What happens when a backup doesn’t finish before another starts in the same routine?

In Aerospike Backup Service:

Full backups cannot overlap. If a scheduled full backup is due to start but the previous one is still running, the new backup is skipped. Full backups always take priority over incremental backups.
Incremental backups are skipped by default if any other backup is running. Set concurrent-incremental to true to allow overlapping incremental backups.
Incremental backups do not run until at least one full backup has completed successfully.

Can multiple backup routines run simultaneously?

Yes, multiple backup routines can run in parallel in ABS. You can back up different namespaces from the same cluster using separate routines with different schedules.

To manage resource utilization, configure aerospike-clusters.CLUSTER_NAME.max-parallel-scans to limit the number of read threads operating on a single cluster.

Are backups from the different CLI tool versions compatible with each other?

Yes. Backups created with the legacy asbackup tool can be restored with absctl restore or ABS. Backups created with absctl backup can be restored with tools that understand the ASB format.

The backup file format (.asb) is unchanged, though new features like expression-based secondary indexes use ASB protocol version 3.2.

What privileges are required for backup and restore?

For backup: read privileges or higher.

For restore: The required privileges depend on the namespace contents:

Basic records: read-write
User-defined functions: udf-admin (Database 6.0.0 and later) or data-admin
Secondary indexes: sindex-admin (Database 6.0.0 and later) or data-admin

See Configuring access control for more information.