Back Up and Restore KalamDB

Create a database backup, monitor its job, and rehearse restoring it on an isolated server. Backup and restore require a DBA or system account. Paths refer to the server filesystem, not the computer running the CLI.

Create a KalamDB backup

Authenticate the CLI to the intended instance first. Provision a backup directory writable by the server process, outside its active data directory. Then run:

BASH

1kalam --url http://127.0.0.1:2900 \2  -c "BACKUP DATABASE TO '/backups/kalamdb-before-upgrade.tar.gz';"

The equivalent SQL is:

SQL

1BACKUP DATABASE TO '/backups/kalamdb-before-upgrade.tar.gz';

The response contains a job ID. Copy that actual value into the status query:

SQL

1SELECT job_id, job_type, status, message, exception_trace2FROM system.jobs3WHERE job_id = 'YOUR_BACKUP_JOB_ID';

Wait for completed. If the job fails, inspect message and exception_trace; do not treat an existing output path as proof of a successful backup.

The transfer layer supports a backup directory or a .tar.gz / .tgz archive. An archive is convenient for copying off the server. Its root contains rocksdb/, storage/, snapshots/, streams/, and optionally server.toml. The RocksDB component uses its native backup mechanism; the other components are copied from the configured local paths.

Verify and store the archive

On the server host, after the job completes:

BASH

1tar -tzf /backups/kalamdb-before-upgrade.tar.gz | head2shasum -a 256 /backups/kalamdb-before-upgrade.tar.gz

Keep the checksum, server version, configuration, timestamp, and recovery procedure with the archive. Copy it to separate storage. Protect it like the live database: the optional configuration can include secrets.

The backup job coordinates with storage-writing jobs. Do not assume this constitutes a cluster-wide point-in-time backup or includes objects held in external buckets. Account for object-storage data, node topology, and external secrets in the recovery plan. Quiesce application writes when establishing the recovery point and test the procedure for your deployment.

Restore on an isolated instance

Before restoring production, rehearse with a separate instance using a compatible server binary, separate data paths, and separate ports. Copy the archive to that server. Keep application traffic stopped during restore.

BASH

1kalam --url http://127.0.0.1:3900 \2  -c "RESTORE DATABASE FROM '/backups/kalamdb-before-upgrade.tar.gz';"

Or execute the SQL on that recovery instance:

SQL

1RESTORE DATABASE FROM '/backups/kalamdb-before-upgrade.tar.gz';

Poll the returned restore job ID:

SQL

1SELECT job_id, status, message, exception_trace2FROM system.jobs3WHERE job_id = 'YOUR_RESTORE_JOB_ID';

Wait for completed, then stop and restart the recovery server. RocksDB data is staged for activation at startup. Storage files and optional server.toml can be copied during the restore job, so this is not an operation to perform while application traffic continues.

Review the restored configuration before restart: make sure the recovery instance still uses its own ports and data directories. Activating a restore replaces current database state; preserve a fresh rollback backup first when restoring an existing instance.

Verify the recovered application

Use the original application identity when checking USER tables:

BASH

1kalam --url http://127.0.0.1:3900 -c 'SELECT COUNT(*) FROM app.todos;'2kalam --url http://127.0.0.1:3900 -c 'SELECT * FROM app.todos LIMIT 10;'

Replace app.todos with a table in your backup. Compare counts and known rows with the recorded recovery point, download a sample FILE value, and open a live subscription before allowing traffic. A successful extraction or server startup alone does not validate the application data.

Schedule and automate

Run the same BACKUP DATABASE statement from your scheduler or deployment tooling. Give each archive a distinct path, poll its job to completion, copy it off-host, and periodically rehearse the restore. There is no separate kalam backup subcommand in this workflow: the CLI executes the SQL command with -c.

Next step

Monitor jobs and troubleshoot failures →

Reference: Storage tiers and cluster operations.