Store Postgres backup artifacts in R2 with temporary local staging only - PR_26168_246-r2-backed-postgres-backupsc

Author: ToolboxAid

.env.example

@@ -18,6 +18,22 @@ GAMEFOUNDRY_SUPABASE_ANON_KEY=
 # Do not expose these values to browser JavaScript, HTML, reports, or screenshots.
 GAMEFOUNDRY_SUPABASE_SERVICE_ROLE_KEY=
 GAMEFOUNDRY_DATABASE_URL=
+
+# Server-only Postgres backup storage.
+# Copy this file to .env and keep the active deployment target's prefix:
+# DEV /dev/backups/postgres/
+# IST /ist/backups/postgres/
+# UAT /uat/backups/postgres/
+# PRD /prd/backups/postgres/
+# R2 object prefixes are created by object upload; no manual folder creation is required.
+GAMEFOUNDRY_DB_BACKUP_STORAGE_PROVIDER=r2
+GAMEFOUNDRY_DB_BACKUP_PREFIX=/dev/backups/postgres/
+
+# Optional temporary server-side pg_dump staging override.
+# Leave blank to use the OS temp directory. Do not point this at repo tmp/.
+GAMEFOUNDRY_DB_BACKUP_STAGING_DIR=
+
+# Deprecated: final backup artifacts are uploaded to R2, not stored here.
 GAMEFOUNDRY_DB_BACKUP_DIR=
 
 # Server-only project asset storage configuration.

docs_build/database/README.md

