hydromodpy.core.migrations.auto_boot

Robust boot-time migration with backup, FileLock and rolling history.

ensure_schema_safe wraps hydromodpy.core.migrations.ensure_schema() with three guarantees that the bare runner does not provide:

• a FileLock on <db>.lock so two processes never migrate the same DuckDB file simultaneously (the bare ensure_schema is unlocked).

• an atomic file-level backup <db>.bak-<ISO8601Z> taken right before any migration runs, with automatic restore-on-failure if the schema upgrade raises.

• a rolling history of at most MAX_BACKUPS snapshots per database (oldest removed on overflow).

The opt-out HMP_AUTO_MIGRATE=0 raises AutoMigrationDisabled when a pending migration is detected, leaving the on-disk file untouched.

Functions

backup_path_for(db_path, *[, timestamp])	Return the canonical backup path for db_path at timestamp.
ensure_schema_safe(connection, *, db_path, ...)	Bring component up to the latest version with backup + lock.
list_backups(db_path)	Return existing backups for db_path ordered oldest -> newest.
restore_backup(db_path, backup)	Restore db_path from backup overwriting the current file.

Exceptions

AutoMigrationDisabled

Raised when HMP_AUTO_MIGRATE=0 blocks a needed schema upgrade.