spec-6.5: cluster-aware backup / restore / PITR substrate

docs/reference/system-views.md

@@ -1,14 +1,113 @@
 # System views
 
-linkdb adds three cluster-aware system views to the standard
-PostgreSQL catalog.  All three are present in `--enable-cluster`
-builds; in `--disable-cluster` builds they return zero rows.
+linkdb adds cluster-aware system views to the standard PostgreSQL
+catalog.  These views are present in `--enable-cluster` builds; in
+`--disable-cluster` builds the backing functions are unavailable or
+return zero rows, depending on whether the function is read-only or
+operator-facing.
 
 | View | Purpose |
 |---|---|
 | `pg_cluster_nodes` | Cluster topology (the parsed `pgrac.conf`) |
 | `pg_stat_cluster_wait_events` | Cluster-specific wait events on the local node |
 | `pg_stat_gcluster_wait_events` | Cluster wait events globally (cross-node placeholder) |
+| `pg_stat_cluster_backup` | Current cluster backup state on the local node |
+| `pg_cluster_backup_history` | Latest cluster backup manifest summary |
+| `pg_cluster_restore_points` | Cluster restore points visible to PITR status |
+| `pg_cluster_pitr_status` | Cluster PITR target reachability status |
+
+## Cluster Backup / PITR Views
+
+The cluster backup surface exposes the manifest and target-resolution
+state used by `pg_cluster_backup_start`, `pg_cluster_backup_stop`, and
+`pg_cluster_create_restore_point`.
+
+Current 6.5 scope is conservative:
+
+- The views, catalog entries, manifest validators, PITR target resolver,
+  shared-memory state, and IC wire format are present as substrate.
+- Mutating physical backup and restore-point entry points fail closed
+  with `feature_not_supported` until the cluster physical capture,
+  durable WAL pin, restore-point commit-drain barrier, restore, and PITR
+  replay paths are implemented.
+- No manifest is published unless WAL, undo, transaction-table, SCN, and
+  control-file inclusion are proven.  The current substrate therefore
+  refuses to create a manifest instead of reporting a partial or unsound
+  backup as complete.
+
+### `pg_stat_cluster_backup`
+
+One row describing the current or most recent cluster backup on this
+node.
+
+| Column | Type | Description |
+|---|---|---|
+| `in_progress` | `bool` | True while this session has an active cluster backup. |
+| `backup_id` | `text` | Backup label/id, or NULL before the first backup. |
+| `coordinator_node_id` | `int4` | Local node id that started the backup. |
+| `start_redo_lsn` | `pg_lsn` | Checkpoint redo LSN used as the backup start contract. |
+| `checkpoint_lsn` | `pg_lsn` | Checkpoint record LSN captured at backup start. |
+| `stop_cut_lsn` | `pg_lsn` | WAL cut LSN captured at backup stop. |
+| `consistent_scn` | `int8` | Cluster SCN selected for the backup cut. |
+| `manifest_crc` | `int8` | CRC32C of the latest manifest image. |
+| `started_at` | `timestamptz` | Local timestamp when the backup started. |
+| `stopped_at` | `timestamptz` | Local timestamp when the backup stopped. |
+| `backup_parallel_channels` | `int4` | Configured copy-channel capacity for the backup substrate. |
+| `backup_wal_retention` | `int4` | Configured WAL retention hint, in MB. |
+| `restore_points_enabled` | `bool` | Whether automatic PITR restore-point scheduling is enabled. |
+| `restore_point_interval_ms` | `int4` | Automatic restore-point scheduling interval, in milliseconds. |
+
+### `pg_cluster_backup_history`
+
+Returns the latest cluster backup manifest summary retained in shared
+memory.
+
+| Column | Type | Description |
+|---|---|---|
+| `backup_id` | `text` | Backup label/id. |
+| `consistent_scn` | `int8` | SCN that defines the backup cut. |
+| `scn_durable_peak` | `int8` | Highest durable SCN covered by the cut. |
+| `timeline` | `int4` | WAL timeline recorded at backup stop. |
+| `catversion` | `int8` | Catalog version used to reject incompatible restores. |
+| `storage_id` | `int4` | Cluster shared-storage backend id. |
+| `node_count` | `int4` | Number of nodes proven in the manifest. |
+| `thread_count` | `int4` | Number of WAL threads proven in the manifest. |
+| `manifest_crc` | `int8` | CRC32C of the manifest image. |
+
+### `pg_cluster_restore_points`
+
+Shows restore points created by the cluster-aware restore-point entry
+point.
+
+| Column | Type | Description |
+|---|---|---|
+| `restore_point_name` | `text` | Restore point name. |
+| `cut_scn` | `int8` | SCN selected for the restore point cut. |
+| `thread_count` | `int4` | WAL threads covered by the cut. |
+| `incarnation` | `int4` | Cluster incarnation recorded with the cut. |
+| `created_at` | `timestamptz` | Local timestamp when the point was recorded. |
+
+### `pg_cluster_pitr_status`
+
+Resolves the configured cluster PITR target against known restore
+points and the latest manifest.
+
+| Column | Type | Description |
+|---|---|---|
+| `target_type` | `text` | `latest` when no target is configured, `scn`, `name`, or `cluster_time`. |
+| `target_action` | `text` | Configured PITR action: `pause`, `promote`, or `shutdown`. |
+| `reachable` | `bool` | True if the configured target is reachable. |
+| `reason` | `text` | `ok` or the fail-closed reason. |
+| `resolved_scn` | `int8` | Restore-point SCN selected for the target, when reachable. |
+| `restore_point_name` | `text` | Restore point used for the target, when reachable. |
+
+Mutating function execution is revoked from PUBLIC:
+
+```sql
+SELECT * FROM pg_cluster_backup_start('b1', true);
+SELECT * FROM pg_cluster_backup_stop(true);
+SELECT * FROM pg_cluster_create_restore_point('rp1');
+```
 
 ## pg_cluster_nodes
 

