---
owner: gmikcon
status: draft
last_reviewed: 2026-11-20
review_interval: 90d
confidence: high
source_of_truth: migration-runbook
---

# PostgreSQL cutover runbook

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.

## 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:

```bash
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 set
   `GNEXUS_BOOK_FILE_BACKEND_FROZEN=true` before switching the backend. File writes
   then fail with a clear error instead of silently diverging from PostgreSQL.
3. Run the cutover against the target database:

   ```bash
   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:

   ```bash
   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:

   ```text
   GNEXUS_BOOK_STORAGE_BACKEND=db
   GNEXUS_BOOK_FILE_BACKEND_FROZEN=true
   GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://...
   ```

6. Restart `gnexus-book-backend` and `gnexus-book-mcp`.
7. Run the post-cutover checks below.
8. Leave the file write path frozen 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.

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.

## Rollback

The file backend is frozen but intact. To roll back:

1. Take a fresh PostgreSQL dump and record it as the current database point.
2. Stop `gnexus-book-backend` and `gnexus-book-mcp`.
3. Set `GNEXUS_BOOK_STORAGE_BACKEND=file` and, as an explicit break-glass action,
   `GNEXUS_BOOK_FILE_BACKEND_FROZEN=false`.
4. Restore the pre-cutover file tree from the Git archive/tar if it has changed since
   the cutover.
5. Restart the services and run `scripts/rollback-cutover.sh` to verify file validation
   and document reads.
6. If the database must be restored separately, use `scripts/restore-db.sh` with the
   pre-cutover dump and `GNEXUS_BOOK_RESTORE_YES=1`.
7. Record the rollback and re-freeze file writes once the database is selected again.

## After acceptance

- Keep the pre-cutover dump and the Git archive for the agreed retention period.
- Keep file writes frozen; remove the write path only after the database backend has
  run without incident and the owner signs off the decommission runbook.
- Archive legacy pending-change JSON before deleting it; the 2026-11-20 archive is the
  precedent.
- Record the cutover in gnexus-book and update the service page with backup and
  restore instructions.
