Backup

A backup is a single .ndbz file: the database folder, compressed (tar + gzip) and encrypted with a backup passphrase. File names are encrypted too; someone who finds the backup cannot see which schemas it holds.

>> backup_database -f ./backups/shop-2026-10-30.ndbz
>> restore_database -f ./backups/shop-2026-10-30.ndbz -t ./restored/shop.ndbc

From the menu: Database → Backup... and Database → Restore.... In Go:

err := db.BackupFile("shop.ndbz", backupPassphrase)
err = nardb.Restore("shop.ndbz", "restored/shop.ndbc", backupPassphrase)

How it works#

• While the backup is taken, writes wait briefly: the write-ahead log is moved into the files and the files are copied as one consistent moment. Reads, and writes after the backup, carry on as usual.
• The backup passphrase needs at least 12 characters. The encryption key is derived from it with Argon2id; the algorithm is XChaCha20-Poly1305.
• The stream is encrypted in 1 MiB chunks. Every chunk is bound to the backup's header, its position and a "last chunk" flag. A backup that was changed, cut short, reordered or truncated does not restore.
• A wrong passphrase is caught before any chunk is opened and reported as "wrong passphrase". A damaged backup is reported as corrupt; the two are never confused.

Moving to another machine#

When the database is encrypted with its key in the system keychain, the backup re-wraps the data key with the backup passphrase. The backup therefore opens on another machine without that keychain, using only the backup passphrase. The restored database is passphrase-encrypted; to move its key into that machine's keychain:

>> encrypt_database -e keychain

The backup of an unencrypted database is encrypted as well, but the restored database is unencrypted, like its source.

Limits#

• A restore always goes to a new path; it never overwrites an existing database.
• Encrypted pages do not compress. The backup of an encrypted database is roughly as large as the database.
• If the backup passphrase is forgotten, the backup cannot be opened.
• Incremental backups do not exist yet; every backup is full.