@dotdo/postgres 0.1.0

package/dist/migrations/progress-tracker-kv.js

@@ -0,0 +1,231 @@
+/**
+ * KV-based Progress Storage
+ *
+ * Production storage implementation using Cloudflare Workers KV
+ * for migration progress tracking across Durable Objects.
+ *
+ * @module migrations/progress-tracker-kv
+ */
+/**
+ * KV-based progress storage implementation
+ *
+ * Uses Cloudflare Workers KV to store migration progress data.
+ * Keys are structured as:
+ * - {prefix}:op:{migrationId} - Operation metadata
+ * - {prefix}:do:{migrationId}:{doId} - DO progress
+ * - {prefix}:index:{migrationId}:{status} - Status indexes for filtering
+ *
+ * @example
+ * ```typescript
+ * const storage = new KVProgressStorage({
+ *   kv: env.MIGRATION_PROGRESS_KV,
+ *   prefix: 'migration_progress',
+ *   expirationTtl: 604800, // 7 days
+ * })
+ *
+ * const tracker = createProgressTracker({ storage })
+ * ```
+ */
+export class KVProgressStorage {
+    kv;
+    prefix;
+    expirationTtl;
+    constructor(config) {
+        this.kv = config.kv;
+        this.prefix = config.prefix ?? 'migration_progress';
+        this.expirationTtl = config.expirationTtl ?? 604800; // 7 days default
+    }
+    /**
+     * Generate key for operation metadata
+     */
+    operationKey(migrationId) {
+        return `${this.prefix}:op:${migrationId}`;
+    }
+    /**
+     * Generate key for DO progress
+     */
+    doProgressKey(migrationId, doId) {
+        return `${this.prefix}:do:${migrationId}:${doId}`;
+    }
+    /**
+     * Generate key for DO list
+     */
+    doListKey(migrationId) {
+        return `${this.prefix}:do_list:${migrationId}`;
+    }
+    /**
+     * Generate key for status index
+     */
+    statusIndexKey(migrationId, status) {
+        return `${this.prefix}:index:${migrationId}:${status}`;
+    }
+    /**
+     * Generate key prefix for listing operations
+     */
+    operationListPrefix() {
+        return `${this.prefix}:op:`;
+    }
+    async setOperation(migrationId, operation) {
+        const key = this.operationKey(migrationId);
+        const value = JSON.stringify(operation);
+        // Set expiration for completed/failed operations
+        const shouldExpire = operation.status === 'completed' || operation.status === 'failed';
+        await this.kv.put(key, value, shouldExpire ? { expirationTtl: this.expirationTtl } : {});
+    }
+    async getOperation(migrationId) {
+        const key = this.operationKey(migrationId);
+        const value = await this.kv.get(key, 'text');
+        if (!value) {
+            return null;
+        }
+        return JSON.parse(value);
+    }
+    async setDOProgress(migrationId, doId, progress) {
+        const key = this.doProgressKey(migrationId, doId);
+        const value = JSON.stringify(progress);
+        await this.kv.put(key, value);
+        // Update status index
+        await this.updateStatusIndex(migrationId, doId, progress.status);
+        // Add to DO list if not present
+        await this.addToDOList(migrationId, doId);
+    }
+    async getDOProgress(migrationId, doId) {
+        const key = this.doProgressKey(migrationId, doId);
+        const value = await this.kv.get(key, 'text');
+        if (!value) {
+            return null;
+        }
+        return JSON.parse(value);
+    }
+    async getAllDOProgress(migrationId) {
+        // Get list of all DO IDs for this migration
+        const doIds = await this.getDOList(migrationId);
+        if (doIds.length === 0) {
+            return [];
+        }
+        // Fetch all progress states in parallel
+        const progressPromises = doIds.map((doId) => this.getDOProgress(migrationId, doId));
+        const results = await Promise.all(progressPromises);
+        // Filter out nulls (shouldn't happen but be safe)
+        return results.filter((p) => p !== null);
+    }
+    async getDOProgressByStatus(migrationId, status) {
+        // Get DO IDs from status index
+        const indexKey = this.statusIndexKey(migrationId, status);
+        const indexValue = await this.kv.get(indexKey, 'text');
+        if (!indexValue) {
+            return [];
+        }
+        const doIds = JSON.parse(indexValue);
+        // Fetch progress for all DOs in parallel
+        const progressPromises = doIds.map((doId) => this.getDOProgress(migrationId, doId));
+        const results = await Promise.all(progressPromises);
+        // Filter out nulls and verify status (in case of stale index)
+        return results.filter((p) => p !== null && p.status === status);
+    }
+    async deleteOperation(migrationId) {
+        // Delete operation metadata
+        await this.kv.delete(this.operationKey(migrationId));
+        // Get all DO IDs and delete their progress
+        const doIds = await this.getDOList(migrationId);
+        const deletePromises = [];
+        // Delete all DO progress
+        for (const doId of doIds) {
+            deletePromises.push(this.kv.delete(this.doProgressKey(migrationId, doId)));
+        }
+        // Delete all status indexes
+        const statuses = ['pending', 'running', 'completed', 'failed', 'skipped'];
+        for (const status of statuses) {
+            deletePromises.push(this.kv.delete(this.statusIndexKey(migrationId, status)));
+        }
+        // Delete DO list
+        deletePromises.push(this.kv.delete(this.doListKey(migrationId)));
+        await Promise.all(deletePromises);
+    }
+    async listOperations() {
+        // List all operation keys
+        const prefix = this.operationListPrefix();
+        const list = await this.kv.list({ prefix });
+        if (list.keys.length === 0) {
+            return [];
+        }
+        // Fetch all operations in parallel
+        const operationPromises = list.keys.map((key) => this.kv.get(key.name, 'text'));
+        const results = await Promise.all(operationPromises);
+        // Parse and filter nulls
+        return results
+            .filter((value) => value !== null)
+            .map((value) => JSON.parse(value));
+    }
+    /**
+     * Update status index when DO status changes
+     */
+    async updateStatusIndex(migrationId, doId, newStatus) {
+        const statuses = ['pending', 'running', 'completed', 'failed', 'skipped'];
+        // Remove from all other status indexes and add to new one
+        const updatePromises = statuses.map(async (status) => {
+            const indexKey = this.statusIndexKey(migrationId, status);
+            const indexValue = await this.kv.get(indexKey, 'text');
+            let doIds = indexValue ? JSON.parse(indexValue) : [];
+            if (status === newStatus) {
+                // Add to this index if not present
+                if (!doIds.includes(doId)) {
+                    doIds.push(doId);
+                    await this.kv.put(indexKey, JSON.stringify(doIds));
+                }
+            }
+            else {
+                // Remove from this index if present
+                if (doIds.includes(doId)) {
+                    doIds = doIds.filter((id) => id !== doId);
+                    if (doIds.length > 0) {
+                        await this.kv.put(indexKey, JSON.stringify(doIds));
+                    }
+                    else {
+                        await this.kv.delete(indexKey);
+                    }
+                }
+            }
+        });
+        await Promise.all(updatePromises);
+    }
+    /**
+     * Add DO to the DO list for a migration
+     */
+    async addToDOList(migrationId, doId) {
+        const listKey = this.doListKey(migrationId);
+        const listValue = await this.kv.get(listKey, 'text');
+        let doIds = listValue ? JSON.parse(listValue) : [];
+        if (!doIds.includes(doId)) {
+            doIds.push(doId);
+            await this.kv.put(listKey, JSON.stringify(doIds));
+        }
+    }
+    /**
+     * Get list of all DO IDs for a migration
+     */
+    async getDOList(migrationId) {
+        const listKey = this.doListKey(migrationId);
+        const listValue = await this.kv.get(listKey, 'text');
+        return listValue ? JSON.parse(listValue) : [];
+    }
+}
+/**
+ * Create a KV-based progress storage instance
+ *
+ * @param config KV storage configuration
+ * @returns Configured KV progress storage
+ *
+ * @example
+ * ```typescript
+ * const storage = createKVProgressStorage({
+ *   kv: env.MIGRATION_PROGRESS_KV,
+ *   prefix: 'migrations',
+ *   expirationTtl: 604800, // 7 days
+ * })
+ * ```
+ */
+export function createKVProgressStorage(config) {
+    return new KVProgressStorage(config);
+}
+//# sourceMappingURL=progress-tracker-kv.js.map

