Offline copy & restore

Current support

There is no online backup API, checkpoint export, incremental backup stream, or audited backup/restore tooling. This guide describes an offline filesystem-copy procedure to evaluate with restore drills; it is not a certified backup guarantee.

Do not copy a live database directory and assume its files form one checkpoint. The table, manifest, CURRENT, and WAL can change while a copy is in progress.

Prepare a closed copy

1. Stop admitting application writes and background producers.
2. Wait for every user of the shared DB handle to finish.
3. Call Close and verify its result.
4. Ensure no CLI or second application reopens the directory during the copy.
5. Copy the entire directory to a new destination, preserving filenames and contents.

Flush alone does not stop future writers and is not sufficient for this procedure. Close syncs either durability mode, although it cannot repair an earlier device/I/O failure.

Example filesystem copy

With every DB owner stopped, use explicit source/destination paths. PowerShell example:

$source = 'C:\AppData\ZeeDB\data'
$backup = 'D:\Backups\ZeeDB\data-2026-10-16'
if (Test-Path -LiteralPath $backup) { throw 'Choose a new backup destination' }
Copy-Item -LiteralPath $source -Destination $backup -Recurse

These are placeholder application paths: substitute your real dedicated directories. Verify the copy command’s success and storage capacity. Do not merge into a preexisting directory, omit files based on guessed importance, or delete the original after a single copy succeeds.

Copying the LOCK file does not copy a live OS lock. Nevertheless, never manipulate the original LOCK while its owner is open.

Validate a restore candidate

Keep the backup untouched. Copy it into a new working restore directory, then open that working directory with the same engine version and original options.

Open-time recovery may truncate an incomplete WAL tail or reclaim obsolete files. That is why validation should use a disposable working copy rather than modifying the only archive.

restored, err := zeedb.Open(restorePath, originalOptions)
if err != nil {
    return err
}

Close the restored handle with error handling after validation. Opening verifies persisted structures; it does not validate all application relationships, JSON schemas, or external side effects.

Restore drill checklist

• Confirm the expected collection/key samples and logical counts.
• Decode representative application values and verify schema versions.
• Check primary/index relationships if your application maintains indexes.
• Exercise a write/read/close/reopen on the working restore copy.
• Record the engine version, options, filesystem, copy procedure, and validation results.
• Retain prior recovery points according to your application’s policy.

Several scan pages are not one snapshot if writers run during logical validation. Keep the restore candidate isolated until its checks finish.

Failure handling

If the original handle failed to sync or the copy was interrupted, treat the candidate as unverified. Preserve originals and investigate rather than deleting the WAL or manifest to force Open to succeed.

For an engine format upgrade, no automatic migration exists. Keep the original engine/version available and test compatibility on copies before changing deployed data.