74 lines
4.0 KiB
Markdown
74 lines
4.0 KiB
Markdown
# Contract: Backup Management
|
|
|
|
Version: 1.1
|
|
|
|
## Purpose
|
|
|
|
Общие правила для создания, хранения, именования, ротации и восстановления бэкапов вне зависимости от того, что именно сохраняется: SQLite, централизованная БД, конфиг, файлы пользователя или смешанный bundle.
|
|
|
|
## Backup Capability Must Be Shipped
|
|
|
|
Backup/restore must be built into the application runtime or into binaries/scripts shipped as part of the application itself. Do not assume the operator already has suitable software installed on their machine.
|
|
|
|
Rules:
|
|
- AI must not rely on random machine-local applications (DB GUI clients, IDE plugins, desktop backup tools, ad-hoc admin utilities) being present on the user's machine.
|
|
- Backup helpers must not depend on locally installed database clients such as `mysql`, `mysqldump`, `psql`, `pg_dump`, `sqlite3`, or similar tools being present on the user's machine.
|
|
- If the application persists non-ephemeral state and does not already have backup functionality, implement it.
|
|
- Preferred delivery is one of: built-in UI action, CLI subcommand, background scheduler, or another application-owned mechanism implemented in the project.
|
|
- The backup path must work through application mechanics: application code, bundled libraries, and application-owned configuration.
|
|
- Rollout instructions must reference only shipped or implemented backup/restore paths.
|
|
|
|
## Backup Storage
|
|
|
|
Backups are operational artifacts, not source artifacts.
|
|
|
|
Rules:
|
|
- Never write backups into the git repository tree.
|
|
- Backup files must never be staged or committed to git.
|
|
- Every application must have an explicit backup root outside the repository.
|
|
- Default local-app location: store backups next to the user config, for example `~/.config/<appname>/backups/`.
|
|
- Default server/centralized location: store backups in an application-owned path outside the repository, for example `/appdata/<appname>/backups/` or `/var/backups/<appname>/`.
|
|
- Keep retention tiers in separate directories: `daily/`, `weekly/`, `monthly/`, `yearly/`.
|
|
|
|
## Backup Naming and Format
|
|
|
|
Rules:
|
|
- Each snapshot must be a single archive or dump artifact when feasible.
|
|
- Backup filenames must include a timestamp and a version marker relevant to restore safety, for example schema version, migration number, app version, or backup format version.
|
|
- If multiple artifacts are backed up independently, include the artifact identity in the filename.
|
|
- Backups should be archived/compressed by default (`.zip`, `.tar.gz`, `.sql.gz`, `.dump.zst`, or equivalent) unless restore tooling requires a raw dump.
|
|
- Include all sidecar files required for a correct restore.
|
|
- Include the application config in the backup when it is required for a meaningful restore.
|
|
|
|
## Retention and Rotation
|
|
|
|
Use bounded retention. Do not keep an unbounded pile of snapshots.
|
|
|
|
Default policy:
|
|
- Daily: keep 7
|
|
- Weekly: keep 4
|
|
- Monthly: keep 12
|
|
- Yearly: keep 10
|
|
|
|
Rules:
|
|
- Prevent duplicate backups within the same retention period.
|
|
- Rotation/pruning must be automatic when the application manages recurring backups.
|
|
- Pre-migration or pre-repair safety backups may be kept outside normal rotation until the change is verified.
|
|
|
|
## Automated Backup Behavior
|
|
|
|
For applications that manage recurring local or operator-triggered backups:
|
|
|
|
Rules:
|
|
- On application startup, create a backup immediately if none exists yet for the current period.
|
|
- Support scheduled daily backups at a configured local time.
|
|
- Before migrations or other risky state-changing maintenance steps, trigger a fresh backup from the application-owned backup mechanism.
|
|
- If backup location, schedule, or retention is configurable, provide safe defaults and an explicit disable switch.
|
|
|
|
## Restore Readiness
|
|
|
|
Rules:
|
|
- The operator must know how to restore from the backup before applying risky changes.
|
|
- Restore steps must be documented next to the backup workflow.
|
|
- A backup that has never been validated for restore is only partially trusted.
|