@dotdo/postgres 0.1.0

package/dist/migrations/index.js

@@ -0,0 +1,127 @@
+/**
+ * Migration System for postgres.do
+ *
+ * A complete migration system designed for postgres.do's unique multi-database
+ * model where each user gets their own Durable Object database.
+ *
+ * Key Features:
+ * - **Auto-migration on first connection**: Each DO database is automatically
+ *   migrated to the latest schema version on first access.
+ * - **Drizzle ORM compatibility**: Works with Drizzle-generated migrations
+ *   and exports Drizzle-compatible schemas.
+ * - **Schema version tracking**: Each DO instance tracks its own schema version.
+ * - **Concurrent migration safety**: Advisory locks prevent race conditions.
+ * - **Rollback support**: Full support for down migrations.
+ * - **Type-safe schema generation**: Generate TypeScript types from schema.
+ *
+ * @module migrations
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import {
+ *   createMigrationRegistry,
+ *   createAutoMigrator,
+ *   defineMigration,
+ * } from '@dotdo/postgres/migrations'
+ *
+ * // Define migrations
+ * const migrations = [
+ *   defineMigration({
+ *     id: '0001_create_users',
+ *     name: 'Create users table',
+ *     version: 1,
+ *     up: `
+ *       CREATE TABLE users (
+ *         id SERIAL PRIMARY KEY,
+ *         email TEXT NOT NULL UNIQUE,
+ *         created_at TIMESTAMP DEFAULT NOW()
+ *       );
+ *     `,
+ *     down: `
+ *       DROP TABLE users;
+ *     `,
+ *   }),
+ * ]
+ *
+ * // Create auto-migrator for DO
+ * const migrator = createAutoMigrator({ migrations })
+ *
+ * // In your DO
+ * class PostgresDO {
+ *   async fetch(request: Request) {
+ *     await migrator.ensureMigrated(this.pglite)
+ *     // Handle request...
+ *   }
+ * }
+ * ```
+ *
+ * @example Drizzle Integration
+ * ```typescript
+ * import {
+ *   loadBundledDrizzleMigrations,
+ *   createAutoMigrator,
+ * } from '@dotdo/postgres/migrations'
+ *
+ * // Load Drizzle migrations bundled at build time
+ * import bundledMigrations from './drizzle-bundle'
+ *
+ * const migrations = loadBundledDrizzleMigrations(bundledMigrations)
+ * const migrator = createAutoMigrator({ migrations })
+ * ```
+ *
+ * @example Type Generation
+ * ```typescript
+ * import { generateSchemaTypes } from '@dotdo/postgres/migrations'
+ *
+ * const types = await generateSchemaTypes(pglite)
+ * console.log(types)
+ * // interface Users {
+ * //   id: number;
+ * //   email: string;
+ * //   created_at: Date | null;
+ * // }
+ * ```
+ */
+// ============================================================================
+// Registry
+// ============================================================================
+export { MigrationRegistry, MigrationValidationError, createMigrationRegistry, defineMigration, combineMigrations, createMigrationFromDrizzle, } from './registry';
+// ============================================================================
+// Runner
+// ============================================================================
+export { MigrationRunner, MigrationError, createMigrationRunner, } from './runner';
+// ============================================================================
+// Auto-Migrator
+// ============================================================================
+export { AutoMigrator, createAutoMigrator, withAutoMigration, } from './auto-migrator';
+// ============================================================================
+// Drizzle Compatibility
+// ============================================================================
+export { parseDrizzleJournal, convertDrizzleEntry, loadDrizzleMigrations, loadBundledDrizzleMigrations, generateDrizzleMigrationId, generateDrizzleJournalEntry, createDrizzleMigration, exportToDrizzleFormat, validateDrizzleCompatibility, } from './drizzle-compat';
+// ============================================================================
+// Schema Generator
+// ============================================================================
+export { pgTypeToTs, introspectSchema, generateTableInterface, generateSchemaTypes, } from './schema-generator';
+// ============================================================================
+// Validator
+// ============================================================================
+export { MigrationValidator, createMigrationValidator, validateMigration, validateMigrations, } from './validator';
+// ============================================================================
+// Compatibility Validation
+// ============================================================================
+export { SchemaCompatibilityValidator, createCompatibilityValidator, validateCompatibility, isBackwardCompatible, getSafeChanges, getBreakingChanges, } from './compatibility';
+// ============================================================================
+// Bulk Orchestration
+// ============================================================================
+export { BulkMigrationOrchestrator, createBulkMigrationOrchestrator, InMemoryBulkMigrationStorage, } from './bulk-orchestrator';
+// ============================================================================
+// Testing
+// ============================================================================
+export { createTestDatabase, createTestContext, testMigration, verifyMigrationSequence, testRollbackSequence, assertTableExists, assertTableNotExists, assertTableHasColumns, assertIndexExists, assertRowCount, createMockExecutor, } from './testing';
+// ============================================================================
+// Progress Tracker
+// ============================================================================
+export { MigrationProgressTracker, InMemoryProgressStorage, createProgressTracker, } from './progress-tracker';
+export { KVProgressStorage, createKVProgressStorage, } from './progress-tracker-kv';
+export { ProgressTrackerDO, DOProgressStorageClient, createDOProgressStorage, } from './progress-tracker-do';
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AA8CH,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,YAAY,CAAA;AAInB,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,OAAO,EACL,eAAe,EACf,cAAc,EACd,qBAAqB,GACtB,MAAM,UAAU,CAAA;AAEjB,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,iBAAiB,CAAA;AAOxB,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,sBAAsB,EACtB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,kBAAkB,CAAA;AAIzB,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAS3B,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAYpB,+EAA+E;AAC/E,2BAA2B;AAC3B,+EAA+E;AAE/E,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,GACnB,MAAM,iBAAiB,CAAA;AASxB,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,qBAAqB,CAAA;AAa5B,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,GACnB,MAAM,WAAW,CAAA;AAalB,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,oBAAoB,CAAA;AAY3B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA;AAM9B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA"}

