Backup & Restore

AeorDB supports exporting database versions as self-contained .aeordb files, creating incremental patches between versions, importing backups, and promoting version hashes.

Concepts

Full export: A clean .aeordb file containing only the live entries at a specific version. No voids, no deletion records, no stale overwrites, no history.
Patch (diff): A .aeordb file containing only the changeset between two versions – new/changed chunks, updated file records, updated directory indexes, and deletion records for removed files.
Import: Applying an export or patch into a target database.
Promote: Setting a version hash as the current HEAD.

Privileged Backup (`--root-key`)

By default, aeordb export includes only user data — the export omits everything under /.aeordb-system/ (users, groups, snapshot records) and stops at the specified version (HEAD or one named snapshot).

When you supply the source database’s root API key, the CLI unlocks privileged backup mode:

System data is included: /.aeordb-system/users/, /.aeordb-system/groups/, /.aeordb-system/snapshots/, /.aeordb-system/config/.
All named snapshots are walked, not just HEAD. The exported .aeordb carries the full snapshot history.
Credentials are NEVER exported, regardless of the key: /.aeordb-system/api-keys/, /.aeordb-system/refresh-tokens/, and /.aeordb-system/magic-links/ are always filtered out. Credentials are tied to the database identity that issued them; importing them would conflict with the target’s own bootstrap key.

Supply the key via flag or environment variable:

# Flag
aeordb export -D source.aeordb -o backup.aeordb \
  --root-key aeor_k_…

# Environment variable
AEORDB_ROOT_KEY=aeor_k_… aeordb export -D source.aeordb -o backup.aeordb

When importing a backup that contains system data, the target database’s root key must be provided the same way. This proves ownership of the destination before user/group/snapshot records are merged.

Full Export

Export HEAD, a named snapshot, or a specific version hash as a self-contained backup.

CLI

# Export HEAD
aeordb export --database data.aeordb --output backup.aeordb

# Export a named snapshot
aeordb export --database data.aeordb --output backup.aeordb --snapshot v1

# Export a specific version hash
aeordb export --database data.aeordb --output backup.aeordb --hash abc123def456...

The output file must not already exist – the command will refuse to overwrite.

HTTP API

curl -X POST http://localhost:6830/versions/export \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"output": "backup.aeordb"}'

With a snapshot:

curl -X POST http://localhost:6830/versions/export \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"output": "backup.aeordb", "snapshot": "v1"}'

Note: HTTP exports never include system data or other snapshots — that’s CLI-only with --root-key. The HTTP endpoint is for sharing a single version’s user data.

Output

Export complete.
  Files: 142
  Chunks: 89
  Directories: 23
  Version: abc123def456...

Diff / Patch

Create an incremental patch containing only the changes between two versions. This is significantly smaller than a full export when only a few files have changed.

CLI

# Diff between two snapshots
aeordb diff --database data.aeordb --output patch.aeordb --from v1 --to v2

# Diff from a snapshot to HEAD
aeordb diff --database data.aeordb --output patch.aeordb --from v1

# Diff using raw hashes
aeordb diff --database data.aeordb --output patch.aeordb --from abc123... --to def456...

The --from and --to arguments accept either snapshot names or hex-encoded version hashes. If --to is omitted, HEAD is used.

HTTP API

curl -X POST http://localhost:6830/versions/diff \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"output": "patch.aeordb", "from": "v1", "to": "v2"}'

Output

Patch created.
  Files added: 5
  Files modified: 12
  Files deleted: 3
  Chunks: 8
  Directories: 7
  From: abc123...
  To:   def456...

What a Patch Contains

New chunks: Content chunks that exist in the target version but not the base version
Added file records: Files present in the target but not the base
Modified file records: Files that changed between the two versions
Deletion records: Files present in the base but removed in the target
Changed directory indexes: Directory entries that differ between versions

Import

Apply a full export or incremental patch to a target database.

CLI

# Import a full export
aeordb import --database data.aeordb --file backup.aeordb

# Import and immediately promote HEAD
aeordb import --database data.aeordb --file backup.aeordb --promote

# Force import a patch even if base version doesn't match
aeordb import --database data.aeordb --file patch.aeordb --force

# Import a privileged backup that contains system data (users, groups,
# snapshots). Required when the backup was made with --root-key.
aeordb import --database data.aeordb --file backup.aeordb \
  --root-key aeor_k_…

