@dotdo/postgres 0.1.0 → 0.1.2

package/dist/backup/backup-manager.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Automated Backup Manager for PostgreSQL Durable Objects
+ *
+ * Provides scheduled full and incremental backups to R2 storage,
+ * backup manifest management, restore capabilities, and retention policies.
+ */
+/** 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>[];
+    }>;
+}
+/**
+ * Manages automated backups (full and incremental) of PostgreSQL Durable Objects to R2 storage.
+ * Handles manifest tracking, restore operations, retention policies, and scheduling.
+ */
+export declare class BackupManager {
+    private config;
+    private manifest;
+    private stats;
+    private incrementalState;
+    private backupInProgress;
+    private lastFullBackupTime;
+    private backupSequence;
+    constructor(config: BackupConfig);
+    private createEmptyManifest;
+    private createEmptyStats;
+    /**
+     * Creates a full backup of the database, serializing table data and uploading to R2.
+     * Only one backup operation can run at a time.
+     */
+    createFullBackup(pglite: PGLiteInstance): Promise<BackupResult>;
+    /** Stores the last failure result for internal signaling between helper methods */
+    private lastFailureResult;
+    /** 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 queryUserTables;
+    /** Applies compression if configured, returning the final data and compression flag */
+    private applyCompression;
+    /** Builds the R2 object key for a backup */
+    private buildR2Key;
+    /**
+     * Uploads data to R2 with a microtask-based timeout to detect hung operations.
+     * Returns true on success, false on failure (sets lastUploadError).
+     */
+    private uploadWithTimeout;
+    /** Adds an entry to the manifest and updates aggregate metadata */
+    private addManifestEntry;
+    /**
+     * Creates an incremental backup capturing changes since the last backup.
+     * Requires a prior full backup to establish the incremental chain.
+     */
+    createIncrementalBackup(pglite: PGLiteInstance): Promise<BackupResult>;
+    /** Fetches the current WAL LSN from PGLite, falling back to a simulated value */
+    private getCurrentLsn;
+    /**
+     * Restores the database from a specific backup, applying the full incremental chain if necessary.
+     * Supports checksum validation and progress reporting via options.
+     */
+    restoreFromBackup(backupId: string, _pglite: PGLiteInstance, options?: RestoreOptions): Promise<RestoreResult>;
+    /** Checks if a backup exists in R2 under either the full or incremental prefix */
+    private backupExistsInR2;
+    /** Creates a standardized failed RestoreResult */
+    private createFailedRestoreResult;
+    /** Restores a single backup entry, validating its checksum if required */
+    private restoreAndValidateEntry;
+    /** Verifies that the checksum of the given data matches the expected value */
+    private verifyChecksum;
+    /** Restores from the most recent backup in the manifest */
+    restoreFromLatest(pglite: PGLiteInstance): Promise<RestoreResult>;
+    /** Retrieves the backup manifest, loading from R2 if no local entries exist */
+    getManifest(): Promise<BackupManifest>;
+    /** Validates the manifest by checking R2 or local state for parseable data */
+    validateManifest(): Promise<boolean>;
+    /** Returns a copy of all backup entries in the manifest */
+    listBackups(): Promise<BackupEntry[]>;
+    /** Verifies that a backup exists in R2 by checking its object head */
+    verifyBackup(backupId: string): Promise<boolean>;
+    /** Returns the timestamp for the next scheduled backup */
+    getNextBackupTime(): number;
+    /** Determines whether a full backup is required based on the configured interval */
+    needsFullBackup(): boolean;
+    /** Returns the type of backup to create on the next scheduled execution */
+    getScheduledBackupType(): 'full' | 'incremental';
+    /** Handles a Durable Object alarm, creating the appropriate backup type */
+    handleAlarm(pglite: PGLiteInstance): Promise<AlarmResult>;
+    /** Returns the current backup schedule configuration, or defaults */
+    getSchedule(): BackupSchedule;
+    /** Prunes old backups according to the retention policy, preserving minimum full backups */
+    pruneBackups(): Promise<PruneResult>;
+    /** Returns a snapshot of backup statistics */
+    getStats(): BackupStats;
+    /** Resets all backup statistics to zero */
+    resetStats(): void;
+    /** Returns the current incremental backup chain state, or null if no full backup exists */
+    getIncrementalState(): IncrementalBackupState | null;
+    /** Returns the R2 key for the manifest file */
+    private getManifestKey;
+    /** Persists the current manifest to R2 */
+    private saveManifest;
+    /** Builds the parent chain of backup IDs from the base full backup to the given ID */
+    private buildParentChain;
+    /** Gets the ordered chain of backup entries needed to restore to the given backup ID */
+    private getRestoreChain;
+    /** Updates aggregate statistics after a backup operation completes */
+    private updateStats;
+}
+/** Creates a BackupManager instance, validating required configuration */
+export declare function createBackupManager(config: BackupConfig): BackupManager;
+export {};
+//# sourceMappingURL=backup-manager.d.ts.map