docs/user-guide/configuration.md

@@ -3,7 +3,7 @@
 linkdb uses two configuration mechanisms layered on top of standard
 PostgreSQL configuration:
 
-1. **`postgresql.conf`** — standard PG config plus the `cluster.*`
+1. **`postgresql.conf`** — standard PG config plus `cluster.*`
    GUCs added by linkdb's cluster subsystem.
 2. **`pgrac.conf`** — INI-style file describing the cluster
    topology (the list of nodes that participate in the cluster).
@@ -62,6 +62,31 @@ an absolute path), `$PGDATA/pg_wal` must resolve to
 cluster.wal_threads_dir = '/shared/walroot'
 ```
 
+### Cluster backup / PITR GUCs
+
+These settings support the cluster-aware physical backup / restore /
+PITR surface.
+
+| GUC | Type | Default | Context | Notes |
+|---|---|---|---|---|
+| `cluster.recovery_target_scn` | string | `''` | postmaster | Target SCN used by `pg_cluster_pitr_status`. Empty means latest unless a name or cluster-time target is set. |
+| `cluster.recovery_target_cluster_time` | string | `''` | postmaster | Timestamp target reported by `pg_cluster_pitr_status`; current 6.5 recovery action remains fail-closed for this target type. |
+| `cluster.recovery_target_name` | string | `''` | postmaster | Named restore-point target resolved by `pg_cluster_pitr_status`. |
+| `cluster.recovery_target_action` | enum | `pause` | postmaster | Accepted values: `pause`, `promote`, `shutdown`; exposed in PITR status. |
+| `cluster.enable_pitr_restore_points` | bool | `off` | sighup | Enables future automatic restore-point scheduling. Manual `pg_cluster_create_restore_point()` is independent. |
+| `cluster.pitr_restore_point_interval_ms` | integer | `0` | sighup | Zero disables automatic scheduling. |
+| `cluster.backup_wal_retention` | integer | `0` MB | sighup | Retention hint for the future backup-set writer. |
+| `cluster.backup_parallel_channels` | integer | `1` | sighup | Reserved copy-channel capacity for the future backup-set writer. |
+| `cluster.backup_manifest_checksums` | enum | `crc32c` | sighup | Manifest checksums are mandatory; unchecked manifests are not supported. |
+
+The current implementation is intentionally conservative.  These GUCs
+expose the 6.5 catalog and state surface, but mutating cluster physical
+backup and restore-point entry points fail closed with
+`feature_not_supported` until the physical capture, durable WAL pin,
+commit-drain restore-point barrier, restore, and PITR replay paths are
+implemented.  The server refuses to publish a manifest or restore point
+when those proofs are absent.
+
 ### `cluster.interconnect_tier`
 
 | | |

src/backend/catalog/system_views.sql

@@ -1685,6 +1685,71 @@ GRANT SELECT ON pg_cluster_node_removal_state TO PUBLIC;
 -- REVOKE EXECUTE FROM PUBLIC for defense-in-depth (L7).
 REVOKE ALL ON FUNCTION pg_cluster_remove_node(int) FROM PUBLIC;
 
+-- PGRAC: cluster-aware backup / restore / PITR surface (spec-6.5).
+--   The state/history/restore-point/PITR views are read-only observability.
+--   Mutating entry points are superuser-gated in C and revoked from PUBLIC.
+CREATE VIEW pg_stat_cluster_backup AS
+    SELECT in_progress,
+           backup_id,
+           coordinator_node_id,
+           start_redo_lsn,
+           checkpoint_lsn,
+           stop_cut_lsn,
+           consistent_scn,
+           manifest_crc,
+           started_at,
+           stopped_at,
+           backup_parallel_channels,
+           backup_wal_retention,
+           restore_points_enabled,
+           restore_point_interval_ms
+      FROM cluster_get_backup_state();
+
+REVOKE ALL ON pg_stat_cluster_backup FROM PUBLIC;
+GRANT SELECT ON pg_stat_cluster_backup TO PUBLIC;
+
+CREATE VIEW pg_cluster_backup_history AS
+    SELECT backup_id,
+           consistent_scn,
+           scn_durable_peak,
+           timeline,
+           catversion,
+           storage_id,
+           node_count,
+           thread_count,
+           manifest_crc
+      FROM cluster_get_backup_history();
+
+REVOKE ALL ON pg_cluster_backup_history FROM PUBLIC;
+GRANT SELECT ON pg_cluster_backup_history TO PUBLIC;
+
+CREATE VIEW pg_cluster_restore_points AS
+    SELECT restore_point_name,
+           cut_scn,
+           thread_count,
+           incarnation,
+           created_at
+      FROM cluster_get_restore_points();
+
+REVOKE ALL ON pg_cluster_restore_points FROM PUBLIC;
+GRANT SELECT ON pg_cluster_restore_points TO PUBLIC;
+
+CREATE VIEW pg_cluster_pitr_status AS
+    SELECT target_type,
+           target_action,
+           reachable,
+           reason,
+           resolved_scn,
+           restore_point_name
+      FROM cluster_get_pitr_status();
+
+REVOKE ALL ON pg_cluster_pitr_status FROM PUBLIC;
+GRANT SELECT ON pg_cluster_pitr_status TO PUBLIC;
+
+REVOKE ALL ON FUNCTION pg_cluster_backup_start(text, bool) FROM PUBLIC;
+REVOKE ALL ON FUNCTION pg_cluster_backup_stop(bool) FROM PUBLIC;
+REVOKE ALL ON FUNCTION pg_cluster_create_restore_point(text) FROM PUBLIC;
+
 -- PGRAC: pg_cluster_ic_msg_types (spec-2.3 D8; 2026-05-08).
 --   Lists every IC message type registered in the process-local
 --   dispatch_table[] under cluster_ic_router.c.  Diagnostic /

src/backend/cluster/Makefile

@@ -41,6 +41,8 @@ OBJS = \
 	cluster.o \
 	cluster_advisory.o \
 	cluster_cancel_token.o \
+	cluster_backup.o \
+	cluster_backup_manifest.o \
 	cluster_cf_authority.o \
 	cluster_cf_enqueue.o \
 	cluster_cf_phase2.o \
@@ -208,7 +210,8 @@ else
 OBJS = cluster_conf.o cluster_debug.o cluster_ic.o cluster_inject.o cluster_undo_srf.o \
 	cluster_cr_srf.o cluster_block_apply_srf.o cluster_block_recovery_srf.o cluster_thread_recovery_apply_srf.o cluster_thread_recovery_replay_srf.o cluster_thread_recovery_driver_srf.o cluster_thread_recovery_orchestrator_srf.o cluster_pgstat.o cluster_scn.o cluster_views.o cluster_ges_mode_backend.o \
 	cluster_ir_srf.o cluster_ts_srf.o cluster_ko_srf.o \
-	cluster_hang_resolve.o cluster_clean_leave_views.o cluster_node_remove_views.o
+	cluster_hang_resolve.o cluster_clean_leave_views.o cluster_node_remove_views.o \
+	cluster_backup.o cluster_backup_manifest.o
 # spec-5.12: cluster_hang_resolve.o provides the pg_cluster_hang_victims /
 # pg_cluster_hang_resolve SQL symbols (real bodies #ifdef USE_PGRAC_CLUSTER,
 # --disable-cluster stubs raise ERRCODE_FEATURE_NOT_SUPPORTED); the symbols
@@ -217,6 +220,8 @@ OBJS = cluster_conf.o cluster_debug.o cluster_ic.o cluster_inject.o cluster_undo
 # SRF + pg_cluster_clean_leave_request UDF symbols, same unconditional-link reason.
 # spec-5.18: cluster_node_remove_views.o provides cluster_get_node_removal_state +
 # pg_cluster_remove_node, same unconditional-link reason.
+# spec-6.5: cluster_backup.o provides the cluster-aware backup/restore/PITR
+# SQL symbols; --disable-cluster bodies raise ERRCODE_FEATURE_NOT_SUPPORTED.
 endif
 
 include $(top_srcdir)/src/backend/common.mk