package/dist/migrations/migration-api.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Migration Dashboard API
+ *
+ * HTTP API endpoints for migration progress tracking and dashboard.
+ * Provides programmatic access to migration status across Durable Objects.
+ *
+ * @module migrations/migration-api
+ */
+import type { MigrationProgressTracker, DOProgressState } from './progress-tracker';
+/**
+ * Migration status summary response
+ */
+export interface MigrationStatusResponse {
+    /** Total number of DOs */
+    totalDOs: number;
+    /** Distribution of DOs by version */
+    versionDistribution: Record<string, number>;
+    /** Number of failed migrations */
+    failedMigrations: number;
+    /** Migration velocity (DOs per hour) */
+    migrationVelocity: number;
+    /** Current target version */
+    currentVersion: number;
+    /** Last updated timestamp */
+    lastUpdated: string;
+    /** Count of pending DOs */
+    pendingCount: number;
+    /** Count of running DOs */
+    runningCount: number;
+    /** Count of completed DOs */
+    completedCount: number;
+    /** Count of skipped DOs */
+    skippedCount: number;
+    /** Estimated time remaining in milliseconds */
+    estimatedTimeRemainingMs: number | null;
+    /** Average execution time per DO in milliseconds */
+    avgExecutionTimeMs: number;
+}
+/**
+ * DO status information
+ */
+export interface DOStatusResponse {
+    /** Durable Object ID */
+    doId: string;
+    /** Current schema version */
+    version: number;
+    /** Migration status */
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+    /** Last migration attempt timestamp */
+    lastAttempt?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Failed migration details
+ */
+export interface FailedMigrationResponse {
+    /** Durable Object ID */
+    doId: string;
+    /** Error message */
+    error: string;
+    /** Version at which migration failed */
+    version: number;
+    /** Timestamp when migration failed */
+    failedAt: string;
+}
+/**
+ * Alert threshold configuration
+ */
+export interface AlertThresholds {
+    /** Alert when failure rate exceeds this percentage (0-100) */
+    failureRatePercent?: number;
+    /** Alert when velocity drops below this value (DOs/hour) */
+    minVelocity?: number;
+    /** Alert when DOs are stuck at old version for this many hours */
+    stuckVersionHours?: number;
+}
+/**
+ * Alert status
+ */
+export interface AlertStatus {
+    /** Whether any alerts are active */
+    hasActiveAlerts: boolean;
+    /** List of active alerts */
+    alerts: Array<{
+        type: 'failure_rate' | 'low_velocity' | 'stuck_version';
+        message: string;
+        severity: 'warning' | 'critical';
+        triggeredAt: string;
+    }>;
+}
+/**
+ * Webhook configuration for alerts
+ */
+export interface WebhookConfig {
+    /** Webhook URL to call */
+    url: string;
+    /** HTTP method (default: POST) */
+    method?: 'POST' | 'PUT';
+    /** Additional headers */
+    headers?: Record<string, string>;
+    /** Alert types to send to this webhook */
+    alertTypes?: Array<'failure_rate' | 'low_velocity' | 'stuck_version'>;
+}
+/**
+ * Migration API handler options
+ */
+export interface MigrationAPIOptions {
+    /** Progress tracker instance */
+    tracker: MigrationProgressTracker;
+    /** Alert thresholds */
+    alertThresholds?: AlertThresholds;
+    /** Webhook configurations */
+    webhooks?: WebhookConfig[];
+    /** Enable CORS */
+    enableCors?: boolean;
+    /** Allowed origins for CORS */
+    allowedOrigins?: string[];
+}
+/**
+ * Build version distribution from DO progress states
+ * Exported for potential future use in version tracking queries
+ */
+export declare function buildVersionDistribution(doStates: DOProgressState[]): Record<string, number>;
+/**
+ * Create migration API handler
+ *
+ * Returns a fetch handler that can be used in a Cloudflare Worker
+ * to serve migration dashboard API endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { createMigrationAPI } from '@dotdo/postgres/migrations'
+ *
+ * const tracker = createProgressTracker({ storage })
+ * const api = createMigrationAPI({ tracker })
+ *
+ * export default {
+ *   async fetch(request: Request) {
+ *     const url = new URL(request.url)
+ *
+ *     if (url.pathname.startsWith('/api/migrations')) {
+ *       return api.fetch(request)
+ *     }
+ *
+ *     // ... other routes
+ *   }
+ * }
+ * ```
+ */
+export declare function createMigrationAPI(options: MigrationAPIOptions): {
+    /**
+     * Handle incoming requests
+     */
+    fetch(request: Request): Promise<Response>;
+};
+/**
+ * Type exports for external use
+ */
+export type { MigrationStatusResponse as MigrationStatus, DOStatusResponse as DOStatus, FailedMigrationResponse as FailedMigration, };
+//# sourceMappingURL=migration-api.d.ts.map

package/dist/migrations/migration-api.d.ts.map

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