Restore data with Aerospike Backup Service

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Aerospike Backup Service (ABS) restores data asynchronously. A restore request returns a job ID. Poll that ID until the job reaches a terminal status.

For how full and incremental backups form a chain, see Concepts. For request bodies, see API usage examples.

Applies to

Product: Aerospike Backup Service (ABS) 3.7.x.
Audience: database administrators and operators who restore data after data loss, for disaster recovery, or into another cluster.
Outcome: GET /v1/restore/status/JOB_ID reports success, and the record counters (read-records, inserted-records, fresher-records) match what you expected to restore.

Set BASE_URL to your ABS listen address:

export BASE_URL=http://localhost:8080

Before you start

ABS is installed and can reach the destination Aerospike Database cluster. See Install Aerospike Backup Service.
The backup chain is in the storage that ABS reads: a full backup, plus any incremental backups up to the restore time. GET /v1/backups/full and GET /v1/backups/incremental list what exists.
The Database user on the destination cluster has read-write to restore records. Restoring UDFs requires udf-admin (Database 6.0.0 and later) or data-admin. Restoring secondary indexes and set indexes requires sindex-admin (Database 6.0.0 and later) or data-admin. See Privileges.

Choose a restore method

Method	Endpoint	Use when
Timestamp	`POST /v1/restore/timestamp`	You want the cluster at a point in time. With `incr-mode: differential` (default), ABS restores the last full backup before `time`, then every incremental up to `time`. With `incr-mode: cumulative`, ABS restores that full backup plus the latest covering incremental.
Path	`POST /v1/restore/full`	You want one backup directory. You pass storage plus `backup-data-path` (the `key` from `GET /v1/backups/full`). The path is relative to the storage `path` and must be clean (no `..`).

Timestamp restore is the usual disaster-recovery path. Path restore is useful when you already identified a backup directory, or when you restore onto a cluster that does not define the original routine.

Restore by timestamp

time is Unix time in milliseconds (an absolute instant). schedule-timezone does not change how it is interpreted. ABS restores the closest backup state before that time. The backup timestamp is the time the job started, not the time it finished.

Standard restore using a routine that exists in the local configuration:

{
  "routine": "app-daily",
  "time": 1739538000000
}

curl -s -X POST "$BASE_URL/v1/restore/timestamp" \
  -H "Content-Type: application/json" \
  -d '{"routine":"app-daily","time":1739538000000}'

The response is a numeric job ID.

Optional overrides (ABS 3.6.0 and later)

You can override storage, destination cluster, and Secret Agent in the request body. If you omit an override, ABS uses the matching field from the local routine.

Override	Fields	Notes
Storage	`source` or `source-name`	Mutually exclusive.
Destination	`destination` or `destination-name`	Mutually exclusive.
Secret Agent	`secret-agent` or `secret-agent-name`	Decrypts backup files. Destination credentials can include an inline `secret-agent` block.
Incremental order	`disable-reordering`	Set `true` to disable reverse-order optimization.

When both storage and destination are present, the routine does not need to exist in the local ABS configuration. ABS still uses routine to locate the backup chain in storage. If you override only one side, the routine must exist locally.

Restore to a different named cluster, reading from the routine’s storage:

{
  "routine": "app-daily",
  "time": 1739538000000,
  "destination-name": "staging"
}

Cross-region restore when this ABS instance does not define app-daily:

{
  "routine": "app-daily",
  "time": 1739538000000,
  "source": {
    "s3-storage": {
      "bucket": "dr-backup-bucket-us-west",
      "path": "prod",
      "s3-region": "us-west-2"
    }
  },
  "destination-name": "local-dr"
}

Restore by path

Copy key from GET /v1/backups/full into backup-data-path. The value is relative to the storage path and must not contain ... source must match that backup’s storage. destination is any reachable Aerospike Database cluster.

curl -s -X POST "$BASE_URL/v1/restore/full" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "seed-nodes": [{ "host-name": "localhost", "port": 3000 }],
      "credentials": { "user": "restore-user", "password": "password" }
    },
    "policy": { "no-generation": true },
    "source": {
      "s3-storage": {
        "bucket": "company-as-backups",
        "path": "prod",
        "s3-region": "us-east-1"
      }
    },
    "backup-data-path": "app-daily/backup/1739538000000/app"
  }'

no-generation: true overwrites existing records regardless of generation.

Restore to the same namespace or a new namespace

By default, ABS restores into the source namespace name. To restore app into app-restore, set policy.namespace:

"policy": {
  "namespace": {
    "source": "app",
    "destination": "app-restore"
  }
}

source must match the namespace in the backup. It is required as a safeguard against accidental remapping.

A remap applies to exactly one namespace. Every namespace in the restore must equal source. Otherwise, ABS rejects the request before the restore starts, with the error namespace remap from "SOURCE" requires the restore to be scoped to exactly that namespace.

Restore by path (POST /v1/restore/full or POST /v1/restore/incremental): set backup-data-path to the backup of a single namespace, which is the key that GET /v1/backups/full returns. To remap several namespaces, run one restore per namespace.
Restore by timestamp (POST /v1/restore/timestamp): remapping works only for routines that back up a single namespace.

To restore several namespaces without remapping, omit policy.namespace. The destination cluster must have namespaces with the same names.

Unique restores

Set policy.unique to true so existing records in the destination are left unchanged. Only records that are missing in the destination are inserted.

unique cannot be combined with replace or no-generation.

With the default incremental reordering, ABS applies newer incremental versions first. If you need the newest version of a missing record at the target timestamp, do not set disable-reordering to true.

{
  "routine": "app-daily",
  "time": 1739538000000,
  "policy": {
    "unique": true
  }
}

Poll job status

curl -s "$BASE_URL/v1/restore/status/JOB_ID"

ABS 3.6.0 and later return lowercase status values:

Status	Meaning
`running`	Restore is in progress.
`success`	Restore finished successfully.
`failure`	Restore failed.
`canceled`	Restore was canceled.

Filter matching on GET /v1/restore/jobs?status= is case-insensitive. Legacy aliases done and failed map to success and failure. Prefix with ! to exclude statuses, for example !failure,canceled.

`fresher-records` versus inserts

When you restore into a namespace that already holds the same records, inserted-records can stay 0 while read-records and fresher-records increase. fresher-records counts records ABS read from the backup but did not write because the destination already had a generation that won.

That result is success, not a no-op failure. To force backup data to overwrite, use no-generation: true (path restore) or restore into an empty namespace.

Cancel a running restore

curl -X POST "$BASE_URL/v1/restore/cancel/JOB_ID"

ABS cancels the restore job identified by JOB_ID. Data that has already been written to the destination cluster remains intact. Prometheus records outcome="canceled" when the restore job is canceled.

Next steps

Run and track restores
Monitor ABS: restore metrics and alerts
Secure ABS: encryption keys and Secret Agent on restore