Migrate an Aerospike export to SMKV

Applies to: the initial development version of smkv-migrate, reviewed October 16, 2026. This standalone Rust tool is not included in the public APT packages. Request matching migration and backup binaries from early-access support.

Convert an existing Aerospike export into an SMKV backup, store it locally or in your S3 bucket, then restore into a fresh cluster. Conversion runs offline and never connects to an Aerospike server. This is an evaluation workflow, not a continuous migration service or a zero-downtime cutover.

Check compatibility first

Obtain a full export using the Aerospike tools appropriate to your deployment, excluding indexes and UDFs (--no-indexes --no-udfs for legacy asbackup). Decode compressed or encrypted exports before conversion. The converter requires the Version 3.1 file header and does not assume compatibility with other versions.

Check that exported records contain stored user keys before planning a cutover. A workload whose records contain only digests needs a separate key-recovery strategy. SMKV is not an Aerospike wire-protocol replacement; applications must use an SMKV SDK.

Prepare the migration

1. Start with a representative export and a disposable SMKV cluster.
2. Obtain compatible smkv-migrate and smkv-backup binaries. Keep their build identities with the migration record.
3. Create the target cluster map, choosing partition count and capacity before conversion. The map is configuration input; conversion does not contact its addresses.
4. Reserve local staging space for two copies of the archive plus a disk-backed duplicate-key index. Restore needs additional space for node data and checkpoints.
5. For S3 output, install AWS CLI v2 and configure access scoped to a new bucket prefix. Keep credentials outside mapping files and command examples. Local output requires no cloud account.

Map namespaces and sets

Save this as migration-mapping.json, or download the example mapping:

{
  "tables": [
    {
      "namespace": "source",
      "set": "users",
      "database": "customer",
      "table": "users",
      "key_type": "S"
    }
  ]
}

Add one entry for every namespace/set pair in the export. Each entry must map to a unique target database/table; combining source sets into one table is not supported. Use "set": "" for records without a set, with an explicitly named target table. Unmapped records fail conversion.

Bin names become column names unchanged. Database names allow 1–64 ASCII letters, digits, underscores or hyphens. Table and column names allow 1–64 UTF-8 bytes. Rows support up to 64 columns and 64 MiB of encoded values; encoded keys must fit within 64 KiB. Configure your target cluster to accept the actual record sizes.

Each mapped table accepts one source key type:

Mixed key types and empty keys are rejected. In particular, integer keys do not become decimal strings. Adapt and test the application key encoding before migration. Generation numbers and source digests do not become SMKV concurrency metadata.

Convert the export

For a local archive, the destination directory must not exist:

smkv-migrate \
  --input /exports/part-001.asb \
  --input /exports/part-002.asb \
  --mapping migration-mapping.json \
  --map new-cluster.json \
  --work-dir /backup-stage \
  --backup-binary /usr/local/bin/smkv-backup \
  --destination /backups/migration-001

Pass each input file explicitly. The converter cannot detect a file omitted from the export. Do not modify input files while conversion runs.

To publish to S3, replace the destination:

smkv-migrate \
  --input /exports/part-001.asb \
  --input /exports/part-002.asb \
  --mapping migration-mapping.json \
  --map new-cluster.json \
  --work-dir /backup-stage \
  --backup-binary /usr/local/bin/smkv-backup \
  --destination s3://YOUR_BUCKET/migrations/export-001

Use a new, dedicated prefix. Conversion streams records into partition snapshots, detects duplicate identities using a disk-backed index, and runs the existing archive verifier before publishing. S3 claims the prefix conditionally and uploads MANIFEST.json last. MIGRATION.json reports records read, records written, records already expired, input-file count and key encoding.

Verify and restore

smkv-backup --work-dir /backup-stage verify \
  --source s3://YOUR_BUCKET/migrations/export-001

smkv-backup --work-dir /backup-stage import \
  --source s3://YOUR_BUCKET/migrations/export-001 \
  --map new-cluster.json --node-id n1 \
  --data-dir /var/lib/smkv-restored \
  --max-entries 100000000 --max-log-bytes 1099511627776

The limits above are examples, not capacity recommendations. Repeat import for every target node, changing its ID and local destination. Keep the archive's partition count. Destination directories must not exist; use fresh cluster and authority identities. Follow the full backup and restore procedure.

verify checks the manifest, map, sizes and checksums. Import additionally validates records and routing, reopens the restored store, and verifies values and expiration through its index. A checksum check alone does not prove a successful restore.

Validate the application and cut over

For the final migration, quiesce source writes before taking the full export and keep them paused through validation and cutover. There is no change-capture catch-up step. Any writes accepted by the old cluster after that export are absent from the converted archive.

Compare source export counts with MIGRATION.json, accounting for expired records. Check every mapped table and key type, sample values and types through the application SDK, and verify expiration. Records expiring during conversion or restore may be absent by the time you query them; TTL does not restart.

Check cluster readiness and replica agreement before switching application endpoints. Preserve the source and export until acceptance. If applications start writing to SMKV, switching back to the source requires a reconciliation plan; the converter does not reverse-sync those writes.

Failures and current limits

Parsing, unsupported data, duplicate identities or verification failures stop conversion before destination publication. Fix the input or mapping; do not bypass a rejected type by relabeling it.

An interrupted upload may leave a claimed prefix and partial objects. Require a complete manifest and successful verification before restore. Retry with a new destination; identify and remove abandoned output explicitly. Conversion and publication are not resumable.

The current implementation passed synthetic format tests and offline restores through the real SMKV importer. S3 publication ordering and failure handling were tested with a fake AWS CLI. Native asbackup-generated fixtures, a real-bucket migration and large-dataset qualification remain release gates. Use this tool for evaluation until your migration has been qualified.