@libredb/studio 0.9.7

package/src/lib/db/types.ts

@@ -0,0 +1,437 @@
+/**
+ * Database Provider Types & Interfaces
+ * Strategy Pattern implementation for multi-database support
+ */
+
+// Re-export common types from main types file
+export type {
+  DatabaseType,
+  DatabaseConnection,
+  TableSchema,
+  ColumnSchema,
+  IndexSchema,
+  ForeignKeySchema,
+  QueryResult,
+} from '../types';
+
+import type {
+  DatabaseType,
+  DatabaseConnection,
+  TableSchema,
+  QueryResult,
+} from '../types';
+
+// ============================================================================
+// Pool Configuration
+// ============================================================================
+
+export interface PoolConfig {
+  /** Minimum number of connections in pool (default: 2) */
+  min: number;
+  /** Maximum number of connections in pool (default: 10) */
+  max: number;
+  /** Close idle connections after this time in ms (default: 30000) */
+  idleTimeout: number;
+  /** Wait for connection timeout in ms (default: 60000) */
+  acquireTimeout: number;
+}
+
+export const DEFAULT_POOL_CONFIG: PoolConfig = {
+  min: 2,
+  max: 10,
+  idleTimeout: 30000,
+  acquireTimeout: 60000,
+};
+
+/** Query timeout in milliseconds (default: 60 seconds) */
+export const DEFAULT_QUERY_TIMEOUT = 60000;
+
+// ============================================================================
+// Health Information
+// ============================================================================
+
+export interface SlowQuery {
+  query: string;
+  calls: number;
+  avgTime: string;
+}
+
+export interface ActiveSession {
+  pid: number | string;
+  user: string;
+  database: string;
+  state: string;
+  query: string;
+  duration: string;
+}
+
+export interface HealthInfo {
+  activeConnections: number;
+  databaseSize: string;
+  cacheHitRatio: string;
+  slowQueries: SlowQuery[];
+  activeSessions: ActiveSession[];
+}
+
+// ============================================================================
+// Maintenance Operations
+// ============================================================================
+
+export type MaintenanceType = 'vacuum' | 'analyze' | 'reindex' | 'kill' | 'optimize' | 'check';
+
+export interface MaintenanceResult {
+  success: boolean;
+  executionTime: number;
+  message: string;
+}
+
+// ============================================================================
+// Provider Capabilities & Labels
+// ============================================================================
+
+export interface ProviderCapabilities {
+  queryLanguage: 'sql' | 'json';
+  supportsExplain: boolean;
+  supportsExternalQueryLimiting: boolean;
+  supportsCreateTable: boolean;
+  supportsMaintenance: boolean;
+  maintenanceOperations: MaintenanceType[];
+  supportsConnectionString: boolean;
+  defaultPort: number | null;
+  schemaRefreshPattern: string;
+}
+
+export interface ProviderLabels {
+  entityName: string;
+  entityNamePlural: string;
+  rowName: string;
+  rowNamePlural: string;
+  selectAction: string;
+  generateAction: string;
+  analyzeAction: string;
+  vacuumAction: string;
+  searchPlaceholder: string;
+  analyzeGlobalLabel: string;
+  analyzeGlobalTitle: string;
+  analyzeGlobalDesc: string;
+  vacuumGlobalLabel: string;
+  vacuumGlobalTitle: string;
+  vacuumGlobalDesc: string;
+}
+
+export interface PreparedQuery {
+  query: string;
+  wasLimited: boolean;
+  limit: number;
+  offset: number;
+}
+
+export interface QueryPrepareOptions {
+  limit?: number;
+  offset?: number;
+  unlimited?: boolean;
+}
+
+// ============================================================================
+// Provider Interface (Strategy Pattern)
+// ============================================================================
+
+export interface DatabaseProvider {
+  /** Database type identifier */
+  readonly type: DatabaseType;
+
+  /** Connection configuration */
+  readonly config: DatabaseConnection;
+
+  /**
+   * Initialize connection pool or single connection
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Close all connections and cleanup resources
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Check if provider is currently connected
+   */
+  isConnected(): boolean;
+
+  /**
+   * Execute a SQL query
+   * @param sql - SQL query string
+   * @param params - Optional query parameters for prepared statements
+   * @returns Query result with rows, fields, and execution time
+   */
+  query(sql: string, params?: unknown[]): Promise<QueryResult>;
+
+  /**
+   * Get full database schema
+   * @returns Array of table schemas with columns, indexes, and foreign keys
+   */
+  getSchema(): Promise<TableSchema[]>;
+
+  /**
+   * Get list of table names
+   */
+  getTables(): Promise<string[]>;
+
+  /**
+   * Get health and performance metrics
+   */
+  getHealth(): Promise<HealthInfo>;
+
+  /**
+   * Get comprehensive monitoring data
+   * @param options - What to include in the monitoring data
+   */
+  getMonitoringData(options?: MonitoringOptions): Promise<MonitoringData>;
+
+  /**
+   * Get database overview metrics
+   */
+  getOverview(): Promise<DatabaseOverview>;
+
+  /**
+   * Get performance metrics
+   */
+  getPerformanceMetrics(): Promise<PerformanceMetrics>;
+
+  /**
+   * Get slow query statistics
+   * @param options - Query options (limit)
+   */
+  getSlowQueries(options?: { limit?: number }): Promise<SlowQueryStats[]>;
+
+  /**
+   * Get active sessions with details
+   * @param options - Query options (limit)
+   */
+  getActiveSessions(options?: { limit?: number }): Promise<ActiveSessionDetails[]>;
+
+  /**
+   * Get table statistics
+   * @param options - Query options (schema filter)
+   */
+  getTableStats(options?: { schema?: string }): Promise<TableStats[]>;
+
+  /**
+   * Get index statistics
+   * @param options - Query options (schema filter)
+   */
+  getIndexStats(options?: { schema?: string }): Promise<IndexStats[]>;
+
+  /**
+   * Get storage/tablespace statistics
+   */
+  getStorageStats(): Promise<StorageStats[]>;
+
+  /**
+   * Run maintenance operations
+   * @param type - Type of maintenance operation
+   * @param target - Optional target (table name or process ID)
+   */
+  runMaintenance(type: MaintenanceType, target?: string): Promise<MaintenanceResult>;
+
+  /**
+   * Validate provider configuration
+   * @throws DatabaseConfigError if configuration is invalid
+   */
+  validate(): void;
+
+  /**
+   * Get provider capabilities (query language, supported features, etc.)
+   */
+  getCapabilities(): ProviderCapabilities;
+
+  /**
+   * Get UI labels for this provider (entity names, action labels, etc.)
+   */
+  getLabels(): ProviderLabels;
+
+  /**
+   * Prepare a query for execution (apply limits, analyze query type, etc.)
+   */
+  prepareQuery(query: string, options?: QueryPrepareOptions): PreparedQuery;
+}
+
+// ============================================================================
+// Provider Configuration Options
+// ============================================================================
+
+export interface ProviderOptions {
+  /** Connection pool configuration */
+  pool?: Partial<PoolConfig>;
+  /** Query timeout in milliseconds */
+  queryTimeout?: number;
+  /** Enable SSL/TLS connection */
+  ssl?: boolean | { rejectUnauthorized: boolean };
+  /** Connection timezone */
+  timezone?: string;
+}
+
+// ============================================================================
+// Internal Types
+// ============================================================================
+
+export interface ConnectionState {
+  connected: boolean;
+  lastConnected?: Date;
+  lastError?: Error;
+  activeQueries: number;
+}
+
+// ============================================================================
+// Monitoring Types (Extended)
+// ============================================================================
+
+/**
+ * Database overview metrics
+ */
+export interface DatabaseOverview {
+  version: string;
+  uptime: string;
+  startTime?: Date;
+  activeConnections: number;
+  maxConnections: number;
+  databaseSize: string;
+  databaseSizeBytes: number;
+  tableCount: number;
+  indexCount: number;
+}
+
+/**
+ * Performance metrics for the database
+ */
+export interface PerformanceMetrics {
+  /** Cache hit ratio as percentage (0-100) */
+  cacheHitRatio: number;
+  /** Transactions per second */
+  transactionsPerSecond?: number;
+  /** Queries per second */
+  queriesPerSecond?: number;
+  /** Buffer pool usage as percentage (0-100) */
+  bufferPoolUsage?: number;
+  /** Number of deadlocks */
+  deadlocks?: number;
+  /** Checkpoint write time */
+  checkpointWriteTime?: string;
+}
+
+/**
+ * Slow query with detailed statistics
+ */
+export interface SlowQueryStats {
+  queryId?: string;
+  query: string;
+  calls: number;
+  totalTime: number;
+  avgTime: number;
+  minTime?: number;
+  maxTime?: number;
+  rows: number;
+  sharedBlksHit?: number;
+  sharedBlksRead?: number;
+}
+
+/**
+ * Active session with detailed information
+ */
+export interface ActiveSessionDetails {
+  pid: number | string;
+  user: string;
+  database: string;
+  applicationName?: string;
+  clientAddr?: string;
+  state: string;
+  query: string;
+  queryStart?: Date;
+  duration: string;
+  durationMs: number;
+  waitEventType?: string;
+  waitEvent?: string;
+  blocked?: boolean;
+}
+
+/**
+ * Table statistics
+ */
+export interface TableStats {
+  schemaName: string;
+  tableName: string;
+  rowCount: number;
+  liveRowCount?: number;
+  deadRowCount?: number;
+  tableSize: string;
+  tableSizeBytes: number;
+  indexSize?: string;
+  indexSizeBytes?: number;
+  totalSize: string;
+  totalSizeBytes: number;
+  lastVacuum?: Date;
+  lastAnalyze?: Date;
+  bloatRatio?: number;
+}
+
+/**
+ * Index statistics
+ */
+export interface IndexStats {
+  schemaName: string;
+  tableName: string;
+  indexName: string;
+  indexType?: string;
+  columns: string[];
+  isUnique: boolean;
+  isPrimary: boolean;
+  indexSize: string;
+  indexSizeBytes: number;
+  scans: number;
+  usageRatio?: number;
+}
+
+/**
+ * Storage statistics
+ */
+export interface StorageStats {
+  name: string;
+  location?: string;
+  size: string;
+  sizeBytes: number;
+  usagePercent?: number;
+  walSize?: string;
+  walSizeBytes?: number;
+}
+
+/**
+ * Comprehensive monitoring data combining all metrics
+ */
+export interface MonitoringData {
+  timestamp: Date;
+  overview: DatabaseOverview;
+  performance: PerformanceMetrics;
+  slowQueries: SlowQueryStats[];
+  activeSessions: ActiveSessionDetails[];
+  tables?: TableStats[];
+  indexes?: IndexStats[];
+  storage?: StorageStats[];
+}
+
+/**
+ * Options for monitoring queries
+ */
+export interface MonitoringOptions {
+  /** Include table statistics */
+  includeTables?: boolean;
+  /** Include index statistics */
+  includeIndexes?: boolean;
+  /** Include storage/tablespace info */
+  includeStorage?: boolean;
+  /** Limit for slow queries (default: 10) */
+  slowQueryLimit?: number;
+  /** Limit for active sessions (default: 50) */
+  sessionLimit?: number;
+  /** Schema filter (default: 'public' for PostgreSQL) */
+  schemaFilter?: string;
+}