package/dist/migrations/progress-tracker-kv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-tracker-kv.js","sourceRoot":"","sources":["../../src/migrations/progress-tracker-kv.ts"],"names":[],"mappings":"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"}

package/dist/migrations/progress-tracker.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Migration Progress Tracker
+ *
+ * Tracks migration progress across thousands of Durable Objects.
+ * Provides centralized progress reporting, pause/resume capabilities,
+ * and aggregate statistics.
+ *
+ * @module migrations/progress-tracker
+ */
+export type { MigrationStatus } from './types';
+/**
+ * Status of a migration operation across multiple DOs
+ */
+export type MigrationOperationStatus = 'pending' | 'running' | 'paused' | 'completed' | 'failed';
+/**
+ * Status of an individual DO's migration
+ */
+export type DOMigrationStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+/**
+ * Progress state for a single DO
+ */
+export interface DOProgressState {
+    /** Durable Object ID */
+    doId: string;
+    /** Current migration status */
+    status: DOMigrationStatus;
+    /** Current migration version being applied */
+    currentVersion: number | null;
+    /** Target version to migrate to */
+    targetVersion: number;
+    /** Number of migrations completed */
+    migrationsCompleted: number;
+    /** Total migrations to apply */
+    totalMigrations: number;
+    /** Last error message if failed */
+    error?: string;
+    /** When this DO started migrating */
+    startedAt?: string;
+    /** When this DO completed/failed */
+    completedAt?: string;
+    /** Total execution time in milliseconds */
+    executionTimeMs?: number;
+}
+/**
+ * Aggregate progress statistics
+ */
+export interface ProgressStats {
+    /** Total number of DOs being migrated */
+    total: number;
+    /** Number of DOs that haven't started */
+    pending: number;
+    /** Number of DOs currently migrating */
+    running: number;
+    /** Number of DOs that completed successfully */
+    completed: number;
+    /** Number of DOs that failed */
+    failed: number;
+    /** Number of DOs that were skipped */
+    skipped: number;
+    /** Overall completion percentage (0-100) */
+    percentComplete: number;
+    /** Estimated time remaining in milliseconds (null if not available) */
+    estimatedTimeRemainingMs: number | null;
+    /** Average execution time per DO in milliseconds */
+    avgExecutionTimeMs: number;
+}
+/**
+ * Migration operation record
+ */
+export interface MigrationOperation {
+    /** Unique migration operation ID */
+    migrationId: string;
+    /** Target schema version */
+    targetVersion: number;
+    /** Overall operation status */
+    status: MigrationOperationStatus;
+    /** Total DOs to migrate */
+    totalDOs: number;
+    /** When the operation started */
+    startedAt: string;
+    /** When the operation completed/failed (if applicable) */
+    completedAt?: string;
+    /** User/system that initiated the operation */
+    initiatedBy?: string;
+    /** Optional description/reason */
+    description?: string;
+    /** Progress statistics */
+    stats: ProgressStats;
+}
+/**
+ * Storage interface for progress tracking
+ *
+ * Implementations can use Durable Object storage, KV, or other backends
+ */
+export interface ProgressStorage {
+    /**
+     * Store migration operation metadata
+     */
+    setOperation(migrationId: string, operation: MigrationOperation): Promise<void>;
+    /**
+     * Get migration operation metadata
+     */
+    getOperation(migrationId: string): Promise<MigrationOperation | null>;
+    /**
+     * Store DO progress state
+     */
+    setDOProgress(migrationId: string, doId: string, progress: DOProgressState): Promise<void>;
+    /**
+     * Get DO progress state
+     */
+    getDOProgress(migrationId: string, doId: string): Promise<DOProgressState | null>;
+    /**
+     * Get all DO progress states for a migration
+     */
+    getAllDOProgress(migrationId: string): Promise<DOProgressState[]>;
+    /**
+     * Get DO progress states by status
+     */
+    getDOProgressByStatus(migrationId: string, status: DOMigrationStatus): Promise<DOProgressState[]>;
+    /**
+     * Delete migration operation and all associated progress
+     */
+    deleteOperation(migrationId: string): Promise<void>;
+    /**
+     * List all migration operations
+     */
+    listOperations(): Promise<MigrationOperation[]>;
+}
+/**
+ * In-memory storage implementation (for testing/single-instance use)
+ */
+export declare class InMemoryProgressStorage implements ProgressStorage {
+    private operations;
+    private doProgress;
+    setOperation(migrationId: string, operation: MigrationOperation): Promise<void>;
+    getOperation(migrationId: string): Promise<MigrationOperation | null>;
+    setDOProgress(migrationId: string, doId: string, progress: DOProgressState): Promise<void>;
+    getDOProgress(migrationId: string, doId: string): Promise<DOProgressState | null>;
+    getAllDOProgress(migrationId: string): Promise<DOProgressState[]>;
+    getDOProgressByStatus(migrationId: string, status: DOMigrationStatus): Promise<DOProgressState[]>;
+    deleteOperation(migrationId: string): Promise<void>;
+    listOperations(): Promise<MigrationOperation[]>;
+    /**
+     * Clear all data (useful for testing)
+     */
+    clear(): void;
+}
+/**
+ * Configuration for the progress tracker
+ */
+export interface ProgressTrackerConfig {
+    /** Storage backend for progress data */
+    storage: ProgressStorage;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Migration Progress Tracker
+ *
+ * Tracks migration progress across many Durable Objects, providing
+ * aggregate statistics and pause/resume capabilities.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new MigrationProgressTracker({
+ *   storage: new InMemoryProgressStorage(),
+ * })
+ *
+ * // Start tracking a migration
+ * await tracker.startMigration('migration-2024-01', [
+ *   'do-1', 'do-2', 'do-3'
+ * ], 5)
+ *
+ * // Report progress from individual DOs
+ * await tracker.reportProgress('migration-2024-01', {
+ *   doId: 'do-1',
+ *   status: 'running',
+ *   currentVersion: 3,
+ *   targetVersion: 5,
+ *   migrationsCompleted: 3,
+ *   totalMigrations: 5,
+ * })
+ *
+ * // Get overall progress
+ * const progress = await tracker.getProgress('migration-2024-01')
+ * console.log(`${progress.stats.percentComplete}% complete`)
+ * ```
+ */
+export declare class MigrationProgressTracker {
+    private storage;
+    private debug;
+    constructor(config: ProgressTrackerConfig);
+    /**
+     * Log debug message
+     */
+    private log;
+    /**
+     * Calculate progress statistics
+     */
+    private calculateStats;
+    /**
+     * Start tracking a migration operation
+     *
+     * @param migrationId Unique identifier for this migration operation
+     * @param doIds Array of Durable Object IDs to migrate
+     * @param targetVersion Target schema version
+     * @param options Optional operation metadata
+     * @returns The created migration operation
+     */
+    startMigration(migrationId: string, doIds: string[], targetVersion: number, options?: {
+        initiatedBy?: string;
+        description?: string;
+    }): Promise<MigrationOperation>;
+    /**
+     * Report progress for a specific DO
+     *
+     * @param migrationId Migration operation ID
+     * @param progress Progress update for a DO
+     */
+    reportProgress(migrationId: string, progress: Partial<DOProgressState> & {
+        doId: string;
+    }): Promise<void>;
+    /**
+     * Get overall progress for a migration operation
+     *
+     * @param migrationId Migration operation ID
+     * @returns Migration operation with current stats
+     */
+    getProgress(migrationId: string): Promise<MigrationOperation>;
+    /**
+     * Get DOs that are still pending migration
+     *
+     * @param migrationId Migration operation ID
+     * @returns Array of DO IDs that haven't started migration
+     */
+    getPendingDOs(migrationId: string): Promise<string[]>;
+    /**
+     * Get DOs that are currently running migration
+     *
+     * @param migrationId Migration operation ID
+     * @returns Array of DO IDs currently migrating
+     */
+    getRunningDOs(migrationId: string): Promise<string[]>;
+    /**
+     * Get DOs that failed migration
+     *
+     * @param migrationId Migration operation ID
+     * @returns Array of progress states for failed DOs
+     */
+    getFailedDOs(migrationId: string): Promise<DOProgressState[]>;
+    /**
+     * Get progress for a specific DO
+     *
+     * @param migrationId Migration operation ID
+     * @param doId Durable Object ID
+     * @returns Progress state for the DO
+     */
+    getDOProgress(migrationId: string, doId: string): Promise<DOProgressState | null>;
+    /**
+     * Pause a migration operation
+     *
+     * This doesn't stop in-flight migrations but marks the operation as paused,
+     * preventing new migrations from starting.
+     *
+     * @param migrationId Migration operation ID
+     */
+    pauseMigration(migrationId: string): Promise<void>;
+    /**
+     * Resume a paused migration operation
+     *
+     * @param migrationId Migration operation ID
+     */
+    resumeMigration(migrationId: string): Promise<void>;
+    /**
+     * Cancel a migration operation
+     *
+     * This marks the operation as failed and stops tracking.
+     * It doesn't rollback any completed migrations.
+     *
+     * @param migrationId Migration operation ID
+     */
+    cancelMigration(migrationId: string): Promise<void>;
+    /**
+     * Delete a migration operation and all progress data
+     *
+     * @param migrationId Migration operation ID
+     */
+    deleteMigration(migrationId: string): Promise<void>;
+    /**
+     * List all migration operations
+     *
+     * @returns Array of all migration operations
+     */
+    listMigrations(): Promise<MigrationOperation[]>;
+    /**
+     * Retry failed DOs in a migration operation
+     *
+     * Resets failed DOs to pending status so they can be retried.
+     *
+     * @param migrationId Migration operation ID
+     * @returns Number of DOs reset to pending
+     */
+    retryFailedDOs(migrationId: string): Promise<number>;
+}
+/**
+ * Create a migration progress tracker
+ *
+ * @param config Progress tracker configuration
+ * @returns Configured progress tracker instance
+ *
+ * @example
+ * ```typescript
+ * const tracker = createProgressTracker({
+ *   storage: new InMemoryProgressStorage(),
+ *   debug: true,
+ * })
+ * ```
+ */
+export declare function createProgressTracker(config: ProgressTrackerConfig): MigrationProgressTracker;
+//# sourceMappingURL=progress-tracker.d.ts.map

package/dist/migrations/progress-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-tracker.d.ts","sourceRoot":"","sources":["../../src/migrations/progress-tracker.ts"],"names":[],"mappings":"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"}