@@ -37,7 +37,7 @@ The database promotion lane is documented in [promotion-lane.md](promotion-lane.
 
 ## Backup And Restore
 
-The operator-controlled backup and restore lane is documented in [backup-restore-lane.md](backup-restore-lane.md). Backup and restore use `GAMEFOUNDRY_DATABASE_URL` from `.env`; restore requires an explicit operator checklist and confirmation phrase before any destructive command runs.
+The operator-controlled backup and restore lane is documented in [backup-restore-lane.md](backup-restore-lane.md). Backup uses `GAMEFOUNDRY_DATABASE_URL` from `.env`, temporary server-side `pg_dump --format=custom` staging, and the configured R2 backup prefix for final artifacts. Restore remains scaffold-only until safe R2 restore is explicitly implemented and still requires an operator checklist and confirmation phrase before any future destructive command can run.
 
 ## Runbook
 

docs_build/database/backup-restore-lane.md

@@ -10,47 +10,77 @@ GAMEFOUNDRY_DATABASE_URL
 
 Do not paste database URLs, passwords, service keys, or dump contents into reports.
 
-## Backup Command Path
+## Backup Operation Path
 
-Use the active `.env` as the source of the database connection. Do not pass deployment-target parameters.
+Use the active `.env` as the source of the database connection and R2 backup
+storage configuration. Do not pass deployment-target parameters.
 
-PowerShell operator flow:
+Required backup storage variables:
 
-```powershell
-$databaseUrl = (Get-Content .env |
-  Where-Object { $_ -match '^GAMEFOUNDRY_DATABASE_URL=' } |
-  Select-Object -First 1) -replace '^GAMEFOUNDRY_DATABASE_URL=', ''
-
-$backupPath = Join-Path (Get-Location) 'backups\gamefoundry-backup.dump'
-pg_dump --dbname $databaseUrl --format custom --file $backupPath
+```text
+GAMEFOUNDRY_DB_BACKUP_STORAGE_PROVIDER=r2
+GAMEFOUNDRY_DB_BACKUP_PREFIX=/dev/backups/postgres/
 ```
 
+Copy-source target files must use the matching prefix:
+
+- DEV: `/dev/backups/postgres/`
+- IST: `/ist/backups/postgres/`
+- UAT: `/uat/backups/postgres/`
+- PRD: `/prd/backups/postgres/`
+
+R2 prefixes are object-key prefixes. They are created by upload and do not
+require manual folder creation.
+
+Create Backup runs through Admin Operations and the Local API:
+
+1. Validate the current database connection.
+2. Run server-side `pg_dump --format=custom`.
+3. Write the `.dump` only to temporary server-side staging.
+4. Upload the `.dump` to the configured R2 backup prefix.
+5. Delete the temporary local dump after upload.
+6. Report PASS/FAIL without exposing database passwords or storage secrets.
+
+`GAMEFOUNDRY_DB_BACKUP_DIR` is deprecated for final backup storage. If
+temporary staging must be overridden, use
+`GAMEFOUNDRY_DB_BACKUP_STAGING_DIR` and keep it outside repo `tmp/`.
+
 Validation expectation:
 
 - `.env` exists
 - `GAMEFOUNDRY_DATABASE_URL` is present
-- `pg_dump` is available on the operator machine
-- the backup file is written outside tracked source paths
-- reports state only the backup path and success/failure, not the connection string
+- `GAMEFOUNDRY_DB_BACKUP_STORAGE_PROVIDER` is `r2`
+- `GAMEFOUNDRY_DB_BACKUP_PREFIX` matches the active target prefix
+- R2 endpoint, bucket, access key, and secret key are configured server-side
+- `pg_dump` is available on the Local API host
+- the local dump is temporary staging only and is deleted after upload
+- reports state only R2 key, filename, size, timestamp, environment, and
+  success/failure, not the connection string or storage secrets
 
 Backup metadata must be recorded without secrets:
 
 - `backupName`
 - `databaseName`
 - `createdAt`
 - `migrationVersion`
+- `environment`
+- `fileName`
+- `r2Key`
+- `sizeBytes`
 
 Use `schema_migrations` to derive `migrationVersion`; do not use
 `platform_settings` for backup migration state.
 
 ## Restore Checklist
 
-Restore is destructive. Do not run restore unless every checklist item is complete:
+Restore is destructive. Admin Operations Restore From Backup remains
+scaffold-only until a later PR explicitly implements safe R2 restore. Do not
+run restore unless every checklist item is complete:
 
 - Confirm the target `.env` is the intended database.
 - Run `node .\scripts\validate-runtime-connections.mjs` and record PASS/FAIL.
 - Validate the current `schema_migrations` state before applying restore.
-- Confirm the backup file path and checksum.
+- Confirm the R2 backup key, filename, size, timestamp, and checksum.
 - Confirm the backup metadata `migrationVersion`.
 - Confirm the application is stopped or in a maintenance window.
 - Confirm owner approval.
@@ -61,27 +91,15 @@ Restore is destructive. Do not run restore unless every checklist item is comple
 
 ## Restore Command Path
 
-PowerShell operator flow:
-
-```powershell
-$confirmation = Read-Host 'Type RESTORE CONFIRMED to restore the configured database'
-if ($confirmation -ne 'RESTORE CONFIRMED') {
-  throw 'Restore cancelled because confirmation did not match.'
-}
-
-$databaseUrl = (Get-Content .env |
-  Where-Object { $_ -match '^GAMEFOUNDRY_DATABASE_URL=' } |
-  Select-Object -First 1) -replace '^GAMEFOUNDRY_DATABASE_URL=', ''
-
-$backupPath = Join-Path (Get-Location) 'backups\gamefoundry-backup.dump'
-pg_restore --dbname $databaseUrl --clean --if-exists --single-transaction $backupPath
-```
+No active Restore From Backup command path is approved in this PR. Safe R2
+restore must be explicitly implemented and reviewed before `pg_restore` is
+available through Admin Operations.
 
 Restore reports must include:
 
 - target host, port, and database name only
 - backup metadata: `backupName`, `databaseName`, `createdAt`, and `migrationVersion`
-- backup file path
+- R2 backup key and filename
 - backup checksum
 - migration state validation before restore
 - confirmation checklist status

docs_build/database/runbook.md

@@ -95,32 +95,41 @@ execution is allowed.
 
 ## Backup
 
-Use the backup path documented in
+Use the backup operation path documented in
 [backup-restore-lane.md](backup-restore-lane.md). Backups use
-`GAMEFOUNDRY_DATABASE_URL` from `.env`.
+`GAMEFOUNDRY_DATABASE_URL` from `.env`, write `pg_dump --format=custom` only
+to temporary server-side staging, and upload the final `.dump` artifact to the
+configured R2 backup prefix.
 
 Minimum backup checklist:
 
 - Confirm `.env` points at the intended database.
 - Confirm `pg_dump` is installed.
+- Confirm `GAMEFOUNDRY_DB_BACKUP_STORAGE_PROVIDER=r2`.
+- Confirm `GAMEFOUNDRY_DB_BACKUP_PREFIX` matches the active target:
+  `/dev/backups/postgres/`, `/ist/backups/postgres/`,
+  `/uat/backups/postgres/`, or `/prd/backups/postgres/`.
 - Record backup metadata: `backupName`, `databaseName`, `createdAt`, and
   `migrationVersion`.
-- Write backup files outside tracked source paths.
-- Record backup path and checksum only.
+- Confirm R2 prefixes require no manual folder creation.
+- Confirm temporary local staging is deleted after successful upload.
+- Record R2 key, filename, size, timestamp, environment, and checksum only.
 - Do not write secrets, full URLs, service role keys, or dump contents to
   reports.
 
 ## Restore
 
 Use the restore path documented in
-[backup-restore-lane.md](backup-restore-lane.md). Restore is destructive and
-must require explicit operator confirmation.
+[backup-restore-lane.md](backup-restore-lane.md). Restore is destructive,
+remains scaffold-only until safe R2 restore is explicitly implemented, and must
+require explicit operator confirmation before any future destructive command can
+run.
 
 Minimum restore checklist:
 
 - Confirm `.env` points at the intended target database.
 - Validate the current `schema_migrations` state before applying restore.
-- Confirm the backup file path and checksum.
+- Confirm the R2 backup key, filename, size, timestamp, and checksum.
 - Confirm backup metadata, including `migrationVersion`.
 - Stop the application or enter a maintenance window.
 - Confirm owner approval.

docs_build/dev/codex_commands.md

@@ -2613,3 +2613,33 @@ Required reports:
 
 Packaging:
 - `tmp/PR_26168_235-owner-operations-scope-cleanup_delta.zip`
+
+
+## PR_26168_246-r2-backed-postgres-backups
+
+Changes:
+- Read `docs_build/dev/PROJECT_INSTRUCTIONS.md`.
+- Verified the current branch is `main`.
+- Updated Create Backup to stage `pg_dump --format=custom` output in temporary server-side storage only.
+- Uploaded final `.dump` artifacts to the configured R2 backup prefix.
+- Added backup storage provider and prefix configuration for R2-backed Postgres backups.
+- Deprecated `GAMEFOUNDRY_DB_BACKUP_DIR` for final backup storage.
+- Kept Restore From Backup scaffold-only.
+
+Validation:
+- `node --check` for changed JS/MJS and Playwright files.
+- `node --test tests/dev-runtime/PostgresBackupService.test.mjs`
+- `npx playwright test tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs --grep "Admin Operations" --reporter=line`
+- `git diff --check -- touched files`
+- Static checks for no `.dump` artifacts and no inline Admin Operations HTML violations.
+- Full samples smoke skipped because sample JSON and sample runtime behavior were not touched.
+
+Required reports:
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+- `docs_build/dev/reports/PR_26168_246-r2-backed-postgres-backups.md`
+- `docs_build/dev/reports/playwright_v8_coverage_report.txt`
+- `docs_build/dev/reports/coverage_changed_js_guardrail.txt`
+
+Packaging:
+- `tmp/PR_26168_246-r2-backed-postgres-backups_delta.zip`

docs_build/dev/commit_comment.txt

@@ -1 +1 @@
-Admin operations order and safety - PR_26168_236-admin-operations-order-and-safety
+R2 backed Postgres backups - PR_26168_246-r2-backed-postgres-backups

docs_build/dev/reports/PR_26168_246-r2-backed-postgres-backups.md

@@ -0,0 +1,140 @@
+# PR_26168_246-r2-backed-postgres-backups
+
+## Branch Validation
+
+PASS - Current branch is `main`; expected branch is `main`.
+
+Local branches found:
+
+```text
+main
+```
+
+## Summary
+
+Create Backup now validates the current database connection through Admin Operations, runs server-side `pg_dump --format=custom`, writes the dump only to temporary server-side staging, uploads the final `.dump` to the configured R2 backup prefix, and removes staging after upload. `GAMEFOUNDRY_DB_BACKUP_DIR` is deprecated for final backup storage.
+
+Restore From Backup remains scaffold-only.
+
+## Requirement Checklist
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Read `docs_build/dev/PROJECT_INSTRUCTIONS.md` first | PASS | Read before implementation and followed BUILD/report/ZIP rules. |
+| Hard stop unless current branch is `main` | PASS | `git branch --show-current` returned `main`; local branch list contained `main`. |
+| Upload final Create Backup artifacts to R2 instead of permanently storing in `GAMEFOUNDRY_DB_BACKUP_DIR` | PASS | `createPostgresBackup` uploads via configured R2 storage and only reports the R2 key. |
+| Validate current DB connection before backup | PASS | `createBackupAction()` still calls `validateBackupDatabaseConnection()` before `createPostgresBackup()`. |
+| Run server-side `pg_dump --format=custom` | PASS | Backup service keeps `--format=custom`; Node test asserts the dump command args. |
+| Write dump to temporary server-side staging only | PASS | Backup service uses OS temp or `GAMEFOUNDRY_DB_BACKUP_STAGING_DIR`; repo `tmp/` staging is rejected. |
+| Upload `.dump` to configured R2 backup prefix | PASS | `createConfiguredBackupStorage()` loads `GAMEFOUNDRY_DB_BACKUP_PREFIX`; configured fake R2 validation captured the PUT. |
+| Delete temporary local dump after successful upload | PASS | Node test asserts the staged file and staging directory are removed after PASS. |
+| Report PASS/FAIL with R2 key, filename, size, timestamp, and environment | PASS | Success and upload-failure results include backup metadata; Playwright asserts visible R2 key PASS/FAIL behavior. |
+| Add safe env placeholders and copy-source guidance | PASS | `.env.example` includes provider, prefix, staging note, and deprecated backup-dir guidance. |
+| Use environment-specific prefixes for DEV, IST, UAT, PRD | PASS | `.env.example` and database docs list `/dev/`, `/ist/`, `/uat/`, and `/prd/backups/postgres/`; config validates allowed prefixes. |
+| R2 prefixes must not require manual folder creation | PASS | `.env.example` and database docs state prefixes are object-key prefixes created by upload. |
+| Treat `GAMEFOUNDRY_DB_BACKUP_DIR` as deprecated final storage | PASS | Code ignores it for final storage and only appends a deprecation note when present. |
+| Rename/document local staging as temporary only | PASS | Added `GAMEFOUNDRY_DB_BACKUP_STAGING_DIR` as optional temporary staging override. |
+| Do not store backups in repo `tmp/` | PASS | Staging root under repo `tmp/` returns FAIL; no `.dump` files were found. |
+| Do not commit backup files | PASS | `rg --files -g '*.dump'` returned no matches. |
+| Do not expose DB password, storage keys, or secrets | PASS | DB password stays in `PGPASSWORD`; tests assert command args and UI/report messages do not expose secret fixture values. |
+| Restore From Backup remains guarded/scaffold-only | PASS | Restore action remains `SKIP`; docs state no approved safe R2 restore path exists in this PR. |
+| Use existing storage provider contract where possible | PASS | Backup uses the existing R2 signed storage module and `putObject` contract, with backup-specific config. |
+| Do not add unrelated Project Package, migration, or workspace behavior | PASS | Changes are limited to backup storage, Admin Operations backup diagnostics/tests, env/docs, and required reports. |
+| Do not run full samples smoke | PASS | Full samples smoke was skipped; no sample JSON or sample runtime behavior changed. |
+
+## Validation Lane Report
+
+Impacted lane: Admin Operations backup action, Local API backup service, R2 storage provider config, and database backup docs.
+
+Skipped broad lanes: full samples, engine-wide runtime, Project Package, migration, and Project Workspace lanes. They were safe to skip because no sample JSON, engine core, package import/export behavior, migration runner, or Project Workspace runtime files changed.
+
+PASS - Syntax/static checks:
+
+```text
+node --check src/dev-runtime/storage/storage-config.mjs
+node --check src/dev-runtime/storage/r2-project-asset-storage.mjs
+node --check src/dev-runtime/database/postgres-backup-service.mjs
+node --check src/dev-runtime/server/local-api-router.mjs
+node --check assets/theme-v2/js/admin-operations.js
+node --check src/engine/api/admin-operations-api-client.js
+node --check tests/dev-runtime/PostgresBackupService.test.mjs
+node --check tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs
+```
+
+PASS - Targeted Local API backup and R2 upload validation:
+
+```text
+node --test tests/dev-runtime/PostgresBackupService.test.mjs
+```
+
+Result: 7 passed.
+
+Covered:
+
+- Missing R2 backup storage visible FAIL.
+- Missing `pg_dump` visible FAIL.
+- Repo `tmp/` staging rejection.
+- `pg_dump --format=custom` command construction without DB password in args.
+- Successful R2 upload metadata with R2 key, filename, size, timestamp, and environment.
+- Temporary staged dump and staging directory cleanup after successful upload.
+- R2 upload failure reports key metadata and cleans staging.
+- Configured R2 provider path against a fake local R2-compatible server.
+
+PASS - Targeted Admin Operations Playwright / visible PASS/FAIL behavior:
+
+```text
+npx playwright test tests/playwright/tools/AdminPlatformToolsWireframes.spec.mjs --grep "Admin Operations" --reporter=line
+```
+
+Result: 4 passed.
+
+Covered:
+
+- Create Backup visible PASS message includes the R2 key.
+- Create Backup visible FAIL message is actionable when backup storage config is missing.
+- Restore From Backup remains scaffold-only.
+- Admin Operations order, safety table, non-admin block, and DEV-only reseed gating remain intact.
+
+PASS - Static artifact and HTML checks:
+
+```text
+rg --files -g '*.dump' -g '!node_modules' -g '!tests/results' -g '!tmp'
+rg --pcre2 -n "<script(?![^>]+src=)|<style|\s(onclick|onchange|oninput|onsubmit|onkeydown|onkeyup|onload)=" admin/operations.html
+git diff --check
+```
+
+Results:
+
+- No `.dump` files found.
+- No inline Admin Operations HTML violations found.
+- `git diff --check` passed with line-ending warnings only.
+
+PASS/WARN - Playwright V8 coverage report generated:
+
+- `docs_build/dev/reports/playwright_v8_coverage_report.txt`
+- `docs_build/dev/reports/coverage_changed_js_guardrail.txt`
+- WARN entries are expected for Node-only Local API/storage modules that browser V8 coverage cannot collect.
+
+## Manual Validation Notes
+
+PASS - The tested R2 path used a local fake R2-compatible server and the real configured storage factory, not real production credentials.
+
+PASS - Successful backup tests verified that temporary local staging is removed after upload.
+
+PASS - No real database password, storage access key, storage secret key, service role key, full database URL, or raw dump content was written to reports or UI messages.
+
+PASS - Actual live backup creation still requires a real `.env`, reachable Postgres database, installed PostgreSQL client tools on the Local API host, and configured R2 credentials.
+
+SKIP - Full samples smoke was not run because this PR only changes Admin Operations backup feedback, Local API backup service/storage behavior, env/docs, and targeted tests.
+
+## Artifacts
+
+PASS - Required reports:
+
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+- `docs_build/dev/reports/PR_26168_246-r2-backed-postgres-backups.md`
+
+PASS - Repo-structured delta ZIP:
+
+- `tmp/PR_26168_246-r2-backed-postgres-backups_delta.zip`