Backup and restore

Goal

Create and restore backups of a AngaraBase instance — from cold/offline baselines through online FULL + LOG chain with point-in-time recovery (PITR).

Prerequisites

• Initialized AngaraBase instance (angarabase-server --init; see Configuration)
• Built angara-cli binary (see Quickstart)
• For online backups (phase 1b): a running server with WAL (transaction_log backend ≠ noop)

Cold / offline backup

The original supported method. The server must be stopped (or will be stopped by the runner).

1. Copy storage.data_directory and storage.transaction_log_directory.
2. After restore, run the txlog-level oracle.
3. The source must be a correctly initialized data directory.

Pinned commands (legacy shell)

Backup:

tools/backup_restore/run.sh backup \
 --data-dir /var/lib/angarabase/data \
 --txlog-dir /var/lib/angarabase/transaction_log \
 --out /tmp/angarabase-backup.tar.gz \
 --root artifacts/backup_restore/backup

Restore:

tools/backup_restore/run.sh restore \
 --archive /tmp/angarabase-backup.tar.gz \
 --dest /tmp/angarabase-restore \
 --force \
 --root artifacts/backup_restore/restore

Oracle (post-restore verification):

tools/backup_restore/oracle.sh --root artifacts/backup_restore_oracle/run_1

Remote Admin Backup Flow (Online Backup via Admin API)

AngaraBase supports triggering backups remotely via the Admin TCP endpoint. This is the recommended approach for production deployments, as it does not require direct file system access to the database node.

Requirements

• The angarabase-server must be running with the Admin API enabled (configured via admin.listen_address in angarabase.conf or ANGARABASE_ADMIN_ADDR environment variable).
• angara-cli must be executed with the --addr <host:port> parameter instead of --config.
• The user executing the backup must have network access to the Admin API port (default: 9899).

How it works

When using --addr, angara-cli connects to the running server’s Admin API and issues a RUN backup_full command. The server coordinates the backup process internally (Fuzzy Copy, WAL Inclusion) and streams the resulting .angarabk file back to the client over the network.

This allows operators to take backups from a central management node without SSH access to the database servers.

Storage layout note

User tables use the page-based .adb path. Legacy heap_store/*.bin is migrated to .adb on first access.

For backup/restore and triage:

• Both files per database are critical: <db>.adb and <db>.atl.
• heap_store/ is not the source of truth after migration.
• Upgrading old instances may take time proportional to heap_store volume.
• If the backup was taken with TDE enabled (ANGARABASE_TDE_ENABLE=1), restore requires the same valid key material; without it, startup after restore is fail-closed.

Backup/Restore v2 — phase 1a: one-file backupset

Minimal offline pipeline producing a single *.angarabk file (manifest-first format).

Capabilities

Pinned commands (phase 1a)

# FULL (offline/local baseline)
angara-cli backup full \
 --config /path/to/angarabase.conf \
 --out /tmp/full_0001.angarabk \
 --db-id base

# FULL (remote execution via Admin API)
angara-cli backup full \
 --addr 127.0.0.1:9899 \
 --out /tmp/full_0001.angarabk \
 --db-id base

# INSPECT (manifest-only)
angara-cli backup inspect --file /tmp/full_0001.angarabk

# VERIFY v0 (struct/hash)
angara-cli backup verify --file /tmp/full_0001.angarabk --json

# RESTORE (local) into a new directory
angara-cli backup restore \
 --config /path/to/angarabase.conf \
 --file /tmp/full_0001.angarabk \
 --target-dir /tmp/restore_0001 \
 --overwrite

Evidence pack (N=3)

tools/backup_restore/evidence_v2_phase1a.sh --runs 3

Inspect vs verify

• backup inspect: manifest-only, no payload scan.
• backup verify: struct/hash integrity; proves backupset consistency, not SQL-level correctness.

Backup/Restore v2 — phase 1b: online FULL + LOG chain + PITR

Online pipeline with point-in-time recovery support.

Capabilities

Pinned commands (phase 1b)

# ONLINE FULL (best-effort, with backup fence)
# Local execution:
angara-cli backup full-online \
 --config /path/to/angarabase.conf \
 --out /tmp/full_online_0001.angarabk \
 --db-id base

# Remote execution (via Admin API):
angara-cli backup full-online \
 --addr 127.0.0.1:9899 \
 --out /tmp/full_online_0001.angarabk \
 --db-id base

# LOG chunk (LSN boundaries must be contiguous with FULL/prev LOG)
angara-cli backup log \
 --config /path/to/angarabase.conf \
 --out /tmp/log_0001.angarabk \
 --start-lsn <u64> --end-lsn <u64> \
 --db-id base

# Validate chain contiguity
angara-cli backup chain-validate \
 --chain /tmp/full_online_0001.angarabk,/tmp/log_0001.angarabk \
 --json

# PITR restore to target_lsn
angara-cli backup restore-chain \
 --config /path/to/angarabase.conf \
 --target-dir /tmp/restore_chain_0001 \
 --target-lsn <u64> \
 --chain /tmp/full_online_0001.angarabk,/tmp/log_0001.angarabk \
 --overwrite

Evidence pack (N=3)

tools/backup_restore/evidence_v2_phase1b.sh --runs 3

Expected result

After a successful restore the server should start cleanly and previously committed data should be present:

SELECT * FROM sys.health;
SELECT * FROM sys.identity;

For PITR restores, data reflects the state at target_lsn.

Troubleshooting

For unresolved issues see Known issues and Support.

Host migration (without dump/restore)

An alternative to backup/restore for moving AngaraBase to another host is direct data-file copying using the Instance Lease system.

When applicable

• Single-node deployment — one AngaraBase instance
• Shared storage — NFS, SAN, or manual file copy
• Same version — the same AngaraBase version on source and target
• Maintenance window — the instance can be stopped during copying

Step-by-step instructions

1. Stop the source instance:

# Graceful shutdown to release the lease
kill -TERM <angarabase-pid>

# Wait for completion
ps aux | grep angarabase-server

2. Verify lease release (optional):

-- On another instance or via backup connection
SELECT lease_holder_id FROM sys.identity;

3. Copy data files:

# Copy data directory
rsync -av /source/data/ /target/data/

# Copy transaction log directory
rsync -av /source/txlog/ /target/txlog/

# Verify integrity
find /target/data -name "*.adb" -exec ls -la {} \;

4. Start on the target host:

# Update configuration if needed
vim /target/angarabase.conf

# Start AngaraBase
angarabase-server --config /target/angarabase.conf

5. Verify migration:

-- Check lease holder
SELECT lease_holder_hostname, recovery_mode FROM sys.identity;

-- Verify data integrity
SELECT COUNT(*) FROM your_tables;

-- Check system state
SELECT * FROM sys.health;

What to check after startup

• lease_holder_hostname changed to the new host
• recovery_mode shows the recovery type
• All tables are accessible and contain the expected data
• No errors in server logs
• Client connections work correctly

Limitations

• Downtime required — requires stopping the service during copying
• File consistency — files must be copied atomically
• Version compatibility — AngaraBase versions must match
• Configuration — paths in the configuration may need updates

Comparison with backup/restore

See also

Detailed host migration instructions: Crash Recovery — Host Migration

Links

• Canonical operator runbook: angarabook/src/operations/backup-restore.md

• Configuration reference: Configuration

• Diagnostics (post-restore health check): Diagnostics

• Host migration details: Crash Recovery