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

```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 put it in
   maintenance mode).
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. Set the service environment:

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

5. Restart `gnexus-book-backend` and `gnexus-book-mcp`.
6. Run the post-cutover checks below.
7. 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.
- 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.
