Newer
Older
gnexus-book / 30-runbooks / cutover-postgres.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 7 hours ago 3 KB docs: document data ownership rollout

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

source_of_truth: migration-runbook

PostgreSQL cutover runbook

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.

Preconditions

  • The pre-cutover backup has been copied off-host and restored at least once.
  • validate_repository is clean on the file backend.
  • The target PostgreSQL database exists and is reachable.
  • The target is either empty or the operator explicitly passes --replace.
  • The owner has chosen a maintenance window and confirmed the cutover.
  • Real gnexus-auth credentials are configured before exposing the service outside the LAN; database cutover and authentication cutover can be separate steps.

Rehearsal

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.

Cutover

  1. Announce the maintenance window and the rollback plan.
  2. Freeze writes to the file backend (stop the backend service or put it in maintenance mode).
  3. Run the cutover against the target database:

    GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://USER@HOST:PORT/gnexus_book \
      ./scripts/cutover-db.sh --replace
  4. 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).

  5. Set the service environment:

    GNEXUS_BOOK_STORAGE_BACKEND=db
    GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://...
  6. Restart gnexus-book-backend and gnexus-book-mcp.

  7. Run the post-cutover checks below.
  8. Unfreeze writes and announce completion.

Post-cutover checks

  • 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.
  • A test changeset can be proposed and applied, with validation passing.
  • The UI loads documents, history, inventory and status.
  • MCP over /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.
  • A fresh off-host dump exists and its checksum verifies.

Rollback

The file backend remains intact. To roll back:

  1. Set GNEXUS_BOOK_STORAGE_BACKEND=file.
  2. Restart gnexus-book-backend and gnexus-book-mcp.
  3. Run scripts/rollback-cutover.sh to verify file validation and document reads.
  4. If the database must be restored separately, use scripts/restore-db.sh with the pre-cutover dump and GNEXUS_BOOK_RESTORE_YES=1.

After acceptance

  • Keep the pre-cutover dump and the Git archive for the agreed retention period.
  • Remove the file write path only after the database backend has run without incident.
  • Record the cutover in gnexus-book and update the service page with backup and restore instructions.