Home Mac app guides PITR Recovery GUI

PITR Recovery GUI

Last updated on Jul 12, 2026

Purpose

PITR Recovery helps users prepare point-in-time document load requests, inspect available current-vs-recovered diff output, and prepare guarded restore workflows. Approved live PITR-enabled Firebase proof remains required before live historical reads or restores are treated as complete.

Flow

  1. Select a project and Firestore database.
  2. Enter a document path.
  3. Enter a whole-minute recovery timestamp.
  4. Build current and historical read requests; use approved live evidence before treating historical results as production-proven.
  5. Review field diff, JSON, and logs.
  6. Restore the historical document version only after explicit confirmation.

Outputs

  • TABLE: field-level diff and recovery summary
  • JSON: current document JSON, recovered/stubbed payloads when available, and request details
  • LOGS: REST read/write, validation, and task logs

Validation

  • Document path is required.
  • Recovery timestamp must be valid RFC 3339, whole-minute aligned with seconds set to 00, not in the future, and inside the configured recovery window.
  • Restore requires an available recovered snapshot from approved live evidence or a fixture-backed/stubbed recovery payload.

Current local validation evidence covers timestamp parsing, whole-minute rejection, future-time rejection, and configurable recovery-window bounds. Local recovery guard evidence covers recovered-field PATCH construction, read-only rejection before task enqueue, missing-recovered-document rejection, and production typed confirmation before task enqueue. Historical reads and restores still require approved live PITR-enabled Firebase verification before they should be treated as production-proven.

Use the module for incident response prep when a single Firestore document needs careful review before restoration. The operator should select the Firebase project, Firestore database, document path, and historical timestamp, then compare the current data against the recovered snapshot when an approved live or fixture-backed snapshot is available before approving any write. That keeps recovery evidence visible instead of hiding it inside an external script.

The table and JSON outputs are useful for different review styles. Table output summarizes changed fields, missing fields, and restored values, while JSON output keeps the raw document payload available for copying into a ticket or runbook. Logs should capture request timing, selected target details, PITR API errors, and restore validation failures.

Safety

  • Restore is a Firestore write and is blocked for read-only projects.
  • Production restore requires explicit RECOVER <project-id> confirmation.
  • Restore should run through the task queue.
  • The diff should make changed, added, removed, and unchanged fields clear before confirmation.

Current Verification

  • FirestorePITRServiceTests/testValidateReadTimeAcceptsWholeMinuteWithinRecoveryWindow, testValidateReadTimeRejectsNonWholeMinuteTimestamps, testValidateReadTimeRejectsFutureAndOlderThanSevenDays, and testValidateReadTimeUsesConfiguredRecoveryWindow prove timestamp guardrails.
  • FirestorePITRServiceTests/testRecoverDocumentPatchesRecoveredFieldsWithLiveAuthorization proves the recovery PATCH body uses recovered fields, with stubbed transport only.
  • PITRRecoveryGuardTests/testReadOnlyProjectRejectsPITRRecoveryBeforeQueueingTask, testProductionPITRRecoveryRequiresTypedConfirmationBeforeQueueingTask, and testMissingRecoveredDocumentRejectsPITRRecoveryBeforeQueueingTask prove app-level recovery guardrails before task enqueue.
  • Approved live PITR-enabled Firebase proof remains required before live historical read or restore behavior is claimed.

Source Anchors

  • Sources/FirestructApp/Features/PITR/UI/PITRRecoveryView.swift
  • Sources/FirestructApp/Features/PITR/Services/AppModel+PITRActions.swift
  • Sources/FirestructApp/Features/PITR/Model/PITRStore.swift
  • Sources/FirestructCore/FirestorePITRService.swift