---
name: replace-production-database
description:
  Replace the populated SHD.build production database with a local full
  bootstrap bundle after verified backups. Use only when the user explicitly
  authorizes replacement of all production data.
---

# Replace Production Database

This procedure overwrites production users, sessions, builds, guides, audits,
proposals, settings, and source data. Obtain explicit approval for a full
replacement. Use the ISAC import flow when the request only concerns canonical
game data.

## Export

1. Stop only this repository's local development server. The embedded database
   must be closed during export.
2. Run `npm run production:bootstrap:export`. Record the generated bundle
   beneath `data/backups/`; it includes private account data and uploaded
   assets.
3. Transfer the bundle to `f302` over SSH. Keep it outside Git and confirm the
   remote copy is nonempty.

## Replace

1. Confirm the current production deployment is healthy and no Gitea production
   deployment is running.
2. On `f302`, stop only the production `app` and `scheduler` services from
   `/opt/shd-build-production`.
3. Run `node scripts/db-backup.mjs` through the production Compose service.
   Record and retain the JSON backup path before any destructive work.
4. Reset the production database file and its embedded-database support files.
   Keep the persistent volume and existing upload directories; the import writes
   the local avatar and managed-image files without deleting retained files.
5. Run `node scripts/db-migrate.mjs` through the production Compose service to
   create the current empty schema.
6. Run `/opt/shd-build-production/bootstrap-production.sh <bundle-path>`. The
   script stages the bundle in the private data volume, assigns it to the
   runtime UID, runs `environment-bootstrap-import.mjs` with the required
   confirmation, removes the staged copy, and restarts both services.
7. Wait for app health, then remove the remote transfer bundle.

## Verify

1. Confirm the importer reports the expected row, avatar, and managed-image
   counts.
2. Confirm `https://shd.build/api/health` returns `ready: true` with an `ok`
   database check.
3. Confirm the production app container is healthy and its scheduler is running.
4. Restart the local development server and verify it accepts an HTTP request.

## Guardrails

- Never replace a populated production database without explicit user approval.
- Never delete the production Compose volume.
- Do not replace the database while the app or scheduler can write to it.
- Keep the verified pre-replacement backup. It is the recovery source if the
  import or restart fails.