@@ -202,3 +202,60 @@ spec:
     kind: Postgres
     name: orders-db
 ```
+
+## Point-in-time recovery (PostgreSQL)
+
+A `RestoreJob` restores a `Postgres` application from a `Backup`. Omit `spec.options.recoveryTime` to recover to the latest point in the WAL archive; set it (RFC3339) to recover the database to an exact instant — a point-in-time recovery (PITR). Under the hood the CNPG barman-cloud plugin restores the newest base backup taken at/before that instant and replays archived WAL up to it, so the restored cluster reflects the database exactly as of `recoveryTime`; later writes are absent.
+
+```yaml
+apiVersion: backups.cozystack.io/v1alpha1
+kind: RestoreJob
+metadata:
+  name: orders-db-pitr
+  namespace: tenant-acme
+spec:
+  backupRef:
+    name: orders-db-adhoc            # a completed Backup of the source
+  targetApplicationRef:              # omit for a destructive in-place restore
+    apiGroup: apps.cozystack.io
+    kind: Postgres
+    name: orders-db-copy             # a pre-deployed, empty Postgres app
+  options:
+    recoveryTime: "2026-07-21T09:30:00Z"
+```
+
+A full, scripted example (write a marker, capture the timestamp, restore to it, assert what survived) is in [`examples/backups/postgres/`](../../examples/backups/postgres/) — `45-restorejob-pitr.yaml`, driven by `run-all.sh`.
+
+### The recoverable window
+
+`recoveryTime` must fall inside the window the archive can reconstruct:
+
+- **Earliest** — the completion of the oldest base backup still in the archive. You cannot recover to an instant before the first base backup: WAL replay always starts from a base backup, and retention (`barmanObjectStore.retentionPolicy`) eventually trims the oldest ones together with the WAL that predates them.
+- **Latest** — the timestamp of the most recent WAL segment shipped to object storage. While the source runs with `backup.enabled: true` it archives continuously, so the latest restorable time trails "now" only by the archive lag (seconds for a healthy cluster). Once the source is deleted, the latest restorable time is frozen at whatever WAL made it to S3 before it went away.
+
+A `recoveryTime` **past the latest archived WAL cannot converge**: PostgreSQL replays every available WAL, never reaches the target, exits with `FATAL: recovery ended before configured recovery target was reached`, and CNPG re-creates the recovery instance in a loop. Such a wedged restore is failed by the restore deadline (`spec.options.restoreTimeoutSeconds`, default 30m) — and the driver reads the recovery pod's log at that point, so instead of a generic timeout the RestoreJob ends `status.phase: Failed` with conditions `RecoveryConverged=False` and `Ready=False`, both reason `RecoveryTargetUnreachable`, and a message naming the target. The driver deliberately does **not** fail earlier off that FATAL: a *reachable* near-now target hits the identical FATAL transiently — often repeatedly, on a slow archiver — before it converges, so an earlier trip would reject a recoverable restore. To reject an unreachable target quickly, set a short `restoreTimeoutSeconds`; otherwise widen the window (take a fresh backup, or restore closer to now) or pick a time inside it.
+
+Restoring to a **very recent** instant is safe as long as WAL archiving is current: the segment covering the target may not be in object storage yet and the same FATAL fires transiently, but because the driver only fails at the deadline (not on that FATAL), the recovery has the whole window to catch up — the next attempt promotes once the WAL ships and the cluster goes healthy, which completes the restore. Only a target that never becomes reachable within the deadline is failed. If archiving is badly behind (a stalled `archive_command`, an overloaded cluster) a near-now target can exceed even the default 30m window; restore to a point you can confirm is archived (e.g. at/before the most recent completed backup, per the discovery query below).
+
+A `recoveryTime` **before the earliest base backup** fails differently: PostgreSQL cannot begin replay before the base backup it restored, so recovery never reaches a consistent state and never emits the "recovery ended before …" FATAL the driver classifies on. That case also surfaces at the deadline, but with the generic reason `RestoreFailed` rather than `RecoveryTargetUnreachable`. Choosing a `recoveryTime` at/after the oldest base backup's completion (below) avoids it.
+
+### Discovering the earliest / latest restorable time
+
+CNPG's `Cluster.status.firstRecoverabilityPoint` exists in the status schema but is unreliable under the barman-cloud plugin — it was observed empty on every plugin-backed cluster on the dev7 test cluster (CNPG 1.28.1) — so read the window from the backup catalog instead. Each completed base backup records its WAL range and timestamps on the underlying `cnpg.io/Backup`:
+
+```bash
+# Completed base backups, oldest first: STOP is the earliest instant that
+# backup alone can restore to; the oldest STOP is the window's lower bound.
+kubectl -n <ns> get backups.postgresql.cnpg.io \
+  --sort-by=.status.stoppedAt \
+  -o custom-columns=NAME:.metadata.name,PHASE:.status.phase,START:.status.startedAt,STOP:.status.stoppedAt,BEGINWAL:.status.beginWal,ENDWAL:.status.endWal
+
+# The cozystack Backup points at its underlying cnpg.io/Backup and S3 prefix.
+kubectl -n <ns> get backup.backups.cozystack.io <name> -o jsonpath='{.spec.driverMetadata}'
+```
+
+The upper bound — the latest archived WAL — is whatever the source has shipped so far; with archiving healthy, any time up to a few seconds ago is safe. To confirm the archive is current, check that the source cluster's WAL is flowing to S3 (the `barman-cloud` sidecar logs an upload per segment) before restoring to a near-now target.
+
+### Idempotency under GitOps
+
+An in-progress restore is safe to reconcile. The driver purges the target `Cluster` + PVCs exactly once per RestoreJob (guarded by the `TargetPurged` condition and a freshly-recovered check), suspends the target's HelmRelease across the purge so Flux cannot race the bootstrap swap, and resumes it once the recovery cluster is rendered. A Flux reconcile (or a controller restart) mid-restore therefore re-attaches to the recovering cluster rather than deleting it and starting over.
@@ -24,7 +24,13 @@ export PG_TARGET_CLUSTER="postgres-${PG_TARGET_NAME}"
 export STRATEGY_NAME="${STRATEGY_NAME:-cnpg-strategy-default}"
 export BACKUPCLASS_NAME="${BACKUPCLASS_NAME:-postgres-cnpg}"
 export BACKUPJOB_NAME="${BACKUPJOB_NAME:-pg-src-adhoc}"
+# A second ad-hoc BackupJob taken after the PITR marker writes; its completion
+# is the deterministic "WAL past the recovery target is archived" gate for the
+# point-in-time restore (see run-all.sh step 45).
+export BACKUPJOB_POSTMARKER_NAME="${BACKUPJOB_POSTMARKER_NAME:-pg-src-postmarker}"
 export RESTOREJOB_TOCOPY_NAME="${RESTOREJOB_TOCOPY_NAME:-pg-src-to-pg-target}"
+export RESTOREJOB_PITR_NAME="${RESTOREJOB_PITR_NAME:-pg-src-to-pg-target-pitr}"
+export RESTOREJOB_UNREACHABLE_NAME="${RESTOREJOB_UNREACHABLE_NAME:-pg-src-to-pg-target-unreachable}"
 export PLAN_NAME="${PLAN_NAME:-pg-src-daily}"
 # App user password baked into 05-postgres-src.yaml (REPLACE_WITH_PASSWORD).
 export PG_PASSWORD="${PG_PASSWORD:-Xai7Wepo0aeThie8}"
 
@@ -2,7 +2,12 @@
 # back into pg-src. WARNING: deletes the live cnpg.io Cluster and its PVCs
 # before re-bootstrapping from S3 - any data not yet streamed to WAL is lost.
 #
-# Optional: spec.options.recoveryTime (RFC3339) for point-in-time recovery.
+# Optional: spec.options.recoveryTime (RFC3339) turns this into a point-in-time
+# recovery, same as the to-copy variant in 45-restorejob-pitr.yaml (which the
+# e2e drives with a real, in-window timestamp). Uncomment and set a timestamp
+# inside your recoverable window - see 45-restorejob-pitr.yaml and
+# docs/operations/backup-classes.md ("Point-in-time recovery") for how to find
+# the earliest/latest restorable time.
 ---
 apiVersion: backups.cozystack.io/v1alpha1
 kind: RestoreJob
 
@@ -0,0 +1,34 @@
+# Point-in-time recovery (PITR) to a copy.
+#
+# Restores the source's Barman archive into pg-target as of a specific instant
+# via spec.options.recoveryTime (RFC3339). The chart maps it onto CNPG's
+# bootstrap.recovery.recoveryTarget.targetTime: PostgreSQL restores the newest
+# base backup taken at/before that instant and replays archived WAL up to it,
+# so the copy reflects the database exactly as of recoveryTime - later writes
+# are absent.
+#
+# recoveryTime MUST fall inside the recoverable window: at/after the base
+# backup's completion and at/before the latest WAL shipped to object storage.
+# A target past the latest archived WAL cannot converge - the RestoreJob fails
+# with condition Ready=False/RecoveryTargetUnreachable instead of hanging. See
+# docs/operations/backup-classes.md ("Point-in-time recovery") for how to
+# discover the earliest/latest restorable time.
+#
+# run-all.sh substitutes REPLACE_WITH_RECOVERY_TIME with a timestamp it captures
+# between two marker writes, then asserts the pre-marker row is present and the
+# post-marker row is absent. Editing by hand, replace it with an RFC3339
+# timestamp inside your window, e.g. "2026-05-01T12:00:00Z".
+---
+apiVersion: backups.cozystack.io/v1alpha1
+kind: RestoreJob
+metadata:
+  name: pg-src-to-pg-target-pitr
+spec:
+  backupRef:
+    name: pg-src-adhoc
+  targetApplicationRef:
+    apiGroup: apps.cozystack.io
+    kind: Postgres
+    name: pg-target
+  options:
+    recoveryTime: "REPLACE_WITH_RECOVERY_TIME"
@@ -14,6 +14,7 @@ The numbered manifests are the documented flow; a human can read and apply them
 - `25-backupjob-adhoc.yaml` — an ad-hoc `BackupJob`.
 - `30-postgres-target.yaml` + `40-restorejob-to-copy.yaml` — restore into a fresh copy, leaving the source running.
 - `35-restorejob-in-place.yaml` — the destructive in-place restore variant.
+- `45-restorejob-pitr.yaml` — point-in-time recovery: restore into the copy as of a specific `spec.options.recoveryTime` (RFC3339).
 
 ## Placeholders and derived Secrets
 
@@ -30,7 +31,7 @@ NAMESPACE=tenant-root examples/backups/postgres/run-all.sh
 NAMESPACE=tenant-root examples/backups/postgres/cleanup.sh
 ```
 
