# Online backup in development builds

Start the file-backed server with `ratdb serve INSTANCE --backup-dir DIR`. Use an existing private directory dedicated to this instance on a filesystem that supports hard links. An authenticated shell session can run `online-backup`. The response includes the generation, the server-generated filename and the measured writer pause in microseconds. The command is disabled by default. Each generation can be published once per directory.

The server owns the source exclusively throughout. It holds its database mutex while copying the committed bank in 16 KiB chunks, flushing the destination, opening it and validating its physical state. Reads and writes queue during this phase. Logical document and catalog checks then run on the private image while the server resumes work. A non-overwriting hard link publishes the checked image. Unix additionally syncs the containing directory. Filesystem latency and database size determine the pause. A process kill can leave an unpublished .ratdb-online-*.tmp file. Remove orphan staging files after shutting down the server. A lost response can leave a valid final file; inspect it before retrying.

Restore to a fresh path with `ratdb restore DIR/generation-N.ratdb NEW`. Run `ratdb check NEW`, set credentials with `ratdb setup NEW admin`, and start the restored instance. The image contains one committed generation, including empty namespace metadata. Credentials and old inactive-bank bytes are excluded.

The real-client regression starts 64 acknowledged writes, captures a generation while the worker is active, changes the live data again, restores into a new server, and verifies the generation, exact matching document and empty den. It exercises default-disabled and no-clobber behavior. A Windows debug run captured generation 5 with a 2,597 microsecond pause on this small fixture. This is a functional sample only. The distributed alpha predates this command.