vault.backup

Documentation for eth_defi.vault.backup Python module.

Verified file backups and progress reporting for scanner database maintenance.

These primitives are shared by local migrations and private R2 snapshots. The caller owns the database connection and must stop other database owners before checkpointing or copying persistent state.

Functions

`backup_database`(connection, path, backup_dir)	Create and verify an independent backup before any repair transaction.
`copy_database_file`(source, destination)	Copy a checkpointed database with progress and durable file contents.
`file_sha256`(path)	Hash an evidence file without loading it into memory.
`observe_database_operation`(label)	Log a heartbeat while an uninterruptible DuckDB operation runs.
`write_json_atomic`(path, value)	Persist a report or backup receipt atomically and durably.

file_sha256(path)

Hash an evidence file without loading it into memory.

Progress is visible for production-sized files.

Parameters: path (pathlib.Path) – Existing immutable file.
Returns: SHA-256 hexadecimal digest.
Return type: str

write_json_atomic(path, value)

Persist a report or backup receipt atomically and durably.

A failed write cannot replace a completed receipt with partial JSON.

Parameters

path (pathlib.Path) – Destination path.
value (dict) – JSON-serialisable report.

Returns

None.

Return type

None

observe_database_operation(label)

Log a heartbeat while an uninterruptible DuckDB operation runs.

The heartbeat never uses the database connection and stops on context exit.

Parameters: label (str) – Operation context shown in logs.
Returns: Context yielding None.
Return type: collections.abc.Iterator[None]

copy_database_file(source, destination)

Copy a checkpointed database with progress and durable file contents.

The caller keeps the source’s exclusive connection while this runs.

Parameters

source (pathlib.Path) – Checkpointed, stable source database.
destination (pathlib.Path) – New snapshot filename.

Returns

None after fsync.

Return type

None

backup_database(connection, path, backup_dir)

Create and verify an independent backup before any repair transaction.

The exclusive read/write connection excludes external DuckDB writers. Checkpoint first to include committed WAL contents, retain that connection while copying, and abort before migration if verification or fsync fails.

Parameters

connection (_duckdb.DuckDBPyConnection) – Exclusively held database connection.
path (pathlib.Path) – Target database, with its owner stopped.
backup_dir (pathlib.Path) – Backup directory outside the target path.

Returns

Durable backup receipt containing its path and SHA-256.

Return type

dict