package/dist/backup/backup-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-manager.d.ts","sourceRoot":"","sources":["../../src/backup/backup-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqCH,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,MAAM,EAAE,QAAQ,CAAA;IAChB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAA;IACd,sCAAsC;IACtC,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,qBAAqB,CAAA;IACjC,oDAAoD;IACpD,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,KAAK,CAAA;IAC/C,wDAAwD;IACxD,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,IAAI,EAAE,MAAM,GAAG,aAAa,CAAA;IAC5B,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,2DAA2D;AAC3D,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAA;IAClB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAA;IAClB,wDAAwD;IACxD,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,GAAG,aAAa,CAAA;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,GAAG,aAAa,CAAA;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAA;IAChB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,EAAE,MAAM,CAAA;IACtB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,MAAM,CAAA;IACvB,sBAAsB,EAAE,MAAM,CAAA;CAC/B;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;CACnD;AAED,uDAAuD;AACvD,UAAU,oBAAoB;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,UAAU,WAAW;IACnB,aAAa,EAAE,OAAO,CAAA;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,CAAA;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED;;;GAGG;AACH,UAAU,cAAc;IACtB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;KAAE,CAAC,CAAA;CACjE;AA8DD;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,gBAAgB,CAAsC;IAC9D,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,kBAAkB,CAAI;IAC9B,OAAO,CAAC,cAAc,CAAI;gBAEd,MAAM,EAAE,YAAY;IAMhC,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,gBAAgB;IAiBxB;;;OAGG;IACG,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAgFrE,mFAAmF;IACnF,OAAO,CAAC,iBAAiB,CAA4B;IACrD,2CAA2C;IAC3C,OAAO,CAAC,eAAe,CAAK;IAE5B;;;OAGG;YACW,eAAe;IAmB7B,uFAAuF;IACvF,OAAO,CAAC,gBAAgB;IAOxB,4CAA4C;IAC5C,OAAO,CAAC,UAAU;IAIlB;;;OAGG;YACW,iBAAiB;IA6B/B,mEAAmE;YACrD,gBAAgB;IAa9B;;;OAGG;IACG,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAiF5E,iFAAiF;YACnE,aAAa;IAa3B;;;OAGG;IACG,iBAAiB,CACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC;IAuEzB,kFAAkF;YACpE,gBAAgB;IAO9B,kDAAkD;IAClD,OAAO,CAAC,yBAAyB;IASjC,0EAA0E;YAC5D,uBAAuB;IAsBrC,8EAA8E;YAChE,cAAc;IAK5B,2DAA2D;IACrD,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAiBvE,+EAA+E;IACzE,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC;IA4B5C,8EAA8E;IACxE,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAe1C,2DAA2D;IACrD,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAI3C,sEAAsE;IAChE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBtD,0DAA0D;IAC1D,iBAAiB,IAAI,MAAM;IAK3B,oFAAoF;IACpF,eAAe,IAAI,OAAO;IAM1B,2EAA2E;IAC3E,sBAAsB,IAAI,MAAM,GAAG,aAAa;IAKhD,2EAA2E;IACrE,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IAa/D,qEAAqE;IACrE,WAAW,IAAI,cAAc;IAQ7B,4FAA4F;IACtF,YAAY,IAAI,OAAO,CAAC,WAAW,CAAC;IA+E1C,8CAA8C;IAC9C,QAAQ,IAAI,WAAW;IAIvB,2CAA2C;IAC3C,UAAU,IAAI,IAAI;IAIlB,2FAA2F;IAC3F,mBAAmB,IAAI,sBAAsB,GAAG,IAAI;IAQpD,+CAA+C;IAC/C,OAAO,CAAC,cAAc;IAItB,0CAA0C;YAC5B,YAAY;IAO1B,sFAAsF;IACtF,OAAO,CAAC,gBAAgB;IAcxB,wFAAwF;IACxF,OAAO,CAAC,eAAe;IAevB,sEAAsE;IACtE,OAAO,CAAC,WAAW;CA0BpB;AAMD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,CAQvE"}