Newer
Older
gnexus-book / 30-runbooks / decommission-file-backend.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 3 days ago 2 KB docs: add operations and decommission runbooks

owner: gmikcon status: draft last_reviewed: 2026-11-19 review_interval: 90d confidence: high

source_of_truth: migration-runbook

Decommission the file backend

Remove the file write path and Git adapter after the production cutover is accepted. Not executed yet. The file backend remains available for rollback and for tests until the prerequisites below are met.

Prerequisites

  • Production has run on GNEXUS_BOOK_STORAGE_BACKEND=db for an agreed stability window with no unresolved data incidents.
  • The pre-cutover dump and a fresh post-cutover dump have both passed restore drills.
  • validate_repository and validate_database are clean.
  • The parity suite reports zero differences.
  • The owner has signed off the decommission in writing.

Steps

  1. Archive the original Git repository:
    • create a git bundle of all refs and a worktree archive;
    • copy both off-host and verify SHA-256 and a restore.
  2. Keep the last pre-decommission PostgreSQL dump off-host with the agreed retention.
  3. Update defaults so tests and development no longer depend on the file backend.
  4. Remove the file write path:
    • DocsRepository, InventoryRepository write paths where no longer needed;
    • GitAdapter commit path and /commit routing;
    • file-specific pending changes (90-maintenance/pending-changes/*.json).
  5. Retarget the test suite to the database backend and remove file-parity fixtures that no longer have a reference implementation.
  6. Remove unused configuration (GNEXUS_BOOK_STORAGE_BACKEND=file branches) and dependencies.
  7. Update the service page, README, CLAUDE.md and this runbook.
  8. Run the full test suite, validation, parity checks that still make sense, and a restore drill.

Rollback

Until the Git archive and the pre-decommission dump are retired:

  • restore the service from the last dump if the database is damaged;
  • restore the file backend from the Git archive if the database path must be abandoned entirely.

After both artifacts are retired, rollback is no longer possible.

Status

Blocked on the production cutover and owner sign-off. No file-backend code has been removed.