jinojose/aipackage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
aipackage/specs/001-enterprise-experience/migrations.md

1.2 KiB
Raw Permalink Blame History

SQLite Migration and Rollback Procedure

Rules

  1. Read the current schema version before application startup writes new data.
  2. Create a verified pre-migration backup of the database and required companion state.
  3. Apply sequential idempotent migrations in one exclusive transaction where SQLite permits.
  4. Record the new version only after all statements and validation checks succeed.
  5. On failure, roll back the transaction, preserve the original database and record a redacted error.
  6. Never downgrade destructively. Restore the pre-migration backup when rollback requires an older application version.

Validation

  • Fresh database reaches the latest version.
  • Each supported previous version upgrades exactly once.
  • Re-running the migration is a no-op.
  • Interrupted/failed migration leaves a usable prior database or verified recovery copy.
  • Existing users, sessions, audit history, licensing state, settings and supported customer data remain readable.
  • Backup compatibility is checked before any restore mutation.

Rollback Evidence

Record source and target schema versions, backup path/checksum, start/end time, result, correlation ID, validation outcome, and recovery action without storing secrets or customer content.