-`run-all.sh` writes a sentinel row into the source, waits for the `BackupJob` to reach `Succeeded`, restores to a copy, and asserts the sentinel round-tripped through S3 into the restored copy. Set `SKIP_RESTORE=1` to stop after a successful backup.
+`run-all.sh` writes a sentinel row into the source, waits for the `BackupJob` to reach `Succeeded`, restores to a copy, and asserts the sentinel round-tripped through S3 into the restored copy. It then runs a **point-in-time recovery**: it writes a `before` marker, captures the server timestamp, writes an `after` marker, and restores the copy to that timestamp (`45-restorejob-pitr.yaml`), asserting the `before` row survived and the `after` row did not. Finally it submits a RestoreJob with a `recoveryTime` an hour in the future and asserts it **fails fast** with `status.phase: Failed` and reason `RecoveryTargetUnreachable` (rather than hanging to the restore deadline). Set `SKIP_RESTORE=1` to stop after a successful backup, or `SKIP_PITR=1` to stop after the latest-point restore.
 
 ## Automated e2e
 
 
@@ -20,12 +20,14 @@ for app in "$PG_SRC_NAME" "$PG_TARGET_NAME"; do
     fi
 done
 
-log_substep "Deleting RestoreJob..."
-kubectl -n "$NAMESPACE" delete restorejob.backups.cozystack.io "$RESTOREJOB_TOCOPY_NAME" --ignore-not-found
+log_substep "Deleting RestoreJobs..."
+kubectl -n "$NAMESPACE" delete restorejob.backups.cozystack.io \
+    "$RESTOREJOB_TOCOPY_NAME" "$RESTOREJOB_PITR_NAME" "$RESTOREJOB_UNREACHABLE_NAME" --ignore-not-found
 
 log_substep "Deleting Plan + BackupJob + derived Backup artefacts..."
 kubectl -n "$NAMESPACE" delete plan.backups.cozystack.io "$PLAN_NAME" --ignore-not-found
-kubectl -n "$NAMESPACE" delete backupjob.backups.cozystack.io "$BACKUPJOB_NAME" --ignore-not-found
+kubectl -n "$NAMESPACE" delete backupjob.backups.cozystack.io \
+    "$BACKUPJOB_NAME" "$BACKUPJOB_POSTMARKER_NAME" --ignore-not-found
 # Only the Backups of THIS demo's apps — never `--all`: on a shared cluster the
 # namespace can hold Backup artefacts of other applications and flows.
 for b in $(kubectl -n "$NAMESPACE" get backups.backups.cozystack.io \