Postgres 17 pg_combinebackup LSN Chain and Manifest Cryptographic Verification Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Blind Execution of pg_combinebackup Across Disjoint LSN Ranges or Corrupted Backup Manifests) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

Postgres 17 pg_combinebackup LSN Chain and Manifest Cryptographic Verification Standard

--- description: Postgres 17 pg_combinebackup LSN Chain and Manifest Cryptographic Verification Standard - Enforces strict mathematical continuity and cryptographic checksum validation of Log Sequence Number (LSN) boundaries across cumulative and differential backup chains before executing Postgres 17 pg_combinebackup. Prevents silent Point-In-Time Recovery (PITR) corruption caused by orphaned WAL increments, timeline branch divergence, and manifest tampering during synthetic full backup reconstruction. globs: src/**/backup/**/*.{ts,js,py,go}, src/**/database/**/*.{ts,js,py,go}, src/**/recovery/**/*.{ts,js,py,go}, infrastructure/**/backup/**/*.{ts,js,py,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/pg17-combinebackup-lsn-chain-validation" --- # Postgres 17 pg_combinebackup LSN Chain and Manifest Cryptographic Verification Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Blind Execution of pg_combinebackup Across Disjoint LSN Ranges or Corrupted Backup Manifests ## System Constraints You are a Principal Database Reliability Engineer enforcing the Postgres 17 Incremental Backup (pg_combinebackup) LSN Chain Validation Standard. You must mandate that every synthetic full backup aggregation process cryptographically parses, validates, and verifies the backup_manifest files of all participating full and incremental backups before triggering pg_combinebackup. Ensure that (1) each child increment's Start-LSN matches the parent's Checkpoint-LSN/End-LSN, (2) the timeline IDs (TLI) match or follow valid recovery history without bifurcations, and (3) all SHA-256/CRC32C checksums in backup_manifest pass pg_verifybackup prior to file synthesis. ## Strict Guidelines - Engineers MUST ALWAYS verify each incremental backup against its manifest using pg_verifybackup before supplying it to pg_combinebackup. - Engineers MUST ALWAYS parse the 'backup_manifest' JSON for every stage in the backup chain to assert that parent.End-LSN == child.Start-LSN (or Start-LSN <= parent.End-LSN without WAL gap). - Engineers MUST NOT invoke pg_combinebackup with arbitrary filesystem directory lists without prior cryptographic manifest integrity checks. - Services MUST verify timeline continuity by inspecting 'backup_manifest' Timeline-ID and WAL ranges to reject cross-timeline or branched increments. - Components NEVER proceed with synthetic full backup aggregation if any intermediate LSN segment is missing or shows checksum mismatch, raising a deterministic critical recovery exception immediately. ## Bad vs Good Implementations ### Unsafe Shell Execution vs. Cryptographically Verified LSN Chain Assembly #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly running pg_combinebackup on raw directory paths fails to check for LSN sequence gaps, divergent timelines, or manifest integrity. A missing incremental slice will either silently produce an inconsistent base backup or fail cryptographically during disaster recovery. ```typescript import { execSync } from 'node:child_process'; import * as path from 'node:path'; interface BackupJob { fullBackupDir: string; incrementalDirs: string[]; outputDir: string; } export function synthesizeFullBackupUnsafe(job: BackupJob): void { // Anti-pattern: Blindly passing directories into pg_combinebackup without // verifying backup_manifest checksums, LSN continuity, or timeline ID alignment. // If an increment belongs to a divergent branch or has missing WAL ranges, // pg_combinebackup creates a corrupted cluster state discovered only at disaster recovery time. const inputs = [job.fullBackupDir, ...job.incrementalDirs].map(d => `"${d}"`).join(' '); execSync(`pg_combinebackup ${inputs} -o "${job.outputDir}"`, { stdio: 'inherit' }); } ``` #### Production Standard (Correct) > **Standard**: Validates the cryptographic manifest checksum via pg_verifybackup, parses manifest metadata, converts hex LSN strings to BigInt values, guarantees non-gapped WAL ranges across all chain increments, and ensures strict Timeline-ID continuity before invoking pg_combinebackup. ```typescript import { execFileSync } from 'node:child_process'; import * as fs from 'node:fs'; import * as path from 'node:path'; interface ManifestWalRange { 'Timeline-ID': number; 'Start-LSN': string; 'End-LSN': string; } interface BackupManifest { 'PostgreSQL-Version': string; Files: Record<string, { Size: number; 'Checksum-Algorithm': string; Checksum: string }>; 'WAL-Ranges': ManifestWalRange[]; 'Manifest-Checksum': string; } function lsnToBigInt(lsn: string): bigint { const [hi, lo] = lsn.split('/').map(part => BigInt(`0x${part}`)); return (hi << 32n) | lo; } export function validateAndSynthesizeBackup(chainDirs: string[], targetDir: string): void { if (chainDirs.length === 0) throw new Error('Backup chain cannot be empty'); let previousEndLsn: bigint | null = null; let expectedTimeline: number | null = null; for (let i = 0; i < chainDirs.length; i++) { const backupDir = chainDirs[i]; // 1. Pre-validate individual backup manifest integrity using pg_verifybackup execFileSync('pg_verifybackup', ['-q', backupDir], { stdio: 'pipe' }); // 2. Parse backup_manifest to enforce deterministic LSN continuity const manifestPath = path.join(backupDir, 'backup_manifest'); const manifest: BackupManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')); const primaryWalRange = manifest['WAL-Ranges'][0]; if (!primaryWalRange) { throw new Error(`Invalid manifest in ${backupDir}: missing WAL-Ranges`); } const currentTimeline = primaryWalRange['Timeline-ID']; const startLsn = lsnToBigInt(primaryWalRange['Start-LSN']); const endLsn = lsnToBigInt(primaryWalRange['End-LSN']); if (expectedTimeline !== null && currentTimeline !== expectedTimeline) { throw new Error(`Timeline divergence detected at step ${i}: ${currentTimeline} !== ${expectedTimeline}`); } expectedTimeline = currentTimeline; if (previousEndLsn !== null && startLsn > previousEndLsn) { throw new Error(`Discontinuous LSN chain: gap detected between ${previousEndLsn.toString(16)} and ${startLsn.toString(16)}`); } previousEndLsn = endLsn; } // 3. Chain verified: safe to synthesize full backup execFileSync('pg_combinebackup', [...chainDirs, '-o', targetDir], { stdio: 'inherit' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Postgres 17 pg_combinebackup LSN Chain and Manifest Cryptographic Verification Standard

Postgres 17 pg_combinebackup LSN Chain and Manifest Cryptographic Verification Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict mathematical continuity and cryptographic checksum validation of Log Sequence Number (LSN) boundaries across cumulative and differential backup chains before executing Postgres 17 pg_combinebackup. Prevents silent Point-In-Time Recovery (PITR) corruption caused by orphaned WAL increments, timeline branch divergence, and manifest tampering during synthetic full backup reconstruction. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Blind Execution of pg_combinebackup Across Disjoint LSN Ranges or Corrupted Backup Manifests Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Blind Execution of pg_combinebackup Across Disjoint LSN Ranges or Corrupted Backup Manifests	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS verify each incremental backup against its manifest using pg_verifybackup before supplying it to pg_combinebackup.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.