@marinoscar/kvox-eval 0.0.0-bootstrap → 0.1.0-next.0

package/host/prisma/schema/platform.db-backup.prisma

@@ -0,0 +1,359 @@
+// GENERATED by platform db compose — do not edit
+// source: package:db-backup.prisma
+
+// =============================================================================
+// Database Backup Runs (issue #281, epic #254)
+// =============================================================================
+//
+// One row per attempt to dump this deployment's PostgreSQL database into
+// object storage — and, from Phase 7 onwards, per attempt to restore FROM one.
+// `DatabaseBackupRunnerService` (`src/db-backup/db-backup-runner.service.ts`)
+// is the only writer of the backup half; the columns in the restore-audit
+// group are declared here now and written by #285.
+//
+// -----------------------------------------------------------------------------
+// ### Why this WAS not a queue job, and why it now is (issue #351, epic #345)
+// -----------------------------------------------------------------------------
+//
+// ⚠ THIS SECTION USED TO SAY "DO NOT MIGRATE THIS ONTO THE QUEUE". It has
+// been migrated, deliberately, and the history is kept because the three
+// objections were correct and a reader needs to know WHERE EACH IS NOW
+// ANSWERED rather than assume they were waved away.
+//
+//   1. `jobs.stuckThresholdMinutes` DEFAULTS TO 30 MINUTES. A dump of a real
+//      production database routinely runs longer than that. The lease reaper
+//      (`JobStuckResetTask`) would see a `running` job whose lease had
+//      expired, conclude its executor had died, and RESET IT TO `pending` —
+//      while `pg_dump` was still streaming. The next claim starts a SECOND
+//      `pg_dump`, writing to the SAME derived storage key as the first, and
+//      two processes interleave their output into one object.
+//      → ANSWERED BY #346's PER-TYPE PROFILES. `db.backup.run` declares
+//      `maxRuntimeMs: 6h`, and the claim's lease is DERIVED from that ceiling
+//      (`resolveJobLeaseMs`), never declared beside it — so a lease shorter
+//      than the permitted runtime is unrepresentable rather than merely
+//      avoided.
+//   2. THE IN-PROCESS WORKER HAS NO LEASE-RENEWAL PATH. `JobWorker` claimed
+//      with a lease and never extended it, so the reaper's verdict above was
+//      not a rare race but unconditional for any long job.
+//      → ANSWERED BY #347. The worker renews on a ticker (lease ÷ 3) for
+//      exactly as long as `process()` runs.
+//   3. A JOB HAS `attempts` AND A RETRY BUDGET. Automatically re-running a
+//      failed multi-gigabyte dump is exactly the wrong behaviour: it burns
+//      hours of I/O on a database that is probably already unwell, and the
+//      correct retry for a backup is "the next scheduled one", tomorrow.
+//      → ANSWERED BY `maxAttempts: 1` on the same profile. The policy did not
+//      change; what changed is that `JobStuckService`'s give-up phase now
+//      ENFORCES it, instead of it holding by the accident of there being no
+//      queue to disagree.
+//
+// This table still has its OWN heartbeat (`lastHeartbeatAt`, written every
+// ~20s with live `bytesWritten`), its OWN staleness policy
+// (`databaseBackup.runStaleMinutes`) and its OWN terminal states, and all
+// three are still load-bearing — but their jobs have narrowed. The heartbeat
+// is now PROGRESS REPORTING for the UI (the lease is the liveness signal),
+// and the stale sweep is the backstop for the one path that still has no job:
+// the `pre_restore` safety dump, which `DatabaseRestoreService` takes through
+// `startBackup` because a restore must not wait on a worker slot.
+//
+// ⚠ THE TWO ROWS ARE NOT REDUNDANT. The `jobs` row answers who asked, when,
+// which executor, which attempt and what error; this row answers what was
+// PRODUCED — key, bucket, bytes, checksum, `verifiedAt`, the db/app/migration
+// audit and the restore audit. They also have independent lifetimes: a job is
+// purged by `job.history.purge` on a retention schedule that has nothing to do
+// with how long the archive is kept, which is exactly why `jobId` is
+// `onDelete: SetNull` and not `Cascade`.
+//
+// -----------------------------------------------------------------------------
+// THE SINGLE-ACTIVE-RUN GUARD IS A PARTIAL UNIQUE INDEX, NOT APPLICATION CODE
+// -----------------------------------------------------------------------------
+//
+// `database_backup_runs_active_uniq_idx` (hand-written in
+// `prisma/migrations/20260907120000_add_database_backup_runs/migration.sql`,
+// TIGHTENED by
+// `prisma/migrations/<add_backup_run_job_link>/migration.sql`, epic #345,
+// issue #351 — see that migration's own header for why) is a UNIQUE index on
+// the CONSTANT EXPRESSION `(true)` restricted to `status IN
+// ('pending','running')`. It is what makes "at most one backup at a time"
+// true ACROSS REPLICAS.
+//
+// REJECTED: a `findFirst({ where: { status: 'running' } })` before the insert.
+// It is a check-then-act race, and it is racy exactly when it matters — a
+// scheduled tick on replica A and an admin's manual click on replica B, in
+// the same second. Both would see no active run, both would insert, and two
+// `pg_dump` processes would stream into two objects while the settings say
+// one backup a night. Only the database can make "is one already active"
+// atomic with the insert that would violate it.
+//
+// The loser's Prisma `P2002` becomes a typed `DatabaseBackupAlreadyRunningError`
+// carrying the winner's run id, which #282/#283 turn into a 409.
+//
+// ⚠ PRISMA CANNOT EXPRESS THIS INDEX — INTENTIONAL SCHEMA DRIFT. The schema
+// language has no syntax for a partial index OR an expression index, exactly
+// as recorded above the `Job` model for `jobs_active_dedup_uniq_idx` and its
+// two siblings. So `prisma migrate dev`/`diff` will not regenerate it and, if
+// anyone diffs this schema against a live database, will want to DROP it.
+// That drift is deliberate and permanent: do not "fix" it, and do not try to
+// force it into `@@unique` syntax that does not exist. The migration file
+// carries the same warning next to the statement itself.
+//
+// ⚠ WHAT THE INDEX ADMITS, PRECISELY, AND WHY THAT CHANGED. The ORIGINAL index
+// keyed on the `status` COLUMN, filtered to two values — that admits at most
+// one `pending` row AND at most one `running` row AT THE SAME TIME, i.e. TWO
+// active runs, not one. That was harmless only as long as
+// `DatabaseBackupRunnerService` inserted its claim directly as `running` and
+// never wrote `pending`. #351 makes the backup a queue job: `POST
+// /api/admin/db-backup/runs` now enqueues the job and creates the run row in
+// `pending` BEFORE any worker has claimed it (so the endpoint can return a run
+// id immediately and `GET /runs/{id}` keeps working), and the handler flips it
+// to `running` once claimed. The moment `pending` rows are real, the
+// column-keyed index stops meaning "at most one active run" and starts
+// meaning "at most two". Keying on `(true)` instead makes every active row —
+// whichever of the two statuses it holds — index to the SAME key, so at most
+// one can exist across both statuses COMBINED. This is the exact tightening
+// this comment always said a future path needing both states populated at
+// once would require ("tighten this index to a constant expression, never
+// move the guard into a service") — it has now happened.
+//
+// -----------------------------------------------------------------------------
+// WHY THE RESTORE AUDIT LIVES ON THE BACKUP'S OWN ROW
+// -----------------------------------------------------------------------------
+//
+// `restoreStatus`, `restoreError`, `restoredAt`, `restoredById`,
+// `restoreScratchDb`, `restoreOldDb`, `swappedAt` and `preRestoreBackupId` are
+// all nullable and all belong to Phase 7. They are columns on THIS table
+// rather than a `database_restore_runs` table because A RESTORE IS ALWAYS
+// DEFINED IN TERMS OF EXACTLY ONE BACKUP: there is no restore without an
+// archive to restore, no archive is restored twice concurrently, and every
+// question anyone asks about a restore ("which dump was this?", "how big was
+// it?", "what migration was the schema on?") is answered by the backup's own
+// columns. A separate table would buy a join on a strict 1:1 relationship and
+// would let the two rows disagree about which archive was replayed.
+//
+// The cost is honest: a backup restored twice (a restore that failed, then
+// retried) overwrites the first attempt's audit fields. That is the correct
+// trade — the interesting record is the state of the LAST restore, and the
+// full history of attempts is in `audit_events`.
+//
+// `preRestoreBackupId` is a SELF-FK: before a restore swaps a database away,
+// #285 takes a `pre_restore` backup, and this column points the restore at the
+// safety net it took. `onDelete: SetNull`, so pruning that safety backup by
+// retention never deletes the restore record that referenced it.
+model DatabaseBackupRun {
+  id String @id @default(uuid()) @db.Uuid
+
+  // The `jobs` row that drove this run, once the dump became a queue job
+  // (`db.backup.run`, epic #345, issue #351). Three properties, each
+  // load-bearing:
+  //
+  //   1. `@unique` is what makes a SECOND run row for one job
+  //      UNREPRESENTABLE. #348 lets a handler derive its own node upload
+  //      key, and a node may legitimately ask for that key twice (a
+  //      timed-out transfer, a lost response, a restarted process still
+  //      holding the lease). The backup's `deriveOutputKey` re-reads by
+  //      `jobId` and returns the existing key; the unique index is what
+  //      GUARANTEES there is at most one to find, rather than that being a
+  //      convention the service has to remember.
+  //
+  //   2. Nullable, ON PURPOSE. Not every run has a job: the `pre_restore`
+  //      dump `DatabaseRestoreService` takes goes through the runner
+  //      directly, with no job in between, and rows predating this
+  //      migration have no job at all. A required column would either break
+  //      the restore path or need a backfill that invents job rows for
+  //      history.
+  //
+  //   3. `onDelete: SetNull`, NOT `Cascade`. `job.history.purge` deletes
+  //      `jobs` rows on a retention schedule that is completely independent
+  //      of the archive retention. Cascade would let a routine history purge
+  //      delete the record of a backup whose archive is still in the bucket
+  //      and still restorable — the exact "deleting history must not delete
+  //      history" hazard `JobStatsRollup` already exists to avoid on the
+  //      stats side. Losing the LINK is acceptable; losing the RUN ROW is
+  //      not.
+  jobId String? @unique @map("job_id") @db.Uuid
+  job   Job?    @relation(fields: [jobId], references: [id], onDelete: SetNull)
+
+  // `pending` = claimed, dump not yet spawned. `running` = a `pg_dump` is
+  // streaming. `completed` = uploaded AND verified (see `verifiedAt`).
+  // `failed` = terminal, `lastError` says why. `stale` = the run's heartbeat
+  // stopped for longer than `databaseBackup.runStaleMinutes` and #282's sweep
+  // gave up on it — DISTINCT from `failed` on purpose, because nothing
+  // observed this run fail; the process holding it disappeared, and an
+  // operator reading the list needs to be able to tell "the dump errored"
+  // from "the container went away mid-dump".
+  status DatabaseBackupStatus @default(pending)
+
+  // `manual` = an administrator clicked. `scheduled` = #282's cron.
+  // `pre_restore` = the safety backup #285 takes immediately before swapping
+  // a restored database into place. No default: a run with no known origin is
+  // a run nobody can attribute, and every caller knows which it is.
+  trigger DatabaseBackupTrigger
+
+  // NULL until the dump is claimed / until it settles. `lastHeartbeatAt` is
+  // now PROGRESS REPORTING for the UI rather than this table's liveness
+  // signal — the job's LEASE is the liveness signal since #351/#352 — see the
+  // "Why this WAS not a queue job, and why it now is" block above.
+  startedAt       DateTime? @map("started_at") @db.Timestamptz
+  finishedAt      DateTime? @map("finished_at") @db.Timestamptz
+  lastHeartbeatAt DateTime? @map("last_heartbeat_at") @db.Timestamptz
+
+  // BigInt, both of them, and NOT `Int`. A PostgreSQL dump crossing 2 GiB is
+  // ordinary, and `Int` is a signed 32-bit column that overflows at 2147483647
+  // bytes — the failure would be a write error on the LARGEST backups, i.e.
+  // exactly the deployments this feature exists for, and it would surface as
+  // a failed run rather than as a wrong number.
+  //
+  // ⚠ A `BigInt` field is the JS `bigint` primitive, which `JSON.stringify`
+  // REFUSES to serialise. #283's response DTO must convert these two to
+  // `string` (or `Number`) explicitly — see the note above `JobStatsRollup`
+  // for the same hazard, decided the other way there because that column is a
+  // running average and this one is a byte count that must stay exact.
+  //
+  // `bytesWritten` is LIVE PROGRESS, rewritten by the heartbeat while the dump
+  // streams; `sizeBytes` is the final size, written once at completion. They
+  // converge on success and deliberately do not on a failure, where the
+  // difference is "how far did it get".
+  bytesWritten BigInt @default(0) @map("bytes_written")
+  sizeBytes    BigInt @default(0) @map("size_bytes")
+
+  // The storage triple: WHICH provider, WHICH key, WHICH bucket. All three
+  // are recorded rather than derived on read, because all three can change
+  // under a deployment (a bucket rename, a provider swap) and a backup that
+  // cannot say where it was written is a backup nobody can restore. The key
+  // is chosen by the SERVER (`buildBackupStorageKey`), never by a caller.
+  storageProvider String @map("storage_provider")
+  storageKey      String @map("storage_key")
+  bucket          String
+
+  // `pg_dump`'s archive format — `custom` (`-Fc`) for everything this
+  // repository writes. Stored so a future format change does not make old
+  // archives unreadable-by-inspection: `pg_restore` needs to know, and
+  // guessing from the key's extension is not knowing.
+  format String
+
+  // sha256 of the archive, computed IN THE SAME SINGLE PASS as `sizeBytes`
+  // while the bytes stream past on their way to storage — the archive is
+  // never buffered and never read twice. NULL until the upload completes.
+  checksumSha256 String? @map("checksum_sha256")
+
+  // The audit quartet: what produced this archive. All four nullable because
+  // each is read best-effort and NONE of them may fail a backup — a run that
+  // could not read the server version is still a valid backup.
+  //
+  //   `dbVersion`     — the PostgreSQL server version this was dumped from.
+  //                     A restore onto an older major will not work, and this
+  //                     is the only place that fact is recorded.
+  //   `appVersion`    — the application build (`resolveApiVersion()`).
+  //   `migrationName` — the newest applied `_prisma_migrations` row. THE most
+  //                     important of the four for a restore: it says which
+  //                     schema the archive contains, so an operator can tell
+  //                     before replaying it whether the running code will
+  //                     understand what comes back.
+  //   `pgDumpVersion` — the `pg_dump` client that WROTE the archive (#352,
+  //                     epic #345). It was a trio until the dump could run on
+  //                     a worker node: on that path the client is a binary on
+  //                     a machine this deployment may not own and cannot
+  //                     inspect, so unless the node reports it, nothing
+  //                     anywhere records which `pg_dump` produced the file —
+  //                     and a `pg_restore` older than the `pg_dump` that wrote
+  //                     an archive simply cannot read it. The server path
+  //                     fills the same column from its own image's client, so
+  //                     the row means one thing whichever executor ran.
+  dbVersion     String? @map("db_version")
+  appVersion    String? @map("app_version")
+  migrationName String? @map("migration_name")
+  pgDumpVersion String? @map("pg_dump_version")
+
+  // Set when the UPLOADED OBJECT was streamed back out of storage and read by
+  // `pg_restore --list` with a non-empty table of contents. A run is never
+  // `completed` without it: the checksum proves what we sent, this proves what
+  // arrived is a readable archive.
+  verifiedAt DateTime? @map("verified_at") @db.Timestamptz
+
+  lastError String? @map("last_error")
+
+  // NULL for a `scheduled` run — nobody asked for it, a timer did. `SetNull`
+  // rather than `Cascade`, matching `AuditEvent.actorUserId` and
+  // `Credential.updatedByUser`: this is a HISTORY RECORD, and deleting an
+  // administrator's account must never delete the record that a backup was
+  // taken. Contrast `WorkerNode.createdBy`, which cascades because a node is
+  // live inventory rather than history.
+  createdById String? @map("created_by_id") @db.Uuid
+  createdBy   User?   @relation("UserDatabaseBackupRuns", fields: [createdById], references: [id], onDelete: SetNull)
+
+  // ---------------------------------------------------------------------------
+  // Restore audit (Phase 7). Declared by #281, written by #285's
+  // `DatabaseRestoreService`. See the "WHY THE RESTORE AUDIT LIVES ON THE
+  // BACKUP'S OWN ROW" block above.
+  // ---------------------------------------------------------------------------
+
+  // A plain string, not an enum, for the same reason `Job.executor` is one: a
+  // small closed set owned by code rather than by this table's own state
+  // machine, and adding a state to it must not cost a migration. NULL means
+  // "this backup has never been restored".
+  //
+  // `restoring` -> `verifying` -> `swapping` -> `completed` | `failed`, plus
+  // `rolled_back` for a restore that was swapped in and then undone. That last
+  // one is the argument for the column being a string: it was added by #285
+  // without a migration. The set lives in `RESTORE_STATUSES`
+  // (`src/db-backup/database-restore.service.ts`).
+  restoreStatus String? @map("restore_status")
+  restoreError  String? @map("restore_error")
+
+  restoredAt   DateTime? @map("restored_at") @db.Timestamptz
+  restoredById String?   @map("restored_by_id") @db.Uuid
+  restoredBy   User?     @relation("UserDatabaseRestores", fields: [restoredById], references: [id], onDelete: SetNull)
+
+  // The names of the two databases a swap-style restore creates and displaces:
+  // the scratch database the archive was replayed into, and the original that
+  // was renamed out of the way. Recorded as NAMES because after the swap they
+  // are the only handle an operator has on either — `databaseBackup
+  // .restoreRollbackMode` decides whether the displaced one survives, and
+  // `oldDatabaseRetentionHours` decides for how long.
+  restoreScratchDb String?   @map("restore_scratch_db")
+  restoreOldDb     String?   @map("restore_old_db")
+  swappedAt        DateTime? @map("swapped_at") @db.Timestamptz
+
+  // The `pre_restore` backup taken immediately before this row's archive was
+  // swapped in — the way back. `SetNull` so retention pruning that safety
+  // backup never deletes the restore record pointing at it.
+  preRestoreBackupId String?             @map("pre_restore_backup_id") @db.Uuid
+  preRestoreBackup   DatabaseBackupRun?  @relation("PreRestoreBackup", fields: [preRestoreBackupId], references: [id], onDelete: SetNull)
+  // The back-reference Prisma requires for the self-relation above. Nothing
+  // reads it today; it exists because a named relation needs both sides.
+  restoresUsingThis  DatabaseBackupRun[] @relation("PreRestoreBackup")
+
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  // The queries #282 and #283 issue, and nothing speculative:
+  //
+  //   - the admin list and the retention sweep are both "newest first", which
+  //     is `createdAt DESC`;
+  //   - `startedAt DESC` answers "when did backups actually run", which is a
+  //     different question from "when were they requested" for any run that
+  //     waited or never started at all;
+  //   - `[status]` backs the stale sweep (`status = 'running'`) and the
+  //     active-run lookup that turns a P2002 into an id;
+  //   - `[status, createdAt DESC]` is the retention query — "the completed
+  //     runs, newest first, keep N" — which neither single-column index
+  //     answers without a sort.
+  @@index([createdAt(sort: Desc)])
+  @@index([startedAt(sort: Desc)])
+  @@index([status])
+  @@index([status, createdAt(sort: Desc)])
+  @@map("database_backup_runs")
+}
+
+enum DatabaseBackupStatus {
+  pending
+  running
+  completed
+  failed
+  stale
+}
+
+enum DatabaseBackupTrigger {
+  manual
+  scheduled
+  pre_restore
+}