Concord.Backup (Concord v2.0.0)

Backup and restore functionality for Concord distributed KV store.

Provides comprehensive backup management including:

Local and remote backup creation
Point-in-time recovery
Backup verification and integrity checks
Compressed backup storage
Metadata tracking

Backup Format

Backups are stored as compressed Erlang term files (.backup) containing:

Metadata (timestamp, cluster info, entry count)
Full snapshot of all key-value pairs
Checksum for integrity verification

Examples

# Create a backup
{:ok, path} = Concord.Backup.create("/path/to/backups")

# Restore from backup
:ok = Concord.Backup.restore("/path/to/backup.backup")

# List available backups
{:ok, backups} = Concord.Backup.list("/path/to/backups")

# Verify backup integrity
{:ok, :valid} = Concord.Backup.verify("/path/to/backup.backup")

Summary

Types

backup()

Backup content

metadata()

Backup metadata

Functions

cleanup(opts \\ [])

Deletes old backups based on retention policy.

create(opts \\ [])

Creates a backup of the current cluster state.

list(backup_dir \\ "./backups")

Lists all available backups in a directory.

restore(backup_path, opts \\ [])

Restores cluster state from a backup file.

verify(backup_path)

Verifies the integrity of a backup file.

Types

backup()

@type backup() :: %{metadata: metadata(), data: [{term(), term()}]}

Backup content

metadata()

@type metadata() :: %{
  timestamp: DateTime.t(),
  node: node(),
  cluster_name: atom(),
  entry_count: non_neg_integer(),
  memory_bytes: non_neg_integer(),
  version: String.t(),
  checksum: binary()
}

Backup metadata

Functions

cleanup(opts \\ [])

@spec cleanup(keyword()) :: {:ok, non_neg_integer()} | {:error, term()}

Deletes old backups based on retention policy.

Options

:keep_count - Number of backups to keep (default: 10)
:keep_days - Keep backups newer than N days (default: 30)

Returns

{:ok, deleted_count} - Number of backups deleted
{:error, reason} - Error during cleanup

Examples

iex> Concord.Backup.cleanup(keep_count: 5)
{:ok, 3}

iex> Concord.Backup.cleanup(keep_days: 7)
{:ok, 10}

create(opts \\ [])

@spec create(keyword()) :: {:ok, Path.t()} | {:error, term()}

Creates a backup of the current cluster state.

Options

:path - Directory to store backup (default: "./backups")
:compress - Compress backup file (default: true)
:include_metadata - Include cluster metadata (default: true)

Returns

{:ok, backup_path} - Path to created backup file
{:error, reason} - Error creating backup

Examples

iex> Concord.Backup.create()
{:ok, "./backups/concord_backup_20251023_143052.backup"}

iex> Concord.Backup.create(path: "/mnt/backups")
{:ok, "/mnt/backups/concord_backup_20251023_143052.backup"}

list(backup_dir \\ "./backups")

@spec list(Path.t()) :: {:ok, [map()]} | {:error, term()}

Lists all available backups in a directory.

Returns

{:ok, backup_list} - List of backup file information
{:error, reason} - Error reading directory

Examples

iex> Concord.Backup.list()
{:ok, [
  %{
    path: "./backups/concord_backup_20251023_143052.backup",
    timestamp: ~U[2025-10-23 14:30:52Z],
    size_bytes: 1048576,
    entry_count: 1000
  }
]}

restore(backup_path, opts \\ [])

@spec restore(
  Path.t(),
  keyword()
) :: :ok | {:error, term()}

Restores cluster state from a backup file.

Warning: This operation will overwrite all existing data in the cluster. It's recommended to create a backup before restoring.

Options

:force - Skip confirmation prompts (default: false)
:verify - Verify backup integrity before restore (default: true)

Returns

:ok - Restore completed successfully
{:error, reason} - Error during restore

Examples

iex> Concord.Backup.restore("/path/to/backup.backup")
:ok

iex> Concord.Backup.restore("/path/to/backup.backup", force: true)
:ok

verify(backup_path)

@spec verify(Path.t()) :: {:ok, :valid | :invalid} | {:error, term()}

Verifies the integrity of a backup file.

Returns

{:ok, :valid} - Backup is valid
{:ok, :invalid} - Backup is corrupted
{:error, reason} - Error reading backup

Examples

iex> Concord.Backup.verify("/path/to/backup.backup")
{:ok, :valid}