@dotdo/postgres 0.1.0

package/src/playground/query-executor.ts

@@ -0,0 +1,669 @@
+/**
+ * Playground Query Executor
+ *
+ * Implements IQueryExecutor for the interactive SQL playground.
+ * Provides query execution with parameter binding, timeout support,
+ * query cancellation, and execution plan generation.
+ *
+ * @module playground/query-executor
+ */
+
+import { PGlite, type Results } from '@dotdo/pglite'
+import type {
+  IQueryExecutor,
+  PlaygroundQueryOptions,
+  PlaygroundExecutionResult,
+  PlaygroundQueryResult,
+  PlaygroundQueryError,
+  QueryResultField,
+  QueryExecutionPlan,
+} from './types'
+
+/**
+ * Options for creating a playground query executor
+ */
+export interface PlaygroundQueryExecutorOptions {
+  /** Existing PGLite instance (optional) */
+  pglite?: PGlite
+  /** Default query timeout in milliseconds (default: 30000) */
+  defaultTimeout?: number
+}
+
+/**
+ * Map PostgreSQL error codes to friendly messages
+ * Pre-computed at module level for performance
+ */
+const ERROR_CODE_MAP: Record<string, string> = {
+  '42P01': 'Table does not exist',
+  '42703': 'Column does not exist',
+  '42601': 'Syntax error',
+  '23505': 'Unique constraint violation',
+  '23502': 'NOT NULL constraint violation',
+  '23503': 'Foreign key constraint violation',
+  '23514': 'Check constraint violation',
+  '22012': 'Division by zero',
+  '42883': 'Function does not exist',
+  '42501': 'Insufficient privilege',
+  '42P07': 'Duplicate table',
+  '42710': 'Duplicate object',
+  '22001': 'String data right truncation',
+  '22003': 'Numeric value out of range',
+  '22P02': 'Invalid text representation',
+}
+
+/**
+ * PostgreSQL data type OID to name map
+ * Pre-computed at module level for performance (avoids recreating on each call)
+ */
+const TYPE_OID_MAP: Record<number, string> = {
+  16: 'boolean',
+  17: 'bytea',
+  18: 'char',
+  19: 'name',
+  20: 'bigint',
+  21: 'smallint',
+  23: 'integer',
+  25: 'text',
+  26: 'oid',
+  700: 'real',
+  701: 'double precision',
+  790: 'money',
+  1042: 'char',
+  1043: 'varchar',
+  1082: 'date',
+  1083: 'time',
+  1114: 'timestamp',
+  1184: 'timestamptz',
+  1186: 'interval',
+  1700: 'numeric',
+  2950: 'uuid',
+  3802: 'jsonb',
+  114: 'json',
+  1007: 'integer[]',
+  1009: 'text[]',
+  1016: 'bigint[]',
+  1000: 'boolean[]',
+  1115: 'timestamp[]',
+  1185: 'timestamptz[]',
+  2951: 'uuid[]',
+  3807: 'jsonb[]',
+  199: 'json[]',
+}
+
+/**
+ * SQL command keywords for fast command detection
+ * Ordered by frequency for early exit optimization
+ */
+const SQL_COMMANDS = [
+  'SELECT',
+  'INSERT',
+  'UPDATE',
+  'DELETE',
+  'CREATE',
+  'ALTER',
+  'DROP',
+  'BEGIN',
+  'COMMIT',
+  'ROLLBACK',
+  'TRUNCATE',
+  'GRANT',
+  'REVOKE',
+  'WITH',
+  'EXPLAIN',
+  'SAVEPOINT',
+  'RELEASE',
+] as const
+
+/**
+ * Transaction control commands that should NOT be wrapped in a transaction
+ * These need direct execution to work properly
+ */
+const TRANSACTION_COMMANDS = new Set([
+  'BEGIN',
+  'COMMIT',
+  'ROLLBACK',
+  'SAVEPOINT',
+  'RELEASE',
+])
+
+/**
+ * Playground Query Executor implementation
+ */
+export class PlaygroundQueryExecutor implements IQueryExecutor {
+  private _pglite: PGlite
+  private _ready: boolean = false
+  private _readyPromise: Promise<void>
+  private _defaultTimeout: number
+  private _currentQueryAbortController: AbortController | null = null
+  private _isExecuting: boolean = false
+  /** Track if we're inside an explicit transaction (started by BEGIN) */
+  private _inExplicitTransaction: boolean = false
+
+  constructor(options: PlaygroundQueryExecutorOptions = {}) {
+    this._defaultTimeout = options.defaultTimeout ?? 30000
+
+    if (options.pglite) {
+      this._pglite = options.pglite
+      this._readyPromise = options.pglite.waitReady.then(() => {
+        this._ready = true
+      })
+    } else {
+      // Create a new in-memory PGLite instance
+      this._pglite = new PGlite()
+      this._readyPromise = this._pglite.waitReady.then(() => {
+        this._ready = true
+      })
+    }
+  }
+
+  /**
+   * Wait for the executor to be ready
+   */
+  async waitReady(): Promise<void> {
+    await this._readyPromise
+  }
+
+  /**
+   * Check if executor is ready
+   */
+  isReady(): boolean {
+    return this._ready
+  }
+
+  /**
+   * Get the underlying PGLite instance
+   */
+  get pglite(): PGlite {
+    return this._pglite
+  }
+
+  /**
+   * Execute a SQL query
+   */
+  async execute<T = Record<string, unknown>>(
+    options: PlaygroundQueryOptions
+  ): Promise<PlaygroundExecutionResult<T>> {
+    const { sql, params, timeout, explain } = options
+    const startTime = performance.now()
+
+    // Ensure we're ready
+    if (!this._ready) {
+      await this._readyPromise
+    }
+
+    // Set up abort controller for cancellation
+    this._currentQueryAbortController = new AbortController()
+    this._isExecuting = true
+
+    try {
+      // Check if we need to get the execution plan
+      if (explain) {
+        return await this._executeWithExplain<T>(sql, params, timeout, startTime)
+      }
+
+      // Check if this is a multi-statement SQL (contains semicolons outside quotes)
+      const isMultiStatement = this._isMultiStatementSql(sql) && !params
+
+      if (isMultiStatement) {
+        // Use exec for multi-statement SQL
+        const results = await this._pglite.exec(sql)
+        const durationMs = performance.now() - startTime
+
+        // Return the last result
+        const lastResult = results[results.length - 1]
+        if (lastResult) {
+          return this._formatSuccessResult<T>(lastResult as Results<T>, durationMs, sql)
+        }
+
+        // No results - return empty success
+        return {
+          rows: [],
+          fields: [],
+          rowCount: null,
+          command: this._extractCommandFromSql(sql),
+          durationMs,
+          success: true,
+        } as PlaygroundQueryResult<T>
+      }
+
+      // Check if this is a transaction control command (BEGIN, COMMIT, ROLLBACK, SAVEPOINT)
+      // These must be executed directly without wrapping in a transaction
+      const command = this._extractCommandFromSql(sql)
+      if (this._isTransactionCommand(sql)) {
+        // Track explicit transaction state
+        if (command === 'BEGIN') {
+          this._inExplicitTransaction = true
+        } else if (command === 'COMMIT' || command === 'ROLLBACK') {
+          this._inExplicitTransaction = false
+        }
+        const result = await this._pglite.query<T>(sql, params)
+        const durationMs = performance.now() - startTime
+        return this._formatSuccessResult<T>(result, durationMs, sql)
+      }
+
+      // If we're inside an explicit transaction, execute directly without wrapping
+      // This prevents nested transactions (SAVEPOINTs) that would interfere with ROLLBACK
+      if (this._inExplicitTransaction) {
+        try {
+          const result = await this._pglite.query<T>(sql, params)
+          const durationMs = performance.now() - startTime
+          return this._formatSuccessResult<T>(result, durationMs, sql)
+        } catch (error) {
+          // On error during explicit transaction, try to rollback and reset state
+          // This handles the case where a transaction becomes aborted
+          try {
+            await this._pglite.query('ROLLBACK')
+          } catch {
+            // Ignore rollback errors - transaction may already be rolled back
+          }
+          this._inExplicitTransaction = false
+          throw error
+        }
+      }
+
+      // Execute the query with timeout (wraps in transaction for statement_timeout)
+      const result = await this._executeWithTimeout<T>(sql, params, timeout ?? this._defaultTimeout)
+      const durationMs = performance.now() - startTime
+
+      return this._formatSuccessResult<T>(result, durationMs, sql)
+    } catch (error) {
+      const durationMs = performance.now() - startTime
+      return this._formatErrorResult(error as Error, durationMs)
+    } finally {
+      this._isExecuting = false
+      this._currentQueryAbortController = null
+    }
+  }
+
+  /**
+   * Check if SQL contains multiple statements
+   */
+  private _isMultiStatementSql(sql: string): boolean {
+    // Simple heuristic: check for semicolons outside of quotes
+    let inSingleQuote = false
+    let inDoubleQuote = false
+    let semicolonCount = 0
+
+    for (let i = 0; i < sql.length; i++) {
+      const char = sql[i]
+      const prevChar = i > 0 ? sql[i - 1] : ''
+
+      if (char === "'" && prevChar !== '\\' && !inDoubleQuote) {
+        inSingleQuote = !inSingleQuote
+      } else if (char === '"' && prevChar !== '\\' && !inSingleQuote) {
+        inDoubleQuote = !inDoubleQuote
+      } else if (char === ';' && !inSingleQuote && !inDoubleQuote) {
+        semicolonCount++
+        // If we find a semicolon and there's more SQL after it, it's multi-statement
+        const remaining = sql.substring(i + 1).trim()
+        if (remaining.length > 0 && semicolonCount > 0) {
+          return true
+        }
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * Extract command type from SQL
+   * Optimized: uses pre-computed command list and early exit
+   */
+  private _extractCommandFromSql(sql: string): string {
+    const trimmed = sql.trimStart().toUpperCase()
+
+    // Use the pre-computed command list for fast lookup
+    for (const cmd of SQL_COMMANDS) {
+      if (trimmed.startsWith(cmd)) {
+        return cmd
+      }
+    }
+
+    return 'UNKNOWN'
+  }
+
+  /**
+   * Check if SQL is a transaction control command that should not be wrapped
+   */
+  private _isTransactionCommand(sql: string): boolean {
+    const command = this._extractCommandFromSql(sql)
+    return TRANSACTION_COMMANDS.has(command)
+  }
+
+  /**
+   * Execute multiple queries in sequence
+   */
+  async executeMultiple(queries: string[]): Promise<PlaygroundExecutionResult[]> {
+    const results: PlaygroundExecutionResult[] = []
+
+    if (queries.length === 0) {
+      return results
+    }
+
+    for (const sql of queries) {
+      const result = await this.execute({ sql })
+      results.push(result)
+
+      // Stop on first error
+      if (!result.success) {
+        break
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * Execute multiple queries in a batch (optimized for many queries)
+   * All queries run in a single transaction for better performance.
+   * Returns results for all queries, stopping on first error.
+   */
+  async executeBatch(queries: string[]): Promise<PlaygroundExecutionResult[]> {
+    if (queries.length === 0) {
+      return []
+    }
+
+    // For single query, just use execute
+    if (queries.length === 1) {
+      const result = await this.execute({ sql: queries[0]! })
+      return [result]
+    }
+
+    const results: PlaygroundExecutionResult[] = []
+
+    // Ensure we're ready
+    if (!this._ready) {
+      await this._readyPromise
+    }
+
+    try {
+      // Execute all in a single transaction for better performance
+      await this._pglite.transaction(async (tx) => {
+        for (const sql of queries) {
+          const queryStart = performance.now()
+          try {
+            const result = await tx.query(sql)
+            const durationMs = performance.now() - queryStart
+            results.push(
+              this._formatSuccessResult(result as Results<Record<string, unknown>>, durationMs, sql)
+            )
+          } catch (error) {
+            const durationMs = performance.now() - queryStart
+            results.push(this._formatErrorResult(error as Error, durationMs))
+            throw error // Roll back the transaction
+          }
+        }
+      })
+    } catch {
+      // Transaction was rolled back, results already contain the error
+    }
+
+    return results
+  }
+
+  /**
+   * Cancel the currently running query
+   */
+  async cancel(): Promise<boolean> {
+    if (!this._isExecuting || !this._currentQueryAbortController) {
+      return false
+    }
+
+    this._currentQueryAbortController.abort()
+
+    // Cancel via PostgreSQL
+    try {
+      await this._pglite.query('SELECT pg_cancel_backend(pg_backend_pid())')
+    } catch {
+      // Ignore errors - the query may have already finished
+    }
+
+    return true
+  }
+
+  /**
+   * Execute query with timeout support
+   */
+  private async _executeWithTimeout<T>(
+    sql: string,
+    params?: unknown[],
+    timeoutMs?: number
+  ): Promise<Results<T>> {
+    const effectiveTimeout = timeoutMs ?? this._defaultTimeout
+
+    // Create a timeout promise
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        reject(new Error('Query timeout - query was cancelled'))
+      }, effectiveTimeout)
+    })
+
+    // Race between query and timeout
+    try {
+      // Use transaction with statement_timeout for proper timeout handling
+      return await Promise.race([
+        this._pglite.transaction(async (tx) => {
+          await tx.query(`SET LOCAL statement_timeout = ${effectiveTimeout}`)
+          return await tx.query<T>(sql, params)
+        }),
+        timeoutPromise,
+      ])
+    } catch (error) {
+      const message = (error as Error).message || ''
+      if (
+        message.includes('timeout') ||
+        message.includes('canceling statement') ||
+        message.includes('statement timeout')
+      ) {
+        throw new Error('Query timeout - query was cancelled')
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Execute query with EXPLAIN
+   */
+  private async _executeWithExplain<T>(
+    sql: string,
+    params: unknown[] | undefined,
+    timeout: number | undefined,
+    startTime: number
+  ): Promise<PlaygroundExecutionResult<T>> {
+    try {
+      // First get the execution plan
+      const explainSql = `EXPLAIN (FORMAT JSON) ${sql}`
+      const explainResult = await this._executeWithTimeout<{ 'QUERY PLAN': unknown[] }>(
+        explainSql,
+        params,
+        timeout ?? this._defaultTimeout
+      )
+
+      // Then execute the actual query
+      const result = await this._executeWithTimeout<T>(sql, params, timeout ?? this._defaultTimeout)
+      const durationMs = performance.now() - startTime
+
+      // Parse the execution plan
+      let plan: QueryExecutionPlan | undefined
+      if (explainResult.rows.length > 0) {
+        const planRow = explainResult.rows[0]
+        if (planRow !== undefined) {
+          const planData = planRow['QUERY PLAN']
+          if (Array.isArray(planData) && planData.length > 0) {
+            plan = this._parsePlan(planData[0] as Record<string, unknown>)
+          }
+        }
+      }
+
+      const successResult = this._formatSuccessResult<T>(result, durationMs, sql)
+      if (successResult.success) {
+        successResult.plan = plan
+      }
+
+      return successResult
+    } catch (error) {
+      const durationMs = performance.now() - startTime
+      return this._formatErrorResult(error as Error, durationMs)
+    }
+  }
+
+  /**
+   * Parse execution plan from EXPLAIN JSON output
+   */
+  private _parsePlan(planNode: Record<string, unknown>): QueryExecutionPlan {
+    const plan: QueryExecutionPlan = {
+      nodeType: (planNode['Node Type'] as string) || 'Unknown',
+      startupCost: (planNode['Startup Cost'] as number) || 0,
+      totalCost: (planNode['Total Cost'] as number) || 0,
+      planRows: (planNode['Plan Rows'] as number) || 0,
+      planWidth: (planNode['Plan Width'] as number) || 0,
+    }
+
+    // Copy additional properties
+    for (const [key, value] of Object.entries(planNode)) {
+      if (!['Node Type', 'Startup Cost', 'Total Cost', 'Plan Rows', 'Plan Width', 'Plans'].includes(key)) {
+        plan[key] = value
+      }
+    }
+
+    // Parse child plans
+    if (Array.isArray(planNode['Plans'])) {
+      plan.plans = (planNode['Plans'] as Record<string, unknown>[]).map((child) =>
+        this._parsePlan(child)
+      )
+    }
+
+    return plan
+  }
+
+  /**
+   * Format a successful query result
+   */
+  private _formatSuccessResult<T>(result: Results<T>, durationMs: number, sql?: string): PlaygroundQueryResult<T> {
+    const fields: QueryResultField[] = result.fields.map((field) => ({
+      name: field.name,
+      dataTypeID: field.dataTypeID,
+      dataTypeName: this._getDataTypeName(field.dataTypeID),
+      tableID: (field as { tableID?: number }).tableID,
+      columnID: (field as { columnID?: number }).columnID,
+    }))
+
+    // Determine command from the result or SQL
+    const command = this._extractCommand(result, sql)
+
+    return {
+      rows: result.rows,
+      fields,
+      rowCount: result.affectedRows ?? result.rows.length,
+      command,
+      durationMs,
+      success: true,
+    }
+  }
+
+  /**
+   * Format an error result
+   */
+  private _formatErrorResult(error: Error, durationMs: number): PlaygroundQueryError {
+    const pgError = error as Error & {
+      code?: string
+      position?: string | number
+      line?: number
+      detail?: string
+      hint?: string
+    }
+
+    const code = pgError.code
+    let message = pgError.message || 'Unknown error'
+
+    // Clean up the error message
+    message = message.replace(/^ERROR:\s*/i, '')
+
+    // Add friendly description if we have a known error code
+    if (code && ERROR_CODE_MAP[code]) {
+      message = `${ERROR_CODE_MAP[code]}: ${message}`
+    }
+
+    // Parse position from error message if not provided
+    let position: number | undefined = typeof pgError.position === 'number'
+      ? pgError.position
+      : (typeof pgError.position === 'string' ? parseInt(pgError.position, 10) : undefined)
+    let line: number | undefined = pgError.line
+
+    if (!position && message.includes('at character')) {
+      const posMatch = message.match(/at character (\d+)/)
+      const posStr = posMatch?.[1]
+      if (posStr) {
+        position = parseInt(posStr, 10)
+      }
+    }
+
+    if (!line && message.includes('LINE')) {
+      const lineMatch = message.match(/LINE (\d+)/)
+      const lineStr = lineMatch?.[1]
+      if (lineStr) {
+        line = parseInt(lineStr, 10)
+      }
+    }
+
+    return {
+      message,
+      code,
+      position,
+      line,
+      detail: pgError.detail,
+      hint: pgError.hint,
+      durationMs,
+      success: false,
+    }
+  }
+
+  /**
+   * Extract command type from query result
+   */
+  private _extractCommand(result: Results<unknown>, sql?: string): string {
+    // PGLite provides a command property in some cases
+    const cmd = (result as Results<unknown> & { command?: string }).command
+
+    if (cmd) {
+      return cmd.toUpperCase()
+    }
+
+    // Try to extract from SQL if provided
+    if (sql) {
+      return this._extractCommandFromSql(sql)
+    }
+
+    // Default to SELECT if there are rows
+    if (result.rows.length > 0 || result.fields.length > 0) {
+      return 'SELECT'
+    }
+
+    return 'UNKNOWN'
+  }
+
+  /**
+   * Get PostgreSQL data type name from OID
+   * Uses the pre-computed module-level TYPE_OID_MAP for performance
+   */
+  private _getDataTypeName(oid: number): string {
+    return TYPE_OID_MAP[oid] || 'unknown'
+  }
+
+  /**
+   * Close the executor
+   */
+  async close(): Promise<void> {
+    this._ready = false
+    await this._pglite.close()
+  }
+}
+
+/**
+ * Create a new playground query executor
+ */
+export function createQueryExecutor(
+  options?: PlaygroundQueryExecutorOptions
+): PlaygroundQueryExecutor {
+  return new PlaygroundQueryExecutor(options)
+}