Repository navigation
feat(recovery): bind caller-owned physical/WAL/PITR profiles #217
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| # ADR 0019: Bind a caller-owned physical/WAL/PITR recovery profile | ||
|
|
||
| - **Status:** Accepted for the bounded physical/PITR profile seam | ||
| - **Date:** 2026-08-16 | ||
|
|
||
| ## Context | ||
|
|
||
| Protected main already records content-free logical-recovery receipts and | ||
| artifact/schema integrity evidence. Issue #204 still requires a separately | ||
| reviewed physical/WAL/PITR profile. A buyer who can dump and restore SQL still | ||
| cannot state, in machine-readable form, whether recovery is crash-consistent | ||
| only or can follow time. | ||
|
|
||
| PostgreSQL continuous archiving uses a base backup plus a WAL archive and a | ||
| recovery target (`immediate`, time, transaction identifier, named restore | ||
| point, or LSN). Those choices are deployer-owned. The package must not execute | ||
| `pg_basebackup`, invent an RPO/RTO, or treat a physical base backup as a | ||
| point-in-time restore. | ||
|
|
||
| ## Decision | ||
|
|
||
| `bind_postgres_physical_recovery_profile()` records one caller-owned profile: | ||
|
|
||
| - `backup_method` is exactly `physical` or `pitr`. | ||
| - `recovery_target_kind` is exactly `immediate`, `time`, `xid`, `name`, or `lsn`. | ||
| - Point-in-time kinds require `backup_method="pitr"`. | ||
| - `pitr` requires `wal_archive_required=True`. | ||
| - `isolated_target_prepared` must be the exact boolean `True`. | ||
| - Optional `rpo_seconds` and `rto_seconds` are deployer-selected objectives. | ||
| - Emitted evidence always sets `package_capability_claim` to `False`. | ||
|
|
||
| The seam does not receive archive paths, DSNs, WAL locations, or restore | ||
| commands, and it does not start PostgreSQL tools. | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| A[Caller asserts isolated target] --> B{Method} | ||
| B -->|physical| C[immediate target only] | ||
| B -->|pitr| D[WAL archive required] | ||
| D --> E[time / xid / name / lsn / immediate] | ||
| C --> F[Profile JSON with capability_claim false] | ||
| E --> F | ||
| F --> G[Operator runs pg_basebackup / restore_command outside this package] | ||
| ``` | ||
|
|
||
| ## Consequences | ||
|
|
||
| Hosts can persist a reviewed physical/PITR contract next to #205 receipts | ||
| without claiming that this package completed backup, restore, CSAP, or SOC 2. | ||
| Logical restore (#208/#212) remains a separate executor. Live WAL replay and | ||
| base-backup execution remain later #204 slices. | ||
|
|
||
| ## Rollback | ||
|
|
||
| Delete the profile module, tests, and this decision record. No schema | ||
| migration is required. | ||
|
|
||
| ## References | ||
|
|
||
| Swanson, M., Bowen, P., Phillips, A., Gallup, D., & Lynes, D. (2010). | ||
| *Contingency planning guide for federal information systems* (NIST Special | ||
| Publication 800-34 Rev. 1). National Institute of Standards and Technology. | ||
| https://doi.org/10.6028/NIST.SP.800-34r1 | ||
|
|
||
| The PostgreSQL Global Development Group. (2026). *Continuous archiving and | ||
| point-in-time recovery (PITR)*. PostgreSQL 18 documentation. | ||
| https://www.postgresql.org/docs/18/continuous-archiving.html | ||
|
|
||
| The PostgreSQL Global Development Group. (2026). *pg_basebackup*. PostgreSQL 18 | ||
| documentation. https://www.postgresql.org/docs/18/app-pgbasebackup.html |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| # PostgreSQL physical and PITR recovery profile | ||
|
|
||
| This record is the operator contract for | ||
| `bind_postgres_physical_recovery_profile()`. Use it before you claim that a | ||
| deployment can recover through WAL replay. The function binds evidence. It does | ||
| not run `pg_basebackup`, `restore_command`, or `pg_restore`. | ||
|
|
||
| ## What to do next | ||
|
|
||
| 1. Create an isolated recovery target first. Pass | ||
| `isolated_target_prepared=True` only after that target exists. The boolean | ||
| is your assertion, not package proof of isolation. | ||
| 2. Choose `backup_method="physical"` only for a crash-consistent base backup | ||
| whose recovery target kind is `immediate`. | ||
| 3. Choose `backup_method="pitr"` only when a WAL archive is already being | ||
| written and you can restore to a time, transaction identifier, named restore | ||
| point, LSN, or immediate consistent state. | ||
| 4. Record deployer-selected `rpo_seconds` and `rto_seconds` when your | ||
| organization has those objectives. Read `package_capability_claim=false` as | ||
| a hard rule: this package did not meet those numbers for you. | ||
| 5. Keep Fernet keys, TLS private material, host configuration, and provider | ||
| files outside database and WAL custody unless a separately reviewed adapter | ||
| owns them. | ||
| 6. After you bind the profile, run the actual base backup and WAL restore | ||
| outside this seam, then prove schema, tenant/RLS, checkpoint, and lifecycle | ||
| usability on the isolated target. | ||
|
|
||
| ## Time-flow boundary | ||
|
|
||
| PostgreSQL point-in-time recovery is a time-flow control. Kinds `time`, | ||
| `xid`, `name`, and `lsn` are accepted only on a `pitr` profile with | ||
| `wal_archive_required=True`. A physical profile cannot borrow those kinds even | ||
| when WAL is being archived. That prevents labeling a crash-consistent restore | ||
| as a point-in-time restore. | ||
|
|
||
| ## What this slice does not prove | ||
|
|
||
| This binder does not execute physical backup, WAL archive, or replay. It does | ||
| not prove schema/RLS/constraint/extension parity, target isolation, universal | ||
| RPO/RTO, high availability, disaster recovery, CSAP, or SOC 2 readiness. Those | ||
| remain issue #204 and deployment-specific evidence. Canonical CHANGELOG and | ||
| README ownership for the broader recovery program stays with the documentation | ||
| and restore-executor writers. | ||
|
|
||
| ## Verification | ||
|
|
||
| Confirm on the exact current head that: | ||
|
|
||
| - a PostgreSQL 18 `pitr` + `time` profile round-trips without a capability claim; | ||
| - `pitr` without a WAL archive fails closed; | ||
| - point-in-time kinds on a `physical` method fail closed; | ||
| - `isolated_target_prepared=False` fails closed; | ||
| - exact-type and hostile-subclass metadata fail closed; | ||
| - parse rejects duplicate keys, unknown keys, and a true capability claim; | ||
| - production statement and branch coverage and public docstrings remain 100%. | ||
|
|
||
| ## References | ||
|
|
||
| International Organization for Standardization. (2022). *Information security, | ||
| cybersecurity and privacy protection — Information security management systems | ||
| — Requirements* (ISO/IEC 27001:2022). Control A.8.13 requires information | ||
| backup; this package records a bounded physical/PITR profile, not a certified | ||
| ISMS. | ||
|
|
||
| Swanson, M., Bowen, P., Phillips, A., Gallup, D., & Lynes, D. (2010). | ||
| *Contingency planning guide for federal information systems* (NIST Special | ||
| Publication 800-34 Rev. 1). National Institute of Standards and Technology. | ||
| https://doi.org/10.6028/NIST.SP.800-34r1 | ||
|
|
||
| The PostgreSQL Global Development Group. (2026). *Backup and restore*. | ||
| PostgreSQL 18 documentation. https://www.postgresql.org/docs/18/backup.html | ||
|
|
||
| The PostgreSQL Global Development Group. (2026). *Continuous archiving and | ||
| point-in-time recovery (PITR)*. PostgreSQL 18 documentation. | ||
| https://www.postgresql.org/docs/18/continuous-archiving.html | ||
|
|
||
| The PostgreSQL Global Development Group. (2026). *pg_basebackup*. PostgreSQL 18 | ||
| documentation. https://www.postgresql.org/docs/18/app-pgbasebackup.html | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,221 @@ | ||
| # SPDX-License-Identifier: Apache-2.0 | ||
| """Bind a caller-owned physical/WAL/PITR recovery profile without executing backup.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import json | ||
| from dataclasses import dataclass | ||
|
|
||
|
|
||
| _BACKUP_METHODS = frozenset({"physical", "pitr"}) | ||
| _POINT_IN_TIME_KINDS = frozenset({"time", "xid", "name", "lsn"}) | ||
| _RECOVERY_TARGET_KINDS = frozenset({"immediate"}) | _POINT_IN_TIME_KINDS | ||
| _PROFILE_KEYS = frozenset( | ||
| { | ||
| "schema_version", | ||
| "postgres_major", | ||
| "backup_method", | ||
| "recovery_target_kind", | ||
| "wal_archive_required", | ||
| "isolated_target_prepared", | ||
| "rpo_seconds", | ||
| "rto_seconds", | ||
| "package_capability_claim", | ||
| } | ||
| ) | ||
| _MAX_SIGNED_BIGINT = (1 << 63) - 1 | ||
| _MAX_PROFILE_JSON_BYTES = 2048 | ||
|
|
||
|
|
||
| class PostgresPhysicalRecoveryError(ValueError): | ||
| """Report a fail-closed physical/WAL/PITR recovery-profile violation.""" | ||
|
|
||
|
|
||
| def _exact_major(value: object) -> bool: | ||
| """Return whether a value is an exact PostgreSQL major-version integer.""" | ||
| return type(value) is int and 1 <= value <= 99 | ||
|
|
||
|
|
||
| def _exact_method(value: object) -> bool: | ||
| """Return whether a value is one reviewed physical or PITR method string.""" | ||
| return type(value) is str and value in _BACKUP_METHODS | ||
|
|
||
|
|
||
| def _exact_target_kind(value: object) -> bool: | ||
| """Return whether a value is one reviewed recovery-target kind string.""" | ||
| return type(value) is str and value in _RECOVERY_TARGET_KINDS | ||
|
|
||
|
|
||
| def _exact_bool(value: object) -> bool: | ||
| """Return whether a value is an exact built-in boolean.""" | ||
| return type(value) is bool | ||
|
|
||
|
|
||
| def _optional_positive_seconds(value: object) -> bool: | ||
| """Return whether a value is omitted or an exact positive second budget.""" | ||
| return value is None or ( | ||
| type(value) is int and 1 <= value <= _MAX_SIGNED_BIGINT | ||
| ) | ||
|
|
||
|
|
||
| def _reject_duplicate_object_pairs( | ||
| pairs: list[tuple[str, object]], | ||
| ) -> dict[str, object]: | ||
| """Build one JSON object while rejecting ambiguous duplicate member names.""" | ||
| decoded: dict[str, object] = {} | ||
| for key, value in pairs: | ||
| if key in decoded: | ||
| raise PostgresPhysicalRecoveryError( | ||
| "invalid PostgreSQL physical recovery profile schema" | ||
| ) | ||
| decoded[key] = value | ||
| return decoded | ||
|
|
||
|
|
||
| @dataclass(frozen=True, slots=True) | ||
| class PostgresPhysicalRecoveryProfile: | ||
| """Represent one caller-owned physical or PITR recovery profile. | ||
|
|
||
| The profile records deployer-selected method, time-flow target kind, WAL | ||
| archive necessity, isolated-target readiness, and optional RPO/RTO | ||
| objectives. It does not execute ``pg_basebackup``, archive WAL, or restore | ||
| a cluster, and it never claims those objectives as package capability. | ||
| """ | ||
|
|
||
| postgres_major: int | ||
| backup_method: str | ||
| recovery_target_kind: str | ||
| wal_archive_required: bool | ||
| isolated_target_prepared: bool | ||
| rpo_seconds: int | None | ||
| rto_seconds: int | None | ||
|
|
||
| def __post_init__(self) -> None: | ||
| """Fail closed when the profile violates the bounded recovery contract.""" | ||
| if not ( | ||
| _exact_major(self.postgres_major) | ||
| and _exact_method(self.backup_method) | ||
| and _exact_target_kind(self.recovery_target_kind) | ||
| and _exact_bool(self.wal_archive_required) | ||
| and _exact_bool(self.isolated_target_prepared) | ||
| and _optional_positive_seconds(self.rpo_seconds) | ||
| and _optional_positive_seconds(self.rto_seconds) | ||
| ): | ||
| raise PostgresPhysicalRecoveryError( | ||
| "invalid PostgreSQL physical recovery profile" | ||
| ) | ||
| if self.isolated_target_prepared is False: | ||
| raise PostgresPhysicalRecoveryError( | ||
| "PostgreSQL physical recovery requires an isolated target" | ||
| ) | ||
| if self.backup_method == "pitr" and self.wal_archive_required is False: | ||
| raise PostgresPhysicalRecoveryError( | ||
| "PostgreSQL PITR profile requires a WAL archive" | ||
| ) | ||
| if ( | ||
| self.recovery_target_kind in _POINT_IN_TIME_KINDS | ||
| and self.backup_method != "pitr" | ||
| ): | ||
| raise PostgresPhysicalRecoveryError( | ||
| "PostgreSQL point-in-time target requires a PITR profile" | ||
| ) | ||
|
|
||
| def as_dict(self) -> dict[str, object]: | ||
| """Return the stable machine-readable physical recovery profile schema.""" | ||
| return { | ||
| "schema_version": 1, | ||
| "postgres_major": self.postgres_major, | ||
| "backup_method": self.backup_method, | ||
| "recovery_target_kind": self.recovery_target_kind, | ||
| "wal_archive_required": self.wal_archive_required, | ||
| "isolated_target_prepared": self.isolated_target_prepared, | ||
| "rpo_seconds": self.rpo_seconds, | ||
| "rto_seconds": self.rto_seconds, | ||
| "package_capability_claim": False, | ||
| } | ||
|
|
||
| def to_json(self) -> str: | ||
| """Return deterministic compact JSON without deployment or business content.""" | ||
| return json.dumps( | ||
| self.as_dict(), | ||
| sort_keys=True, | ||
| separators=(",", ":"), | ||
| ensure_ascii=True, | ||
| ) | ||
|
|
||
|
|
||
| def bind_postgres_physical_recovery_profile( | ||
| *, | ||
| postgres_major: int, | ||
| backup_method: str, | ||
| recovery_target_kind: str, | ||
| wal_archive_required: bool, | ||
| isolated_target_prepared: bool, | ||
| rpo_seconds: int | None = None, | ||
| rto_seconds: int | None = None, | ||
| ) -> PostgresPhysicalRecoveryProfile: | ||
| """Bind one caller-owned physical or PITR profile without executing recovery. | ||
|
|
||
| Callers must already have an isolated recovery target. The service name, | ||
| archive path, WAL location, and restore command stay outside this seam. | ||
| ``backup_method="pitr"`` requires ``wal_archive_required=True``. Point-in-time | ||
| kinds ``time``, ``xid``, ``name``, and ``lsn`` require ``backup_method="pitr"`` | ||
| so a crash-consistent physical base backup cannot be labeled as a time-flow | ||
| restore. Optional ``rpo_seconds`` and ``rto_seconds`` are deployer-selected | ||
| objectives only; the emitted profile always sets | ||
| ``package_capability_claim`` to ``False``. | ||
| """ | ||
| return PostgresPhysicalRecoveryProfile( | ||
| postgres_major=postgres_major, | ||
| backup_method=backup_method, | ||
| recovery_target_kind=recovery_target_kind, | ||
| wal_archive_required=wal_archive_required, | ||
| isolated_target_prepared=isolated_target_prepared, | ||
| rpo_seconds=rpo_seconds, | ||
| rto_seconds=rto_seconds, | ||
| ) | ||
|
|
||
|
|
||
| def parse_postgres_physical_recovery_profile( | ||
| raw_profile: str, | ||
| ) -> PostgresPhysicalRecoveryProfile: | ||
| """Parse one bounded profile and reject extensions or capability claims.""" | ||
| if type(raw_profile) is not str: | ||
| raise PostgresPhysicalRecoveryError( | ||
| "invalid PostgreSQL physical recovery profile JSON" | ||
| ) | ||
| encoded_size = len(raw_profile.encode("utf-8")) | ||
|
cursor[bot] marked this conversation as resolved.
Resolved
|
||
| if encoded_size == 0 or encoded_size > _MAX_PROFILE_JSON_BYTES: | ||
| raise PostgresPhysicalRecoveryError( | ||
| "invalid PostgreSQL physical recovery profile JSON" | ||
| ) | ||
| try: | ||
| decoded = json.loads( | ||
| raw_profile, | ||
| object_pairs_hook=_reject_duplicate_object_pairs, | ||
| ) | ||
| except (json.JSONDecodeError, RecursionError): | ||
| raise PostgresPhysicalRecoveryError( | ||
| "invalid PostgreSQL physical recovery profile JSON" | ||
| ) from None | ||
| if type(decoded) is not dict or frozenset(decoded) != _PROFILE_KEYS: | ||
| raise PostgresPhysicalRecoveryError( | ||
| "invalid PostgreSQL physical recovery profile schema" | ||
| ) | ||
| if decoded.get("schema_version") != 1 or type(decoded.get("schema_version")) is not int: | ||
| raise PostgresPhysicalRecoveryError( | ||
| "invalid PostgreSQL physical recovery profile schema" | ||
| ) | ||
| if decoded.get("package_capability_claim") is not False: | ||
| raise PostgresPhysicalRecoveryError( | ||
| "PostgreSQL physical recovery profile cannot claim package capability" | ||
| ) | ||
| return PostgresPhysicalRecoveryProfile( | ||
| postgres_major=decoded["postgres_major"], | ||
| backup_method=decoded["backup_method"], | ||
| recovery_target_kind=decoded["recovery_target_kind"], | ||
| wal_archive_required=decoded["wal_archive_required"], | ||
| isolated_target_prepared=decoded["isolated_target_prepared"], | ||
| rpo_seconds=decoded["rpo_seconds"], | ||
| rto_seconds=decoded["rto_seconds"], | ||
| ) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.