owner: gmikcon status: draft last_reviewed: 2026-11-19 review_interval: 90d confidence: high
Move Gnexus Book from the file backend to PostgreSQL. The Git checkout is never modified by this procedure; it remains the rollback source until the cutover is accepted.
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.
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_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.The file backend remains intact. To roll back:
GNEXUS_BOOK_STORAGE_BACKEND=file.gnexus-book-backend and gnexus-book-mcp.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.