Newer
Older
gnexus-book / 30-runbooks / decommission-file-backend.md

owner: gmikcon status: draft last_reviewed: 2026-11-20 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. The file write path is already frozen on gnbook (GNEXUS_BOOK_FILE_BACKEND_FROZEN=true) and the legacy pending-change JSON was archived; the remaining code removal is still pending owner sign-off.

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 cutover parity report has been recorded; parity is no longer a permanent invariant after database writes begin.
  • Legacy pending-change JSON has been archived off-host with a manifest.
  • 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. Keep GNEXUS_BOOK_FILE_BACKEND_FROZEN=true so file writes fail even if the backend selection is changed by mistake.
  4. Archive any remaining file-specific pending changes under 90-maintenance/pending-changes/; the 2026-11-20 archive is the precedent.
  5. Update defaults so tests and development no longer depend on the file backend.
  6. 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).
  7. Retarget the test suite to the database backend and remove file-parity fixtures that no longer have a reference implementation.
  8. Remove unused configuration (GNEXUS_BOOK_STORAGE_BACKEND=file branches) and dependencies.
  9. Update the service page, README, CLAUDE.md and this runbook.
  10. 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;
  • to use the file backend during rollback, explicitly set GNEXUS_BOOK_FILE_BACKEND_FROZEN=false and record the break-glass action.

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

Status

Partially executed on 2026-11-20: file writes are frozen, legacy pending changes were archived and removed, and the database is canonical. The file-backend code has not been removed; full decommission remains blocked on the production stability window and owner sign-off.