package/src/lib/db/utils/pool-manager.ts

@@ -0,0 +1,287 @@
+/**
+ * Connection Pool Manager
+ * Abstract pool management utilities for database providers
+ */
+
+import { type PoolConfig, DEFAULT_POOL_CONFIG, type DatabaseType } from '../types';
+import { TimeoutError } from '../errors';
+
+// ============================================================================
+// Pool Statistics
+// ============================================================================
+
+export interface PoolStats {
+  /** Total connections in pool */
+  total: number;
+  /** Currently idle connections */
+  idle: number;
+  /** Currently active/busy connections */
+  active: number;
+  /** Connections waiting in queue */
+  waiting: number;
+}
+
+// ============================================================================
+// Pool Manager Interface
+// ============================================================================
+
+export interface PoolManager<T> {
+  /** Acquire a connection from the pool */
+  acquire(): Promise<T>;
+  /** Release a connection back to the pool */
+  release(connection: T): void;
+  /** Get pool statistics */
+  getStats(): PoolStats;
+  /** Drain all connections and close pool */
+  drain(): Promise<void>;
+  /** Check if pool is healthy */
+  isHealthy(): boolean;
+}
+
+// ============================================================================
+// Pool Configuration Utilities
+// ============================================================================
+
+/**
+ * Merge user config with defaults
+ */
+export function mergePoolConfig(config?: Partial<PoolConfig>): PoolConfig {
+  return {
+    ...DEFAULT_POOL_CONFIG,
+    ...config,
+  };
+}
+
+/**
+ * Validate pool configuration
+ */
+export function validatePoolConfig(config: PoolConfig): void {
+  if (config.min < 0) {
+    throw new Error('Pool min must be non-negative');
+  }
+  if (config.max < 1) {
+    throw new Error('Pool max must be at least 1');
+  }
+  if (config.min > config.max) {
+    throw new Error('Pool min cannot be greater than max');
+  }
+  if (config.idleTimeout < 0) {
+    throw new Error('Pool idleTimeout must be non-negative');
+  }
+  if (config.acquireTimeout < 0) {
+    throw new Error('Pool acquireTimeout must be non-negative');
+  }
+}
+
+// ============================================================================
+// Timeout Utilities
+// ============================================================================
+
+/**
+ * Execute a promise with timeout
+ */
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeout: number,
+  provider: DatabaseType,
+  operation: string
+): Promise<T> {
+  let timeoutId: NodeJS.Timeout;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new TimeoutError(
+        `${operation} timed out after ${timeout}ms`,
+        provider,
+        timeout
+      ));
+    }, timeout);
+  });
+
+  try {
+    const result = await Promise.race([promise, timeoutPromise]);
+    clearTimeout(timeoutId!);
+    return result;
+  } catch (error) {
+    clearTimeout(timeoutId!);
+    throw error;
+  }
+}
+
+/**
+ * Create a cancellable query wrapper
+ */
+export function createCancellableQuery<T>(
+  queryFn: (signal?: AbortSignal) => Promise<T>,
+  timeout: number,
+  provider: DatabaseType
+): { promise: Promise<T>; cancel: () => void } {
+  const controller = new AbortController();
+  let timeoutId: NodeJS.Timeout;
+
+  const promise = new Promise<T>((resolve, reject) => {
+    timeoutId = setTimeout(() => {
+      controller.abort();
+      reject(new TimeoutError(
+        `Query timed out after ${timeout}ms`,
+        provider,
+        timeout
+      ));
+    }, timeout);
+
+    queryFn(controller.signal)
+      .then(resolve)
+      .catch(reject)
+      .finally(() => clearTimeout(timeoutId));
+  });
+
+  return {
+    promise,
+    cancel: () => {
+      clearTimeout(timeoutId);
+      controller.abort();
+    },
+  };
+}
+
+// ============================================================================
+// Connection Health Check
+// ============================================================================
+
+/**
+ * Simple ping-like health check
+ */
+export async function checkConnectionHealth<T>(
+  acquireFn: () => Promise<T>,
+  releaseFn: (conn: T) => void,
+  pingFn: (conn: T) => Promise<void>,
+  timeout: number,
+  provider: DatabaseType
+): Promise<boolean> {
+  try {
+    const conn = await withTimeout(
+      acquireFn(),
+      timeout,
+      provider,
+      'Connection acquire'
+    );
+
+    try {
+      await withTimeout(
+        pingFn(conn),
+        timeout,
+        provider,
+        'Connection ping'
+      );
+      return true;
+    } finally {
+      releaseFn(conn);
+    }
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// Retry Logic
+// ============================================================================
+
+export interface RetryOptions {
+  maxAttempts?: number;
+  initialDelay?: number;
+  maxDelay?: number;
+  backoffMultiplier?: number;
+}
+
+const DEFAULT_RETRY_OPTIONS: Required<RetryOptions> = {
+  maxAttempts: 3,
+  initialDelay: 1000,
+  maxDelay: 10000,
+  backoffMultiplier: 2,
+};
+
+/**
+ * Execute with retry logic and exponential backoff
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+  isRetryable: (error: unknown) => boolean = () => true,
+  provider?: DatabaseType
+): Promise<T> {
+  const opts = { ...DEFAULT_RETRY_OPTIONS, ...options };
+  let lastError: Error | undefined;
+  let delay = opts.initialDelay;
+
+  for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (!isRetryable(error) || attempt === opts.maxAttempts) {
+        throw error;
+      }
+
+      console.error(
+        `[DB${provider ? `:${provider}` : ''}] Operation failed (attempt ${attempt}/${opts.maxAttempts}): ${lastError.message}. Retrying in ${delay}ms...`
+      );
+
+      await sleep(delay);
+      delay = Math.min(delay * opts.backoffMultiplier, opts.maxDelay);
+    }
+  }
+
+  throw lastError;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ============================================================================
+// SQL Utilities
+// ============================================================================
+
+/**
+ * Escape SQL identifier (table name, column name)
+ * Prevents SQL injection in dynamic queries
+ */
+export function escapeIdentifier(identifier: string, provider: DatabaseType): string {
+  // Remove any existing quotes and escape internal quotes
+  const cleaned = identifier.replace(/["'`]/g, '');
+
+  switch (provider) {
+    case 'postgres':
+      return `"${cleaned}"`;
+    case 'mysql':
+      return `\`${cleaned}\``;
+    case 'sqlite':
+      return `"${cleaned}"`;
+    default:
+      return `"${cleaned}"`;
+  }
+}
+
+/**
+ * Format bytes to human readable size
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+
+/**
+ * Format duration in milliseconds to human readable
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(2)}s`;
+  if (ms < 3600000) return `${(ms / 60000).toFixed(2)}m`;
+  return `${(ms / 3600000).toFixed(2)}h`;
+}