Flags:

--promote: Automatically set HEAD to the imported version
--force: Skip base version verification for patches
--root-key <key> (or AEORDB_ROOT_KEY env var): Required when the backup contains system data. The key must be the target database’s root key — proving you own where the data is going.

When the backup contains system data and no root key is provided, the import succeeds but skips the system entries (a warning is printed).

HTTP API

curl -X POST http://localhost:6830/versions/import \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file": "backup.aeordb", "promote": true}'

Patch Base Version Check

When importing a patch, AeorDB verifies that the target database’s current HEAD matches the patch’s base version. If they don’t match, the import fails:

Target database HEAD (aaa111...) does not match patch base version (bbb222...).
Use --force to apply anyway.

Use --force to skip this check if you know what you’re doing.

Output

Full export imported.
  Entries: 254
  Chunks: 89
  Files: 142
  Directories: 23
  Deletions: 0
  Version: abc123...

  HEAD has been promoted.

If --promote was not used:

  HEAD has NOT been changed.
  To promote: aeordb promote --hash abc123...

Promote

Set a specific version hash as the current HEAD.

CLI

aeordb promote --database data.aeordb --hash abc123def456...

The command verifies that the hash exists in the database before promoting.

HTTP API

curl -X POST http://localhost:6830/versions/promote \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hash": "abc123def456..."}'

Typical Workflows

Regular Backups

# Create a snapshot first
curl -X POST http://localhost:6830/versions/snapshots \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"name": "daily-2024-01-15"}'

# Export it
aeordb export --database data.aeordb \
  --output backups/daily-2024-01-15.aeordb \
  --snapshot daily-2024-01-15

Incremental Backups

# First backup: full export
aeordb export --database data.aeordb --output backups/full.aeordb --snapshot v1

# Subsequent backups: just the diff
aeordb diff --database data.aeordb --output backups/patch-v1-v2.aeordb --from v1 --to v2

Restore from Backup

# Import the full backup
aeordb import --database restored.aeordb --file backups/full.aeordb --promote

# Apply incremental patches in order
aeordb import --database restored.aeordb --file backups/patch-v1-v2.aeordb --promote

Migrate Between Servers

# On source server
aeordb export --database data.aeordb --output transfer.aeordb

# Copy to target server
scp transfer.aeordb target-server:/data/

# On target server
aeordb import --database data.aeordb --file transfer.aeordb --promote

Automated Backup Scheduling

Use the "backup" task type with the cron scheduler to run automated backups on a schedule. The backup task exports HEAD (or a named snapshot) as a timestamped .aeordb file and optionally enforces a retention policy.

Cron Configuration

{
  "schedules": [
    {
      "id": "nightly-backup",
      "task_type": "backup",
      "schedule": "0 1 * * *",
      "args": {
        "backup_dir": "/var/backups/aeordb/",
        "retention_count": 7
      },
      "enabled": true
    }
  ]
}

Backup Task Arguments

Argument	Type	Default	Description
`backup_dir`	string	`"./backups/"`	Destination directory for backup files
`retention_count`	integer	`0`	Keep at most this many `.aeordb` files in the backup directory. `0` means unlimited.
`snapshot`	string	–	Export a named snapshot instead of HEAD

The task creates a timestamped filename (e.g., backup-head-20260419T030000.000Z.aeordb) to avoid collisions. When retention_count is set, the oldest .aeordb files in backup_dir are deleted after each backup to stay within the limit.

Example: Weekly Backups with 4-Week Retention

curl -X POST http://localhost:6830/system/cron \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "weekly-backup",
    "schedule": "0 2 * * 0",
    "task_type": "backup",
    "args": {
      "backup_dir": "/var/backups/aeordb/",
      "retention_count": 4
    },
    "enabled": true
  }'

AeorDB Documentation

Backup & Restore

Concepts

Privileged Backup (`--root-key`)

Full Export

CLI

HTTP API

Output

Diff / Patch

CLI

HTTP API

Output

What a Patch Contains

Import

CLI

HTTP API

Patch Base Version Check

Output

Promote

CLI

HTTP API

Typical Workflows

Regular Backups

Incremental Backups

Restore from Backup

Migrate Between Servers

Automated Backup Scheduling

Cron Configuration

Backup Task Arguments

Example: Weekly Backups with 4-Week Retention

See Also

Keyboard shortcuts

AeorDB Documentation