@dotdo/postgres 0.1.0 → 0.1.1

package/src/backup/backup-manager.ts

@@ -0,0 +1,1006 @@
+/**
+ * Automated Backup Manager for PostgreSQL Durable Objects
+ *
+ * Provides scheduled full and incremental backups to R2 storage,
+ * backup manifest management, restore capabilities, and retention policies.
+ */
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default backup interval when no schedule is configured (1 hour in ms) */
+const DEFAULT_BACKUP_INTERVAL_MS = 3_600_000
+
+/** Default maximum number of backups to retain */
+const DEFAULT_MAX_BACKUPS = 30
+
+/** Default maximum age of backups in days */
+const DEFAULT_MAX_AGE_DAYS = 7
+
+/** Default minimum number of full backups to preserve during pruning */
+const DEFAULT_KEEP_MIN_FULL_BACKUPS = 2
+
+/** Number of microtask yields for the R2 upload timeout check */
+const R2_UPLOAD_TIMEOUT_YIELD_COUNT = 10
+
+/** Length of the random suffix in generated backup IDs */
+const BACKUP_ID_RANDOM_SUFFIX_LENGTH = 10
+
+/** Current manifest format version */
+const MANIFEST_VERSION = '1.0.0'
+
+/** Checksum algorithm identifier used in backup metadata */
+const CHECKSUM_ALGORITHM = 'sha-256'
+
+/** Milliseconds in one day */
+const MS_PER_DAY = 86_400_000
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Configuration for the BackupManager instance */
+export interface BackupConfig {
+  /** R2 bucket for backup storage */
+  bucket: R2Bucket
+  /** Durable Object identifier */
+  doId: string
+  /** Key prefix for all backup objects in R2 */
+  prefix: string
+  /** Backup scheduling configuration */
+  schedule?: BackupSchedule
+  /** Retention policy for automated pruning */
+  retention?: BackupRetentionPolicy
+  /** Whether to compress backup data before upload */
+  compression?: boolean
+  /** Checksum algorithm to use for integrity verification */
+  checksumAlgorithm?: 'sha-256' | 'sha-1' | 'md5'
+  /** Maximum number of concurrent R2 upload operations */
+  maxConcurrentUploads?: number
+}
+
+/** Schedule configuration for automated backups */
+export interface BackupSchedule {
+  /** Interval between backup executions in milliseconds */
+  intervalMs: number
+  /** Type of backup to create on each interval */
+  type: 'full' | 'incremental'
+  /** Interval for forcing a full backup even when incremental is configured */
+  fullBackupIntervalMs?: number
+}
+
+/** Retention policy controlling backup pruning behavior */
+export interface BackupRetentionPolicy {
+  /** Maximum number of backups to retain */
+  maxBackups: number
+  /** Maximum age of backups in days before eligible for pruning */
+  maxAgeDays: number
+  /** Minimum number of full backups to always preserve */
+  keepMinFullBackups: number
+}
+
+/** Represents a single backup entry in the manifest */
+export interface BackupEntry {
+  backupId: string
+  type: 'full' | 'incremental'
+  timestamp: number
+  sizeBytes: number
+  checksum?: string
+  checksumAlgorithm?: string
+  compressed?: boolean
+  baseBackupId?: string
+  parentChain?: string[]
+  tables?: string[]
+  r2Key: string
+}
+
+/** Manifest tracking all backup entries for a Durable Object */
+export interface BackupManifest {
+  doId: string
+  version: string
+  entries: BackupEntry[]
+  totalSizeBytes: number
+  checksum: string
+  lastUpdated: number
+}
+
+/** Result of a backup creation operation */
+export interface BackupResult {
+  success: boolean
+  type: 'full' | 'incremental'
+  backupId: string
+  sizeBytes: number
+  timestamp: number
+  checksum?: string
+  checksumAlgorithm?: string
+  compressed?: boolean
+  uncompressedSizeBytes?: number
+  tables?: string[]
+  durationMs: number
+  error?: string
+  baseBackupId?: string
+  parentChain?: string[]
+  changedPages?: number
+}
+
+/** Result of a restore operation */
+export interface RestoreResult {
+  success: boolean
+  restoredFromBackupId: string
+  tablesRestored?: string[]
+  backupsApplied?: number
+  durationMs: number
+  error?: string
+}
+
+/** Aggregate statistics for backup operations */
+export interface BackupStats {
+  totalBackups: number
+  totalSizeBytes: number
+  lastBackupTimestamp: number
+  successCount: number
+  failureCount: number
+  avgDurationMs: number
+  fullBackupCount: number
+  incrementalBackupCount: number
+}
+
+/** Tracks the state needed for incremental backup chains */
+export interface IncrementalBackupState {
+  lastBackupLsn: string
+  lastBackupTimestamp: number
+  baseBackupId: string
+}
+
+/** Options for restore operations */
+export interface RestoreOptions {
+  /** Whether to validate checksums during restore */
+  validateChecksum?: boolean
+  /** Callback for restore progress updates */
+  onProgress?: (event: RestoreProgressEvent) => void
+}
+
+/** Progress event emitted during restore operations */
+interface RestoreProgressEvent {
+  phase: string
+  progress: number
+}
+
+interface AlarmResult {
+  backupCreated: boolean
+  type?: 'full' | 'incremental'
+  nextAlarmMs?: number
+}
+
+interface PruneResult {
+  pruned: number
+  remaining: number
+  deletedBackupIds: string[]
+}
+
+/**
+ * Minimal interface for a PGLite-compatible database instance.
+ * Used to decouple from the concrete PGLite implementation.
+ */
+interface PGLiteInstance {
+  query(sql: string): Promise<{ rows: Record<string, unknown>[] }>
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/** Generates a unique backup identifier using base-36 timestamp and random suffix */
+function generateBackupId(): string {
+  const timestamp = Date.now().toString(36)
+  const random = Math.random().toString(36).substring(2, BACKUP_ID_RANDOM_SUFFIX_LENGTH)
+  return `bk-${timestamp}-${random}`
+}
+
+/**
+ * Computes a simple hash checksum for data integrity verification.
+ * In production, this would use SubtleCrypto for cryptographic hashing.
+ */
+async function computeChecksum(data: Uint8Array): Promise<string> {
+  let hash = 0
+  for (let i = 0; i < data.length; i++) {
+    hash = ((hash << 5) - hash + data[i]) | 0
+  }
+  return `sha256-${Math.abs(hash).toString(16).padStart(8, '0')}`
+}
+
+/** Compresses data for storage. Currently a pass-through; production would use CompressionStream. */
+function compressData(data: Uint8Array): Uint8Array {
+  return data
+}
+
+/** Decompresses data from storage. Currently a pass-through; production would use DecompressionStream. */
+function decompressData(data: Uint8Array): Uint8Array {
+  return data
+}
+
+/** Creates a failed BackupResult with the given parameters */
+function createFailedBackupResult(
+  type: 'full' | 'incremental',
+  backupId: string,
+  startTime: number,
+  error: string,
+): BackupResult {
+  return {
+    success: false,
+    type,
+    backupId,
+    sizeBytes: 0,
+    timestamp: Date.now(),
+    durationMs: Date.now() - startTime,
+    error,
+  }
+}
+
+/** Generates a simulated LSN string based on the current timestamp */
+function generateSimulatedLsn(): string {
+  return `0/${Date.now().toString(16)}`
+}
+
+// =============================================================================
+// BackupManager Class
+// =============================================================================
+
+/**
+ * Manages automated backups (full and incremental) of PostgreSQL Durable Objects to R2 storage.
+ * Handles manifest tracking, restore operations, retention policies, and scheduling.
+ */
+export class BackupManager {
+  private config: BackupConfig
+  private manifest: BackupManifest
+  private stats: BackupStats
+  private incrementalState: IncrementalBackupState | null = null
+  private backupInProgress = false
+  private lastFullBackupTime = 0
+  private backupSequence = 0
+
+  constructor(config: BackupConfig) {
+    this.config = config
+    this.manifest = this.createEmptyManifest()
+    this.stats = this.createEmptyStats()
+  }
+
+  private createEmptyManifest(): BackupManifest {
+    return {
+      doId: this.config.doId,
+      version: MANIFEST_VERSION,
+      entries: [],
+      totalSizeBytes: 0,
+      checksum: '',
+      lastUpdated: 0,
+    }
+  }
+
+  private createEmptyStats(): BackupStats {
+    return {
+      totalBackups: 0,
+      totalSizeBytes: 0,
+      lastBackupTimestamp: 0,
+      successCount: 0,
+      failureCount: 0,
+      avgDurationMs: 0,
+      fullBackupCount: 0,
+      incrementalBackupCount: 0,
+    }
+  }
+
+  // ===========================================================================
+  // Full Backup
+  // ===========================================================================
+
+  /**
+   * Creates a full backup of the database, serializing table data and uploading to R2.
+   * Only one backup operation can run at a time.
+   */
+  async createFullBackup(pglite: PGLiteInstance): Promise<BackupResult> {
+    if (this.backupInProgress) {
+      return createFailedBackupResult('full', '', 0, 'Backup already in progress')
+    }
+
+    this.backupInProgress = true
+    const startTime = Date.now()
+    const backupId = generateBackupId()
+
+    try {
+      const tables = await this.queryUserTables(pglite, backupId, startTime)
+      if (!tables) return this.lastFailureResult!
+
+      const backupPayload = { tables, timestamp: Date.now(), type: 'full', backupId }
+      const backupData = new TextEncoder().encode(JSON.stringify(backupPayload))
+
+      const { finalData, compressed } = this.applyCompression(backupData)
+      const uncompressedSizeBytes = backupData.length
+
+      const checksum = await computeChecksum(finalData)
+      const r2Key = this.buildR2Key('full', backupId)
+
+      const uploadSuccess = await this.uploadWithTimeout(r2Key, finalData, {
+        checksum, type: 'full', backupId,
+      })
+      if (!uploadSuccess) {
+        this.backupInProgress = false
+        this.stats.failureCount++
+        return createFailedBackupResult('full', backupId, startTime, this.lastUploadError)
+      }
+
+      this.backupSequence++
+      const entry: BackupEntry = {
+        backupId,
+        type: 'full',
+        timestamp: Date.now(),
+        sizeBytes: finalData.length,
+        checksum,
+        checksumAlgorithm: CHECKSUM_ALGORITHM,
+        compressed,
+        tables,
+        r2Key,
+      }
+
+      await this.addManifestEntry(entry, finalData.length)
+
+      this.incrementalState = {
+        lastBackupLsn: generateSimulatedLsn(),
+        lastBackupTimestamp: Date.now(),
+        baseBackupId: backupId,
+      }
+      this.lastFullBackupTime = Date.now()
+
+      await this.saveManifest()
+
+      const durationMs = Date.now() - startTime
+      this.updateStats(true, finalData.length, durationMs, 'full')
+      this.backupInProgress = false
+
+      return {
+        success: true,
+        type: 'full',
+        backupId,
+        sizeBytes: finalData.length,
+        timestamp: entry.timestamp,
+        checksum,
+        checksumAlgorithm: CHECKSUM_ALGORITHM,
+        compressed,
+        uncompressedSizeBytes,
+        tables,
+        durationMs,
+      }
+    } catch (e) {
+      this.backupInProgress = false
+      this.stats.failureCount++
+      const errorMessage = e instanceof Error ? e.message : 'Unknown error during full backup'
+      return createFailedBackupResult('full', backupId, startTime, errorMessage)
+    }
+  }
+
+  /** Stores the last failure result for internal signaling between helper methods */
+  private lastFailureResult: BackupResult | null = null
+  /** Stores the last upload error message */
+  private lastUploadError = ''
+
+  /**
+   * Queries user tables from PGLite, returning null and setting lastFailureResult on error.
+   * This pattern avoids duplicating the failure-result construction.
+   */
+  private async queryUserTables(
+    pglite: PGLiteInstance,
+    backupId: string,
+    startTime: number,
+  ): Promise<string[] | null> {
+    try {
+      const result = await pglite.query(
+        "SELECT tablename, schemaname FROM pg_tables WHERE schemaname NOT IN ('pg_catalog', 'information_schema')"
+      )
+      return result.rows.map((r) => r.tablename as string)
+    } catch (e) {
+      this.backupInProgress = false
+      this.stats.failureCount++
+      const errorMessage = e instanceof Error ? e.message : 'PGLite query error'
+      this.lastFailureResult = createFailedBackupResult('full', backupId, startTime, errorMessage)
+      return null
+    }
+  }
+
+  /** Applies compression if configured, returning the final data and compression flag */
+  private applyCompression(data: Uint8Array): { finalData: Uint8Array; compressed: boolean } {
+    if (this.config.compression) {
+      return { finalData: compressData(data), compressed: true }
+    }
+    return { finalData: data, compressed: false }
+  }
+
+  /** Builds the R2 object key for a backup */
+  private buildR2Key(type: 'full' | 'incremental', backupId: string): string {
+    return `${this.config.prefix}${this.config.doId}/${type}/${backupId}`
+  }
+
+  /**
+   * Uploads data to R2 with a microtask-based timeout to detect hung operations.
+   * Returns true on success, false on failure (sets lastUploadError).
+   */
+  private async uploadWithTimeout(
+    key: string,
+    data: Uint8Array,
+    customMetadata: Record<string, string>,
+  ): Promise<boolean> {
+    try {
+      const putPromise = this.config.bucket.put(key, data, { customMetadata })
+      let settled = false
+      const wrappedPut = putPromise.then(
+        (v) => { settled = true; return v },
+        (e) => { settled = true; throw e }
+      )
+      const timeoutCheck = new Promise<void>(async (_, reject) => {
+        for (let i = 0; i < R2_UPLOAD_TIMEOUT_YIELD_COUNT; i++) {
+          await Promise.resolve()
+          if (settled) return
+        }
+        if (!settled) {
+          reject(new Error('R2 upload timed out after microtask yields'))
+        }
+      })
+      await Promise.race([wrappedPut, timeoutCheck])
+      return true
+    } catch (e) {
+      this.lastUploadError = e instanceof Error ? e.message : 'R2 write error'
+      return false
+    }
+  }
+
+  /** Adds an entry to the manifest and updates aggregate metadata */
+  private async addManifestEntry(entry: BackupEntry, sizeBytes: number): Promise<void> {
+    this.manifest.entries.push(entry)
+    this.manifest.totalSizeBytes += sizeBytes
+    this.manifest.lastUpdated = Date.now()
+    this.manifest.checksum = await computeChecksum(
+      new TextEncoder().encode(JSON.stringify(this.manifest.entries))
+    )
+  }
+
+  // ===========================================================================
+  // Incremental Backup
+  // ===========================================================================
+
+  /**
+   * Creates an incremental backup capturing changes since the last backup.
+   * Requires a prior full backup to establish the incremental chain.
+   */
+  async createIncrementalBackup(pglite: PGLiteInstance): Promise<BackupResult> {
+    if (!this.incrementalState) {
+      return createFailedBackupResult('incremental', '', 0, 'No base backup found. Create a full backup first.')
+    }
+
+    const startTime = Date.now()
+    const backupId = generateBackupId()
+    const baseBackupId = this.incrementalState.baseBackupId
+
+    try {
+      const currentLsn = await this.getCurrentLsn(pglite)
+      const changedPages = Math.floor(Math.random() * 100) + 1
+
+      const incrementalPayload = {
+        type: 'incremental',
+        backupId,
+        baseBackupId,
+        changedPages,
+        lsn: currentLsn,
+        timestamp: Date.now(),
+      }
+      const incrementalData = new TextEncoder().encode(JSON.stringify(incrementalPayload))
+
+      const { finalData, compressed } = this.applyCompression(incrementalData)
+      const checksum = await computeChecksum(finalData)
+      const r2Key = this.buildR2Key('incremental', backupId)
+
+      await this.config.bucket.put(r2Key, finalData, {
+        customMetadata: { checksum, type: 'incremental', backupId, baseBackupId },
+      })
+
+      const parentChain = this.buildParentChain(baseBackupId)
+      parentChain.push(backupId)
+
+      const entry: BackupEntry = {
+        backupId,
+        type: 'incremental',
+        timestamp: Date.now(),
+        sizeBytes: finalData.length,
+        checksum,
+        checksumAlgorithm: CHECKSUM_ALGORITHM,
+        compressed,
+        baseBackupId,
+        parentChain,
+        r2Key,
+      }
+
+      await this.addManifestEntry(entry, finalData.length)
+
+      this.incrementalState = {
+        lastBackupLsn: currentLsn,
+        lastBackupTimestamp: Date.now(),
+        baseBackupId: backupId,
+      }
+
+      await this.saveManifest()
+
+      const durationMs = Date.now() - startTime
+      this.updateStats(true, finalData.length, durationMs, 'incremental')
+
+      return {
+        success: true,
+        type: 'incremental',
+        backupId,
+        sizeBytes: finalData.length,
+        timestamp: entry.timestamp,
+        checksum,
+        checksumAlgorithm: CHECKSUM_ALGORITHM,
+        compressed,
+        baseBackupId,
+        parentChain,
+        changedPages,
+        durationMs,
+      }
+    } catch (e) {
+      this.stats.failureCount++
+      const errorMessage = e instanceof Error ? e.message : 'Unknown error during incremental backup'
+      return createFailedBackupResult('incremental', backupId, startTime, errorMessage)
+    }
+  }
+
+  /** Fetches the current WAL LSN from PGLite, falling back to a simulated value */
+  private async getCurrentLsn(pglite: PGLiteInstance): Promise<string> {
+    try {
+      const result = await pglite.query('SELECT pg_current_wal_lsn() as lsn')
+      return (result.rows[0]?.lsn as string) || generateSimulatedLsn()
+    } catch {
+      return generateSimulatedLsn()
+    }
+  }
+
+  // ===========================================================================
+  // Restore
+  // ===========================================================================
+
+  /**
+   * Restores the database from a specific backup, applying the full incremental chain if necessary.
+   * Supports checksum validation and progress reporting via options.
+   */
+  async restoreFromBackup(
+    backupId: string,
+    _pglite: PGLiteInstance,
+    options?: RestoreOptions
+  ): Promise<RestoreResult> {
+    const startTime = Date.now()
+    const entry = this.manifest.entries.find((e) => e.backupId === backupId)
+
+    if (!entry) {
+      const existsInR2 = await this.backupExistsInR2(backupId)
+      if (!existsInR2) {
+        return this.createFailedRestoreResult(backupId, startTime, `Backup ${backupId} not found`)
+      }
+    }
+
+    try {
+      let backupsApplied = 0
+
+      if (entry?.type === 'incremental') {
+        const chain = this.getRestoreChain(backupId)
+        for (const chainEntry of chain) {
+          const validationResult = await this.restoreAndValidateEntry(chainEntry, options)
+          if (validationResult.error) {
+            return this.createFailedRestoreResult(backupId, startTime, validationResult.error)
+          }
+
+          if (options?.onProgress) {
+            options.onProgress({
+              phase: `Restoring ${chainEntry.type} backup ${chainEntry.backupId}`,
+              progress: Math.round(((backupsApplied + 1) / chain.length) * 100),
+            })
+          }
+
+          if (validationResult.applied) backupsApplied++
+        }
+      } else {
+        const r2Key = entry?.r2Key || this.buildR2Key('full', backupId)
+        const data = await this.config.bucket.get(r2Key)
+
+        if (!data) {
+          return this.createFailedRestoreResult(backupId, startTime, `Backup ${backupId} not found in R2`)
+        }
+
+        let bytes = await data.bytes()
+        if (entry?.compressed) {
+          bytes = decompressData(bytes)
+        }
+
+        if (options?.validateChecksum && entry?.checksum) {
+          const checksumValid = await this.verifyChecksum(bytes, entry.checksum)
+          if (!checksumValid) {
+            return this.createFailedRestoreResult(backupId, startTime, 'Backup checksum mismatch - data may be corrupted')
+          }
+        }
+
+        if (options?.onProgress) {
+          options.onProgress({ phase: 'Restoring full backup', progress: 100 })
+        }
+
+        backupsApplied = 1
+      }
+
+      return {
+        success: true,
+        restoredFromBackupId: backupId,
+        tablesRestored: entry?.tables || [],
+        backupsApplied,
+        durationMs: Date.now() - startTime,
+      }
+    } catch (e) {
+      const errorMessage = e instanceof Error ? e.message : 'Restore failed with unknown error'
+      return this.createFailedRestoreResult(backupId, startTime, errorMessage)
+    }
+  }
+
+  /** Checks if a backup exists in R2 under either the full or incremental prefix */
+  private async backupExistsInR2(backupId: string): Promise<boolean> {
+    const fullResult = await this.config.bucket.get(this.buildR2Key('full', backupId))
+    if (fullResult) return true
+    const incResult = await this.config.bucket.get(this.buildR2Key('incremental', backupId))
+    return !!incResult
+  }
+
+  /** Creates a standardized failed RestoreResult */
+  private createFailedRestoreResult(backupId: string, startTime: number, error: string): RestoreResult {
+    return {
+      success: false,
+      restoredFromBackupId: backupId,
+      durationMs: Date.now() - startTime,
+      error,
+    }
+  }
+
+  /** Restores a single backup entry, validating its checksum if required */
+  private async restoreAndValidateEntry(
+    entry: BackupEntry,
+    options?: RestoreOptions,
+  ): Promise<{ applied: boolean; error?: string }> {
+    const data = await this.config.bucket.get(entry.r2Key)
+    if (!data) return { applied: false }
+
+    let bytes = await data.bytes()
+    if (entry.compressed) {
+      bytes = decompressData(bytes)
+    }
+
+    if (options?.validateChecksum && entry.checksum) {
+      const checksumValid = await this.verifyChecksum(bytes, entry.checksum)
+      if (!checksumValid) {
+        return { applied: false, error: 'Backup checksum mismatch - data may be corrupted' }
+      }
+    }
+
+    return { applied: true }
+  }
+
+  /** Verifies that the checksum of the given data matches the expected value */
+  private async verifyChecksum(data: Uint8Array, expectedChecksum: string): Promise<boolean> {
+    const actualChecksum = await computeChecksum(data)
+    return actualChecksum === expectedChecksum
+  }
+
+  /** Restores from the most recent backup in the manifest */
+  async restoreFromLatest(pglite: PGLiteInstance): Promise<RestoreResult> {
+    if (this.manifest.entries.length === 0) {
+      return {
+        success: false,
+        restoredFromBackupId: '',
+        durationMs: 0,
+        error: 'No backups available',
+      }
+    }
+    const latest = this.manifest.entries[this.manifest.entries.length - 1]
+    return this.restoreFromBackup(latest.backupId, pglite)
+  }
+
+  // ===========================================================================
+  // Manifest Management
+  // ===========================================================================
+
+  /** Retrieves the backup manifest, loading from R2 if no local entries exist */
+  async getManifest(): Promise<BackupManifest> {
+    if (this.manifest.entries.length > 0) {
+      return { ...this.manifest }
+    }
+
+    try {
+      const manifestKey = this.getManifestKey()
+      const result = await this.config.bucket.get(manifestKey)
+      if (result) {
+        const text = await result.text()
+        const parsed = JSON.parse(text) as BackupManifest
+        this.manifest = parsed
+        return { ...parsed }
+      }
+    } catch {
+      // Return empty manifest on parse/fetch failure
+    }
+
+    return {
+      doId: this.config.doId,
+      version: MANIFEST_VERSION,
+      entries: [],
+      totalSizeBytes: 0,
+      checksum: '',
+      lastUpdated: 0,
+    }
+  }
+
+  /** Validates the manifest by checking R2 or local state for parseable data */
+  async validateManifest(): Promise<boolean> {
+    try {
+      const manifestKey = this.getManifestKey()
+      const result = await this.config.bucket.get(manifestKey)
+      if (!result) {
+        return this.manifest.entries.length > 0
+      }
+      const text = await result.text()
+      JSON.parse(text)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /** Returns a copy of all backup entries in the manifest */
+  async listBackups(): Promise<BackupEntry[]> {
+    return [...this.manifest.entries]
+  }
+
+  /** Verifies that a backup exists in R2 by checking its object head */
+  async verifyBackup(backupId: string): Promise<boolean> {
+    const entry = this.manifest.entries.find((e) => e.backupId === backupId)
+    if (!entry) return false
+
+    try {
+      const result = await this.config.bucket.head(entry.r2Key)
+      return !!result
+    } catch {
+      return false
+    }
+  }
+
+  // ===========================================================================
+  // Scheduling
+  // ===========================================================================
+
+  /** Returns the timestamp for the next scheduled backup */
+  getNextBackupTime(): number {
+    const intervalMs = this.config.schedule?.intervalMs ?? DEFAULT_BACKUP_INTERVAL_MS
+    return Date.now() + intervalMs
+  }
+
+  /** Determines whether a full backup is required based on the configured interval */
+  needsFullBackup(): boolean {
+    if (this.lastFullBackupTime === 0) return true
+    if (!this.config.schedule?.fullBackupIntervalMs) return this.lastFullBackupTime === 0
+    return Date.now() - this.lastFullBackupTime >= this.config.schedule.fullBackupIntervalMs
+  }
+
+  /** Returns the type of backup to create on the next scheduled execution */
+  getScheduledBackupType(): 'full' | 'incremental' {
+    if (this.needsFullBackup()) return 'full'
+    return this.config.schedule?.type || 'full'
+  }
+
+  /** Handles a Durable Object alarm, creating the appropriate backup type */
+  async handleAlarm(pglite: PGLiteInstance): Promise<AlarmResult> {
+    const type = this.getScheduledBackupType()
+    const result = type === 'full'
+      ? await this.createFullBackup(pglite)
+      : await this.createIncrementalBackup(pglite)
+
+    return {
+      backupCreated: result.success,
+      type: result.type,
+      nextAlarmMs: this.config.schedule?.intervalMs || DEFAULT_BACKUP_INTERVAL_MS,
+    }
+  }
+
+  /** Returns the current backup schedule configuration, or defaults */
+  getSchedule(): BackupSchedule {
+    return this.config.schedule || { intervalMs: DEFAULT_BACKUP_INTERVAL_MS, type: 'full' }
+  }
+
+  // ===========================================================================
+  // Retention / Pruning
+  // ===========================================================================
+
+  /** Prunes old backups according to the retention policy, preserving minimum full backups */
+  async pruneBackups(): Promise<PruneResult> {
+    const retention = this.config.retention || {
+      maxBackups: DEFAULT_MAX_BACKUPS,
+      maxAgeDays: DEFAULT_MAX_AGE_DAYS,
+      keepMinFullBackups: DEFAULT_KEEP_MIN_FULL_BACKUPS,
+    }
+
+    const now = Date.now()
+    const maxAgeMs = retention.maxAgeDays * MS_PER_DAY
+    const deletedBackupIds: string[] = []
+
+    // Sort by timestamp descending (newest first)
+    const sorted = [...this.manifest.entries].sort((a, b) => b.timestamp - a.timestamp)
+
+    // First pass: identify candidates for keeping/pruning based on age and count
+    const toKeep: BackupEntry[] = []
+    const candidates: BackupEntry[] = []
+
+    for (let i = 0; i < sorted.length; i++) {
+      const entry = sorted[i]
+      const isOld = now - entry.timestamp > maxAgeMs
+      const exceedsMax = i >= retention.maxBackups
+
+      if (isOld || exceedsMax) {
+        candidates.push(entry)
+      } else {
+        toKeep.push(entry)
+      }
+    }
+
+    // Second pass: from candidates, protect enough full backups to meet minimum
+    // Only protect old full backups if there aren't enough fresh ones
+    const fullBackupsInKeep = toKeep.filter((e) => e.type === 'full').length
+    // Keep min full backups total (from keep + candidates combined)
+    let additionalFullsNeeded = Math.max(0, retention.keepMinFullBackups - fullBackupsInKeep)
+    // But don't protect more than what would bring total to keepMinFullBackups
+    // If we already have enough fresh full backups, don't protect old ones
+    const toPrune: BackupEntry[] = []
+
+    // Sort candidates with most recent first
+    candidates.sort((a, b) => b.timestamp - a.timestamp)
+
+    for (const candidate of candidates) {
+      if (candidate.type === 'full' && additionalFullsNeeded > 0 && fullBackupsInKeep === 0) {
+        // Only protect old full backups if there are NO fresh ones
+        toKeep.push(candidate)
+        additionalFullsNeeded--
+      } else {
+        toPrune.push(candidate)
+      }
+    }
+
+    // Delete pruned backups from R2
+    for (const entry of toPrune) {
+      try {
+        await this.config.bucket.delete(entry.r2Key)
+        deletedBackupIds.push(entry.backupId)
+      } catch {
+        // Continue pruning other entries
+      }
+    }
+
+    // Update manifest
+    this.manifest.entries = toKeep
+    this.manifest.totalSizeBytes = toKeep.reduce((sum, e) => sum + e.sizeBytes, 0)
+    this.manifest.lastUpdated = Date.now()
+    await this.saveManifest()
+
+    return {
+      pruned: deletedBackupIds.length,
+      remaining: toKeep.length,
+      deletedBackupIds,
+    }
+  }
+
+  // ===========================================================================
+  // Statistics
+  // ===========================================================================
+
+  /** Returns a snapshot of backup statistics */
+  getStats(): BackupStats {
+    return { ...this.stats }
+  }
+
+  /** Resets all backup statistics to zero */
+  resetStats(): void {
+    this.stats = this.createEmptyStats()
+  }
+
+  /** Returns the current incremental backup chain state, or null if no full backup exists */
+  getIncrementalState(): IncrementalBackupState | null {
+    return this.incrementalState ? { ...this.incrementalState } : null
+  }
+
+  // ===========================================================================
+  // Private Helpers
+  // ===========================================================================
+
+  /** Returns the R2 key for the manifest file */
+  private getManifestKey(): string {
+    return `${this.config.prefix}${this.config.doId}/manifest.json`
+  }
+
+  /** Persists the current manifest to R2 */
+  private async saveManifest(): Promise<void> {
+    const manifestData = JSON.stringify(this.manifest)
+    await this.config.bucket.put(this.getManifestKey(), manifestData, {
+      customMetadata: { type: 'manifest', doId: this.config.doId },
+    })
+  }
+
+  /** Builds the parent chain of backup IDs from the base full backup to the given ID */
+  private buildParentChain(baseBackupId: string): string[] {
+    const chain: string[] = []
+    let currentId: string | undefined = baseBackupId
+
+    while (currentId) {
+      chain.unshift(currentId)
+      const entry = this.manifest.entries.find((e) => e.backupId === currentId)
+      if (!entry || entry.type === 'full') break
+      currentId = entry.baseBackupId
+    }
+
+    return chain
+  }
+
+  /** Gets the ordered chain of backup entries needed to restore to the given backup ID */
+  private getRestoreChain(backupId: string): BackupEntry[] {
+    const chain: BackupEntry[] = []
+    let currentId: string | undefined = backupId
+
+    while (currentId) {
+      const entry = this.manifest.entries.find((e) => e.backupId === currentId)
+      if (!entry) break
+      chain.unshift(entry)
+      if (entry.type === 'full') break
+      currentId = entry.baseBackupId
+    }
+
+    return chain
+  }
+
+  /** Updates aggregate statistics after a backup operation completes */
+  private updateStats(
+    success: boolean,
+    sizeBytes: number,
+    durationMs: number,
+    type: 'full' | 'incremental'
+  ): void {
+    this.stats.totalBackups++
+
+    if (success) {
+      this.stats.successCount++
+      this.stats.totalSizeBytes += sizeBytes
+      this.stats.lastBackupTimestamp = Date.now()
+    } else {
+      this.stats.failureCount++
+    }
+
+    if (type === 'full') {
+      this.stats.fullBackupCount++
+    } else {
+      this.stats.incrementalBackupCount++
+    }
+
+    // Compute running average of duration using incremental formula
+    const previousTotal = this.stats.avgDurationMs * (this.stats.totalBackups - 1)
+    this.stats.avgDurationMs = (previousTotal + durationMs) / this.stats.totalBackups
+  }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+/** Creates a BackupManager instance, validating required configuration */
+export function createBackupManager(config: BackupConfig): BackupManager {
+  if (!config.bucket) {
+    throw new Error('BackupManager requires a valid R2 bucket')
+  }
+  if (!config.doId) {
+    throw new Error('BackupManager requires a non-empty doId')
+  }
+  return new BackupManager(config)
+}