# Back up and restore

**Applies to:** development builds with `smkv-backup`. This tool is not in public APT baseline 0.1.0-2. Full backups and restores are manual commands.

## Prepare a destination

Use a new local directory or a unique S3 prefix for each export. S3 requires AWS CLI v2, a configured credential profile, and access scoped to your chosen bucket/prefix. Keep credentials out of commands, archive manifests, and source files. A local export needs no cloud account.

Provide work space for the entire archive, restored data, and checkpoint overhead. Confirm source readiness and stable topology before starting. For an application-consistent cut, stop application writes and wait for replicas to catch up first: ordinary export captures each partition separately, not one global transaction boundary.

## Export and verify

With compatible tools on a host that can reach management and replication endpoints:

```sh
smkv-backup --work-dir /backup-stage export \
  --seed 10.0.0.11:7381 --destination s3://YOUR_BUCKET/smkv/export-001
smkv-backup --work-dir /backup-stage verify \
  --source s3://YOUR_BUCKET/smkv/export-001
```

Replace the S3 URI with a new local path for a local archive. `verify` checks manifest structure, object sizes, and SHA-256 checksums. Save the compatible server/tool build identity alongside your backup record.

Exports publish the manifest last. An interrupted export is incomplete; retry using a new destination. Export is not resumable. Clean abandoned prefixes only after identifying them explicitly. Never treat the presence of some objects as a completed backup.

## Restore into a fresh cluster

Create a target map with the desired node membership and the same partition count as the source. Pick budgets large enough for the data. Stop destination services; each destination directory must not exist.

Run import separately for each target node, changing `--node-id` and its local destination:

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

The numeric limits are examples, not automatic sizing recommendations. Match the map and eventual server configuration. Import validates routing and record contents, reopens the restored store, and verifies values and TTLs through its index before publishing the destination. It does not overwrite a running cluster.

## Verify before cutover

1. Finish imports on every target node and ensure the service identity can read/write the complete restored directory.
2. Start servers with the new map and matching partition count and budgets.
3. For quorum mode, bootstrap a fresh authority group with fresh quorum identities; never copy old voter state into the new cluster.
4. Check all owners, readiness, replica agreement, application sample reads, and expired/deleted records.
5. Switch application discovery seeds only after validation. Retain the old cluster until cutover is accepted.

Expiration uses the original absolute timestamp: elapsed TTL does not restart on restore. Keep compatible binaries with recovery archives. A restore drill is stronger evidence than a checksum-only verification.

## Keep backup separate from sync

Cross-cluster sync checkpoints help new group members catch up from an origin cut. They do not replace independent full backups, retention policies, or a tested disaster-recovery procedure. See [cross-cluster sync](group-sync.html) for its experimental status.