mchus/bible
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Require application-owned backups for migrations

Browse Source
This commit is contained in:
Mikhail Chusavitin
2026-03-07 21:56:51 +03:00
parent 61ed2717d0
commit f55bd84668
2 changed files with 9 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
rules/patterns/backup-management/contract.md
View File

@@ -1,6 +1,6 @@
# Contract: Backup Management # Contract: Backup Management
Version: 1.0 Version: 1.1
## Purpose ## Purpose
@@ -8,12 +8,14 @@ Version: 1.0
## Backup Capability Must Be Shipped ## Backup Capability Must Be Shipped
Backup/restore must be part of the application or its shipped operator tooling. Do not assume the operator already has suitable software installed on their machine. 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: 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. - 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. - 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 a shipped maintenance script/runbook that is part of the project. - 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. - Rollout instructions must reference only shipped or implemented backup/restore paths.
## Backup Storage ## Backup Storage
@@ -60,6 +62,7 @@ For applications that manage recurring local or operator-triggered backups:
Rules: Rules:
- On application startup, create a backup immediately if none exists yet for the current period. - On application startup, create a backup immediately if none exists yet for the current period.
- Support scheduled daily backups at a configured local time. - 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. - If backup location, schedule, or retention is configurable, provide safe defaults and an explicit disable switch.
## Restore Readiness ## Restore Readiness

5
rules/patterns/go-database/contract.md
View File

@@ -1,6 +1,6 @@
# Contract: Database Patterns (Go / MySQL / MariaDB) # Contract: Database Patterns (Go / MySQL / MariaDB)
Version: 1.4 Version: 1.5
## MySQL Transaction Cursor Safety (CRITICAL) ## MySQL Transaction Cursor Safety (CRITICAL)
@@ -122,11 +122,12 @@ Rules:
- "Small" or "safe" changes are not exceptions. - "Small" or "safe" changes are not exceptions.
- The operator must know how to restore from that backup before applying the change. - The operator must know how to restore from that backup before applying the change.
- If a migration or script is intended for production/staging, the rollout instructions must state the backup step explicitly. - If a migration or script is intended for production/staging, the rollout instructions must state the backup step explicitly.
- The backup taken before a migration must be triggered by the application's own backup mechanism, not by assuming `mysql`, `mysqldump`, or other DB client tools exist on the user's machine.
## Migration Policy ## Migration Policy
- Migrations are numbered sequentially and never modified after merge. - Migrations are numbered sequentially and never modified after merge.
- Take and verify a fresh backup before applying migrations to any non-ephemeral database. - Trigger, take, and verify a fresh backup through the application-owned backup mechanism before applying migrations to any non-ephemeral database.
- Each migration must be reversible where possible (document rollback in a comment). - Each migration must be reversible where possible (document rollback in a comment).
- Never rename a column in one migration step — add new, backfill, drop old across separate deploys. - Never rename a column in one migration step — add new, backfill, drop old across separate deploys.
- Auto-apply migrations on startup is acceptable for internal tools; document if used. - Auto-apply migrations on startup is acceptable for internal tools; document if used.