@dotdo/postgres 0.1.0

package/src/migrations/types.ts

@@ -0,0 +1,573 @@
+/**
+ * Migration System Types
+ *
+ * Type definitions for postgres.do's multi-database migration system.
+ * Designed to be compatible with Drizzle ORM while supporting the unique
+ * requirements of per-user Durable Object databases.
+ *
+ * @module migrations/types
+ */
+
+/**
+ * Migration status values
+ */
+export type MigrationStatus = 'pending' | 'applied' | 'failed' | 'rolled_back'
+
+/**
+ * Migration direction for execution
+ */
+export type MigrationDirection = 'up' | 'down'
+
+/**
+ * Individual migration record stored in the migrations table
+ */
+export interface MigrationRecord {
+  /** Migration identifier (e.g., '0001_initial') */
+  id: string
+  /** Human-readable name */
+  name: string
+  /** Numeric version for ordering */
+  version: number
+  /** SHA-256 checksum of migration content */
+  checksum: string
+  /** ISO timestamp when migration was applied */
+  applied_at: string
+  /** Execution time in milliseconds */
+  execution_time_ms: number
+  /** Current status of the migration */
+  status: MigrationStatus
+}
+
+/**
+ * Schema version metadata for a DO instance
+ */
+export interface SchemaVersion {
+  /** Current schema version number (highest applied migration) */
+  currentVersion: number
+  /** Total number of applied migrations */
+  appliedCount: number
+  /** Timestamp of last migration */
+  lastMigrationAt: string | null
+  /** List of all migration records */
+  migrations: MigrationRecord[]
+}
+
+/**
+ * Migration definition for the registry
+ *
+ * This is the format used when defining migrations in code.
+ * Compatible with Drizzle-generated SQL files.
+ *
+ * @example
+ * ```typescript
+ * const migration: Migration = {
+ *   id: '0001_initial',
+ *   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;
+ *   `,
+ *   isReversible: true,
+ * }
+ * ```
+ */
+export interface Migration {
+  /**
+   * Unique migration identifier
+   *
+   * Convention: NNNN_snake_case_description
+   * Example: '0001_create_users', '0002_add_posts'
+   *
+   * This ID must be unique and immutable once deployed.
+   * Changing the ID of a deployed migration will cause it to re-run.
+   */
+  id: string
+
+  /**
+   * Human-readable migration name
+   *
+   * Used in logs and status displays.
+   */
+  name: string
+
+  /**
+   * Migration version number for ordering
+   *
+   * Must be a positive integer. Migrations are executed in version order.
+   * Version numbers should be monotonically increasing.
+   */
+  version: number
+
+  /**
+   * Forward migration SQL
+   *
+   * This SQL is executed when applying the migration.
+   * Must be idempotent where possible (use CREATE TABLE IF NOT EXISTS, etc.)
+   */
+  up: string
+
+  /**
+   * Rollback migration SQL (optional)
+   *
+   * This SQL is executed when rolling back the migration.
+   * If not provided, rollback is not supported for this migration.
+   */
+  down?: string | undefined
+
+  /**
+   * Whether this migration is reversible
+   *
+   * Default: true if down SQL is provided, false otherwise
+   * Set to false explicitly for data migrations that cannot be safely rolled back
+   * even if down SQL is technically provided (e.g., data transformations that lose info).
+   */
+  isReversible?: boolean | undefined
+
+  /**
+   * Tags for categorizing migrations
+   *
+   * Examples: ['schema', 'data', 'index', 'seed']
+   */
+  tags?: string[] | undefined
+
+  /**
+   * Whether this migration is transactional
+   *
+   * Default: true
+   * Set to false for operations that can't run in a transaction
+   * (e.g., CREATE INDEX CONCURRENTLY)
+   */
+  transactional?: boolean | undefined
+
+  /**
+   * Timeout for this specific migration in milliseconds
+   *
+   * Overrides the global migration timeout.
+   */
+  timeoutMs?: number | undefined
+}
+
+/**
+ * Migration input for applying a migration
+ * (Simplified version of Migration for internal use)
+ */
+export interface MigrationInput {
+  id: string
+  name: string
+  version: number
+  sql: string
+}
+
+/**
+ * Result of applying a single migration
+ */
+export interface MigrationResult {
+  /** Whether the migration was successful */
+  success: boolean
+  /** Migration ID */
+  id: string
+  /** Execution time in milliseconds */
+  executionTimeMs: number
+  /** Error message if failed */
+  error?: string | undefined
+  /** Whether this migration was already applied (skipped) */
+  skipped?: boolean | undefined
+}
+
+/**
+ * Result of applying multiple migrations
+ */
+export interface BatchMigrationResult {
+  /** Whether all migrations completed successfully */
+  success: boolean
+  /** Starting schema version */
+  fromVersion: number
+  /** Ending schema version */
+  toVersion: number
+  /** Total duration in milliseconds */
+  durationMs: number
+  /** Individual migration results */
+  results: MigrationResult[]
+  /** Number of migrations executed */
+  migrationsRun: number
+  /** Number of migrations skipped (already applied) */
+  migrationsSkipped: number
+}
+
+/**
+ * Version comparison result
+ */
+export interface VersionComparison {
+  /** Current schema version in the DO */
+  current: number
+  /** Target version being compared against */
+  target: number
+  /** Whether the schema needs migration */
+  needsMigration: boolean
+  /** Number of migrations needed to reach target */
+  pendingCount: number
+  /** List of missing migration versions */
+  missingVersions: number[]
+}
+
+/**
+ * Migration progress event for callbacks
+ */
+export interface MigrationProgressEvent {
+  /** The migration being processed */
+  migration: Migration
+  /** Zero-based index of current migration */
+  index: number
+  /** Total number of migrations to run */
+  total: number
+  /** Phase of the migration */
+  phase: 'starting' | 'executing' | 'completed' | 'failed' | 'skipped'
+  /** Duration in milliseconds (only set on completion) */
+  durationMs?: number | undefined
+  /** Error message if failed */
+  error?: string | undefined
+}
+
+/**
+ * Migration registry configuration
+ */
+export interface MigrationRegistryConfig {
+  /**
+   * Migrations to register
+   */
+  migrations: Migration[]
+
+  /**
+   * Whether to validate migrations on registry creation
+   * Default: true
+   */
+  validateOnCreate?: boolean
+
+  /**
+   * Whether to allow gaps in version numbers
+   * Default: false
+   */
+  allowVersionGaps?: boolean
+}
+
+/**
+ * Migration runner configuration
+ */
+export interface MigrationRunnerConfig {
+  /**
+   * Name of the migrations table
+   * Default: '_migrations'
+   */
+  tableName?: string | undefined
+
+  /**
+   * Schema for the migrations table
+   * Default: 'public'
+   */
+  schema?: string | undefined
+
+  /**
+   * Whether to run migrations automatically on first connection
+   * Default: true
+   */
+  autoMigrate?: boolean | undefined
+
+  /**
+   * Timeout for each migration in milliseconds
+   * Default: 30000 (30 seconds)
+   */
+  migrationTimeoutMs?: number | undefined
+
+  /**
+   * Whether to acquire a lock before running migrations
+   * Default: true
+   */
+  useLocking?: boolean | undefined
+
+  /**
+   * Lock timeout in milliseconds
+   * Default: 5000 (5 seconds)
+   */
+  lockTimeoutMs?: number | undefined
+
+  /**
+   * Callback for migration progress events
+   */
+  onProgress?: ((event: MigrationProgressEvent) => void) | undefined
+
+  /**
+   * Enable debug logging
+   * Default: false
+   */
+  debug?: boolean | undefined
+}
+
+/**
+ * Drizzle-compatible migration file structure
+ *
+ * This matches the format generated by drizzle-kit generate
+ */
+export interface DrizzleMigrationFile {
+  /** Migration SQL content */
+  sql: string
+  /** Timestamp-based folder name (e.g., '20240115120000') */
+  folderName: string
+  /** Migration tag/name */
+  tag?: string
+}
+
+/**
+ * Drizzle migrations journal entry
+ *
+ * This matches the structure in Drizzle's meta/_journal.json
+ */
+export interface DrizzleJournalEntry {
+  idx: number
+  version: string
+  when: number
+  tag: string
+  breakpoints?: boolean
+}
+
+/**
+ * Drizzle migrations journal
+ *
+ * This matches the structure of Drizzle's meta/_journal.json file
+ */
+export interface DrizzleJournal {
+  version: string
+  dialect: 'postgresql' | 'mysql' | 'sqlite'
+  entries: DrizzleJournalEntry[]
+}
+
+/**
+ * Lock state for migration coordination
+ */
+export interface MigrationLock {
+  /** Whether the lock is currently held */
+  acquired: boolean
+  /** ID of the lock holder */
+  lockId?: string
+  /** When the lock was acquired */
+  acquiredAt?: Date
+  /** When the lock expires */
+  expiresAt?: Date
+}
+
+/**
+ * Migration event types for the event system
+ */
+export type MigrationEventType =
+  | 'migration_started'
+  | 'migration_completed'
+  | 'migration_failed'
+  | 'migration_skipped'
+  | 'migration_rolled_back'
+  | 'batch_started'
+  | 'batch_completed'
+  | 'batch_failed'
+  | 'lock_acquired'
+  | 'lock_released'
+  | 'lock_timeout'
+  | 'table_created'
+
+/**
+ * Migration event for the event system
+ */
+export interface MigrationEvent {
+  type: MigrationEventType
+  migration?: Migration
+  result?: MigrationResult
+  batchResult?: BatchMigrationResult
+  lock?: MigrationLock
+  error?: Error
+  timestamp: Date
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Migration event listener
+ */
+export type MigrationEventListener = (event: MigrationEvent) => void | Promise<void>
+
+/**
+ * Query executor interface for migrations
+ */
+export interface QueryExecutor {
+  query<T = unknown>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<{
+    rows: T[]
+    fields: { name: string; dataTypeID: number }[]
+    affectedRows?: number
+  }>
+}
+
+// ============================================================================
+// Rollback Types
+// ============================================================================
+
+/**
+ * Options for rollback operations
+ */
+export interface RollbackOptions {
+  /**
+   * Target version to rollback to
+   *
+   * All migrations with versions greater than this will be rolled back.
+   */
+  toVersion: number
+
+  /**
+   * Preview changes without executing
+   *
+   * When true, returns what would be rolled back without making changes.
+   * Default: false
+   */
+  dryRun?: boolean | undefined
+
+  /**
+   * Skip reversibility checks
+   *
+   * When true, allows rolling back migrations marked as non-reversible.
+   * Use with caution - may result in data loss.
+   * Default: false
+   */
+  force?: boolean | undefined
+
+  /**
+   * Callback for rollback progress events
+   */
+  onProgress?: ((event: RollbackProgressEvent) => void) | undefined
+}
+
+/**
+ * Progress event for rollback operations
+ */
+export interface RollbackProgressEvent {
+  /** The migration being rolled back */
+  migration: Migration
+  /** Zero-based index of current rollback */
+  index: number
+  /** Total number of migrations to rollback */
+  total: number
+  /** Phase of the rollback */
+  phase: 'starting' | 'executing' | 'completed' | 'failed' | 'skipped'
+  /** Duration in milliseconds (only set on completion) */
+  durationMs?: number | undefined
+  /** Error message if failed */
+  error?: string | undefined
+  /** Whether this is a dry run */
+  isDryRun: boolean
+}
+
+/**
+ * Result of a single rollback operation
+ */
+export interface RollbackResult {
+  /** Whether the rollback was successful */
+  success: boolean
+  /** Migration ID that was rolled back */
+  id: string
+  /** Migration version */
+  version: number
+  /** Execution time in milliseconds */
+  executionTimeMs: number
+  /** Error message if failed */
+  error?: string | undefined
+  /** Whether this was a dry run (no changes made) */
+  isDryRun?: boolean | undefined
+  /** Whether the migration was skipped (not applied or non-reversible) */
+  skipped?: boolean | undefined
+  /** Reason for skipping if applicable */
+  skipReason?: 'not_applied' | 'non_reversible' | 'no_down_sql'
+}
+
+/**
+ * Result of a batch rollback operation
+ */
+export interface BatchRollbackResult {
+  /** Whether all rollbacks completed successfully */
+  success: boolean
+  /** Starting schema version */
+  fromVersion: number
+  /** Ending schema version */
+  toVersion: number
+  /** Total duration in milliseconds */
+  durationMs: number
+  /** Individual rollback results */
+  results: RollbackResult[]
+  /** Number of migrations rolled back */
+  rolledBackCount: number
+  /** Number of migrations skipped */
+  skippedCount: number
+  /** Whether this was a dry run */
+  isDryRun: boolean
+  /** Migrations that would block rollback (non-reversible) */
+  blockedBy?: Array<{
+    id: string
+    version: number
+    reason: string
+  }>
+}
+
+/**
+ * Rollback history record stored in the migrations table
+ */
+export interface RollbackHistoryRecord {
+  /** Unique rollback operation ID */
+  rollback_id: string
+  /** Migration ID that was rolled back */
+  migration_id: string
+  /** Migration version that was rolled back */
+  version: number
+  /** ISO timestamp when rollback occurred */
+  rolled_back_at: string
+  /** Execution time in milliseconds */
+  execution_time_ms: number
+  /** Previous status before rollback */
+  previous_status: MigrationStatus
+  /** User/system that initiated the rollback */
+  initiated_by?: string
+  /** Reason for the rollback */
+  reason?: string
+}
+
+/**
+ * Rollback event types
+ */
+export type RollbackEventType =
+  | 'rollback_started'
+  | 'rollback_completed'
+  | 'rollback_failed'
+  | 'rollback_skipped'
+  | 'batch_rollback_started'
+  | 'batch_rollback_completed'
+  | 'batch_rollback_failed'
+
+/**
+ * Rollback event for the event system
+ */
+export interface RollbackEvent {
+  type: RollbackEventType
+  migration?: Migration
+  result?: RollbackResult
+  batchResult?: BatchRollbackResult
+  options?: RollbackOptions
+  error?: Error
+  timestamp: Date
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Rollback event listener
+ */
+export type RollbackEventListener = (event: RollbackEvent) => void | Promise<void>