owner: gmikcon status: draft last_reviewed: 2026-11-20 review_interval: 90d confidence: high
Move Gnexus Book from the file backend to PostgreSQL. The production cutover was completed on 2026-11-20; this runbook remains the procedure for a rehearsal or a future rebuild. The Git checkout is never modified by the cutover and remains a read-only rollback source after the file write path is frozen.
validate_repository is clean on the file backend.--replace.Always rehearse on a disposable database first:
createdb gnexus_book_cutover GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://USER@HOST:PORT/gnexus_book_cutover \ ./scripts/cutover-db.sh --replace
The script runs the importer, validates the imported database, reconciles file and database reads (documents, search, inventory, relationships, validation, freshness), and writes a migration report. It must exit 0.
GNEXUS_BOOK_FILE_BACKEND_FROZEN=true before switching the backend. File writes then fail with a clear error instead of silently diverging from PostgreSQL.Run the cutover against the target database:
GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://USER@HOST:PORT/gnexus_book \ ./scripts/cutover-db.sh --replace
Assign imported data to the first admin (recommended). Either set GNEXUS_BOOK_OWNER_JSON=/path/to/owner.json before step 3 (then cutover-db.sh assigns it after import), or run after import:
cd server GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://... \ .venv/bin/python -m app.storage.cli assign-owner \ --user-json /path/to/owner.json .venv/bin/python -m app.storage.cli ownership
The owner JSON contains sub, email, system_role, status and profile (display_name, locale, timezone, avatar URL).
Set the service environment:
GNEXUS_BOOK_STORAGE_BACKEND=db GNEXUS_BOOK_FILE_BACKEND_FROZEN=true GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://...
Restart gnexus-book-backend and gnexus-book-mcp.
GET /health reports storage: db and checks.db.status: ok.GET /docs, /search, /inventory, /relationships, /validate, /health/freshness return the expected data.GET /documents/<path>/history returns imported version 1./mcp-protocol/ works from the public hostname (no 421 Invalid Host header); GNEXUS_BOOK_MCP_ALLOWED_HOSTS includes that host and GNEXUS_BOOK_MCP_ALLOWED_ORIGINS includes its HTTPS origin.Parity is a cutover check, not a permanent invariant. Once PostgreSQL is canonical, writes through MCP/API make the file backend older by design; a later parity run may report differences and that is expected. Do not "fix" parity by copying files over the database.
The file backend is frozen but intact. To roll back:
gnexus-book-backend and gnexus-book-mcp.GNEXUS_BOOK_STORAGE_BACKEND=file and, as an explicit break-glass action, GNEXUS_BOOK_FILE_BACKEND_FROZEN=false.scripts/rollback-cutover.sh to verify file validation and document reads.scripts/restore-db.sh with the pre-cutover dump and GNEXUS_BOOK_RESTORE_YES=1.