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 (без dump/restore)

Альтернатива backup/restore для переноса AngaraBase на другой хост — прямое копирование файлов данных с использованием Instance Lease системы.

Когда применимо

• Single-node deployment — один инстанс AngaraBase
• Shared storage — NFS, SAN или ручное копирование файлов
• Same version — одинаковая версия AngaraBase на источнике и цели
• Maintenance window — можно остановить инстанс на время копирования

Пошаговая инструкция

1. Остановить source инстанс:

# Graceful shutdown для освобождения lease
kill -TERM <angarabase-pid>

# Дождаться завершения
ps aux | grep angarabase-server

2. Проверить освобождение lease (опционально):

-- На другом инстансе или через backup connection
SELECT lease_holder_id FROM sys.identity;

3. Скопировать файлы данных:

# Копировать data directory
rsync -av /source/data/ /target/data/

# Копировать transaction log directory
rsync -av /source/txlog/ /target/txlog/

# Проверить целостность
find /target/data -name "*.adb" -exec ls -la {} \;

4. Запустить на target хосте:

# Обновить конфигурацию если нужно
vim /target/angarabase.conf

# Запустить AngaraBase
angarabase-server --config /target/angarabase.conf

5. Проверить миграцию:

-- Проверить lease holder
SELECT lease_holder_hostname, recovery_mode FROM sys.identity;

-- Проверить целостность данных
SELECT COUNT(*) FROM your_tables;

-- Проверить состояние системы
SELECT * FROM sys.health;

Что проверить после старта

• lease_holder_hostname изменился на новый хост
• recovery_mode показывает тип восстановления
• Все таблицы доступны и содержат ожидаемые данные
• Нет ошибок в логах сервера
• Клиентские подключения работают корректно

Ограничения

• Downtime required — требует остановки сервиса на время копирования
• File consistency — файлы должны быть скопированы атомарно
• Version compatibility — версии AngaraBase должны совпадать
• Configuration — пути в конфигурации могут потребовать обновления

Сравнение с backup/restore

См. также

Подробные инструкции по host migration: 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