@dotdo/postgres 0.1.0

package/src/playground/schema-explorer.ts

@@ -0,0 +1,558 @@
+/**
+ * Playground Schema Explorer
+ *
+ * Implements ISchemaExplorer for browsing database schema
+ * including tables, columns, indexes, and foreign keys.
+ *
+ * @module playground/schema-explorer
+ */
+
+import type {
+  ISchemaExplorer,
+  IQueryExecutor,
+  TableInfo,
+  TableSchema,
+  ColumnInfo,
+  IndexInfo,
+} from './types'
+
+/**
+ * SQL keywords for autocomplete
+ */
+const SQL_KEYWORDS = [
+  'SELECT',
+  'FROM',
+  'WHERE',
+  'AND',
+  'OR',
+  'NOT',
+  'IN',
+  'IS',
+  'NULL',
+  'AS',
+  'JOIN',
+  'LEFT',
+  'RIGHT',
+  'INNER',
+  'OUTER',
+  'FULL',
+  'CROSS',
+  'ON',
+  'USING',
+  'ORDER',
+  'BY',
+  'ASC',
+  'DESC',
+  'NULLS',
+  'FIRST',
+  'LAST',
+  'GROUP',
+  'HAVING',
+  'LIMIT',
+  'OFFSET',
+  'UNION',
+  'ALL',
+  'EXCEPT',
+  'INTERSECT',
+  'INSERT',
+  'INTO',
+  'VALUES',
+  'UPDATE',
+  'SET',
+  'DELETE',
+  'CREATE',
+  'TABLE',
+  'INDEX',
+  'VIEW',
+  'DROP',
+  'ALTER',
+  'ADD',
+  'COLUMN',
+  'CONSTRAINT',
+  'PRIMARY',
+  'KEY',
+  'FOREIGN',
+  'REFERENCES',
+  'UNIQUE',
+  'CHECK',
+  'DEFAULT',
+  'CASCADE',
+  'RESTRICT',
+  'BEGIN',
+  'COMMIT',
+  'ROLLBACK',
+  'SAVEPOINT',
+  'TRANSACTION',
+  'WITH',
+  'RECURSIVE',
+  'CASE',
+  'WHEN',
+  'THEN',
+  'ELSE',
+  'END',
+  'CAST',
+  'COALESCE',
+  'NULLIF',
+  'EXISTS',
+  'BETWEEN',
+  'LIKE',
+  'ILIKE',
+  'SIMILAR',
+  'DISTINCT',
+  'COUNT',
+  'SUM',
+  'AVG',
+  'MIN',
+  'MAX',
+  'ARRAY',
+  'ANY',
+  'SOME',
+  'TRUE',
+  'FALSE',
+  'RETURNING',
+  'EXPLAIN',
+  'ANALYZE',
+  'VACUUM',
+  'TRUNCATE',
+  'GRANT',
+  'REVOKE',
+  'SERIAL',
+  'BIGSERIAL',
+  'TEXT',
+  'INTEGER',
+  'BIGINT',
+  'SMALLINT',
+  'BOOLEAN',
+  'TIMESTAMP',
+  'TIMESTAMPTZ',
+  'DATE',
+  'TIME',
+  'INTERVAL',
+  'NUMERIC',
+  'DECIMAL',
+  'REAL',
+  'DOUBLE',
+  'PRECISION',
+  'VARCHAR',
+  'CHAR',
+  'JSON',
+  'JSONB',
+  'UUID',
+  'BYTEA',
+]
+
+/**
+ * Schema Explorer implementation
+ */
+export class SchemaExplorer implements ISchemaExplorer {
+  private _executor: IQueryExecutor
+  private _tablesCache: TableInfo[] | null = null
+  private _tableSchemaCache: Map<string, TableSchema> = new Map()
+
+  constructor(executor: IQueryExecutor) {
+    this._executor = executor
+  }
+
+  /**
+   * Get list of all tables
+   */
+  async getTables(): Promise<TableInfo[]> {
+    // Return cached if available
+    if (this._tablesCache !== null) {
+      return this._tablesCache
+    }
+
+    const result = await this._executor.execute<{
+      table_name: string
+      table_schema: string
+      table_type: string
+      estimated_row_count: number | null
+      size_bytes: number | null
+      size_display: string | null
+    }>({
+      sql: `
+        SELECT
+          c.relname AS table_name,
+          n.nspname AS table_schema,
+          CASE
+            WHEN c.relkind = 'r' THEN 'table'
+            WHEN c.relkind = 'v' THEN 'view'
+            WHEN c.relkind = 'm' THEN 'materialized_view'
+          END AS table_type,
+          c.reltuples::bigint AS estimated_row_count,
+          pg_relation_size(c.oid)::bigint AS size_bytes,
+          pg_size_pretty(pg_relation_size(c.oid)) AS size_display
+        FROM pg_class c
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE c.relkind IN ('r', 'v', 'm')
+          AND n.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
+        ORDER BY n.nspname, c.relname
+      `,
+    })
+
+    if (!result.success) {
+      throw new Error(result.message)
+    }
+
+    const tables: TableInfo[] = result.rows.map((row) => ({
+      name: row.table_name,
+      schema: row.table_schema,
+      type: row.table_type as 'table' | 'view' | 'materialized_view',
+      // PostgreSQL returns -1 for reltuples when stats haven't been collected yet
+      // Convert negative values to 0 for a more intuitive API
+      estimatedRowCount: row.estimated_row_count !== null && row.estimated_row_count >= 0
+        ? row.estimated_row_count
+        : (row.estimated_row_count === null ? undefined : 0),
+      sizeBytes: row.size_bytes ?? undefined,
+      sizeDisplay: row.size_display ?? undefined,
+    }))
+
+    this._tablesCache = tables
+    return tables
+  }
+
+  /**
+   * Get detailed schema for a table
+   */
+  async getTableSchema(tableName: string, schema: string = 'public'): Promise<TableSchema> {
+    const cacheKey = `${schema}.${tableName}`
+
+    // Return cached if available
+    const cached = this._tableSchemaCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    // Get table info
+    const tableInfo = await this._getTableInfo(tableName, schema)
+    if (!tableInfo) {
+      throw new Error(`Table "${schema}"."${tableName}" does not exist`)
+    }
+
+    // Get columns
+    const columns = await this._getColumns(tableName, schema)
+
+    // Get indexes
+    const indexes = await this._getIndexes(tableName, schema)
+
+    // Get referenced by (foreign keys pointing to this table)
+    const referencedBy = await this._getReferencedBy(tableName, schema)
+
+    const tableSchema: TableSchema = {
+      table: tableInfo,
+      columns,
+      indexes,
+      referencedBy,
+    }
+
+    this._tableSchemaCache.set(cacheKey, tableSchema)
+    return tableSchema
+  }
+
+  /**
+   * Get column completions for editor
+   */
+  async getCompletions(tableName?: string): Promise<string[]> {
+    const completions: string[] = []
+
+    if (tableName) {
+      // Get columns for specific table
+      try {
+        const schema = await this.getTableSchema(tableName)
+        completions.push(...schema.columns.map((col) => col.name))
+      } catch {
+        // Table doesn't exist - return empty
+      }
+      return completions
+    }
+
+    // Global completions - SQL keywords + table names + qualified columns
+    completions.push(...SQL_KEYWORDS)
+
+    // Refresh the cache to ensure we get the latest table list
+    // This is important because tables may have been created/dropped
+    // since the last call to getTables()
+    await this.refresh()
+
+    const tables = await this.getTables()
+    for (const table of tables) {
+      completions.push(table.name)
+
+      // Add qualified column names
+      try {
+        const schema = await this.getTableSchema(table.name, table.schema)
+        for (const col of schema.columns) {
+          completions.push(`${table.name}.${col.name}`)
+        }
+      } catch {
+        // Ignore errors
+      }
+    }
+
+    return completions
+  }
+
+  /**
+   * Refresh schema cache
+   */
+  async refresh(): Promise<void> {
+    this._tablesCache = null
+    this._tableSchemaCache.clear()
+  }
+
+  /**
+   * Get table info
+   */
+  private async _getTableInfo(tableName: string, schema: string): Promise<TableInfo | null> {
+    const result = await this._executor.execute<{
+      table_name: string
+      table_schema: string
+      table_type: string
+      estimated_row_count: number | null
+      size_bytes: number | null
+      size_display: string | null
+      description: string | null
+    }>({
+      sql: `
+        SELECT
+          c.relname AS table_name,
+          n.nspname AS table_schema,
+          CASE
+            WHEN c.relkind = 'r' THEN 'table'
+            WHEN c.relkind = 'v' THEN 'view'
+            WHEN c.relkind = 'm' THEN 'materialized_view'
+          END AS table_type,
+          c.reltuples::bigint AS estimated_row_count,
+          pg_relation_size(c.oid)::bigint AS size_bytes,
+          pg_size_pretty(pg_relation_size(c.oid)) AS size_display,
+          obj_description(c.oid, 'pg_class') AS description
+        FROM pg_class c
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE c.relname = $1
+          AND n.nspname = $2
+          AND c.relkind IN ('r', 'v', 'm')
+      `,
+      params: [tableName, schema],
+    })
+
+    if (!result.success || result.rows.length === 0) {
+      return null
+    }
+
+    const row = result.rows[0]
+    if (!row) {
+      return null
+    }
+    return {
+      name: row.table_name,
+      schema: row.table_schema,
+      type: row.table_type as 'table' | 'view' | 'materialized_view',
+      estimatedRowCount: row.estimated_row_count ?? undefined,
+      sizeBytes: row.size_bytes ?? undefined,
+      sizeDisplay: row.size_display ?? undefined,
+      description: row.description ?? undefined,
+    }
+  }
+
+  /**
+   * Get columns for a table
+   */
+  private async _getColumns(tableName: string, schema: string): Promise<ColumnInfo[]> {
+    const result = await this._executor.execute<{
+      column_name: string
+      data_type: string
+      is_nullable: string
+      column_default: string | null
+      position: number
+      is_primary_key: boolean
+      is_unique: boolean
+      fk_table: string | null
+      fk_column: string | null
+      description: string | null
+    }>({
+      sql: `
+        WITH pk_cols AS (
+          SELECT a.attname
+          FROM pg_constraint con
+          JOIN pg_class c ON c.oid = con.conrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(con.conkey)
+          WHERE c.relname = $1
+            AND n.nspname = $2
+            AND con.contype = 'p'
+        ),
+        unique_cols AS (
+          SELECT a.attname
+          FROM pg_constraint con
+          JOIN pg_class c ON c.oid = con.conrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(con.conkey)
+          WHERE c.relname = $1
+            AND n.nspname = $2
+            AND con.contype = 'u'
+        ),
+        fk_info AS (
+          SELECT
+            a.attname AS column_name,
+            fk_c.relname AS fk_table,
+            fk_a.attname AS fk_column
+          FROM pg_constraint con
+          JOIN pg_class c ON c.oid = con.conrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(con.conkey)
+          JOIN pg_class fk_c ON fk_c.oid = con.confrelid
+          JOIN pg_attribute fk_a ON fk_a.attrelid = fk_c.oid AND fk_a.attnum = ANY(con.confkey)
+          WHERE c.relname = $1
+            AND n.nspname = $2
+            AND con.contype = 'f'
+        )
+        SELECT
+          a.attname AS column_name,
+          pg_catalog.format_type(a.atttypid, a.atttypmod) AS data_type,
+          CASE WHEN a.attnotnull THEN 'NO' ELSE 'YES' END AS is_nullable,
+          pg_get_expr(d.adbin, d.adrelid) AS column_default,
+          a.attnum AS position,
+          EXISTS (SELECT 1 FROM pk_cols pk WHERE pk.attname = a.attname) AS is_primary_key,
+          EXISTS (SELECT 1 FROM unique_cols uk WHERE uk.attname = a.attname)
+            OR EXISTS (SELECT 1 FROM pk_cols pk WHERE pk.attname = a.attname) AS is_unique,
+          fk.fk_table,
+          fk.fk_column,
+          col_description(c.oid, a.attnum) AS description
+        FROM pg_attribute a
+        JOIN pg_class c ON c.oid = a.attrelid
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        LEFT JOIN pg_attrdef d ON d.adrelid = c.oid AND d.adnum = a.attnum
+        LEFT JOIN fk_info fk ON fk.column_name = a.attname
+        WHERE c.relname = $1
+          AND n.nspname = $2
+          AND a.attnum > 0
+          AND NOT a.attisdropped
+        ORDER BY a.attnum
+      `,
+      params: [tableName, schema],
+    })
+
+    if (!result.success) {
+      throw new Error(result.message)
+    }
+
+    return result.rows.map((row) => ({
+      name: row.column_name,
+      dataType: row.data_type,
+      nullable: row.is_nullable === 'YES',
+      defaultValue: row.column_default ?? undefined,
+      isPrimaryKey: row.is_primary_key,
+      isUnique: row.is_unique,
+      foreignKey:
+        row.fk_table && row.fk_column
+          ? { table: row.fk_table, column: row.fk_column }
+          : undefined,
+      description: row.description ?? undefined,
+      position: row.position,
+    }))
+  }
+
+  /**
+   * Get indexes for a table
+   */
+  private async _getIndexes(tableName: string, schema: string): Promise<IndexInfo[]> {
+    const result = await this._executor.execute<{
+      index_name: string
+      is_unique: boolean
+      is_primary: boolean
+      index_type: string
+      column_names: string[]
+      condition: string | null
+      size_bytes: number
+    }>({
+      sql: `
+        SELECT
+          i.relname AS index_name,
+          ix.indisunique AS is_unique,
+          ix.indisprimary AS is_primary,
+          am.amname AS index_type,
+          ARRAY(
+            SELECT a.attname
+            FROM unnest(ix.indkey) WITH ORDINALITY AS k(attnum, ord)
+            JOIN pg_attribute a ON a.attrelid = ix.indrelid AND a.attnum = k.attnum
+            ORDER BY k.ord
+          ) AS column_names,
+          pg_get_expr(ix.indpred, ix.indrelid) AS condition,
+          pg_relation_size(i.oid)::bigint AS size_bytes
+        FROM pg_index ix
+        JOIN pg_class c ON c.oid = ix.indrelid
+        JOIN pg_class i ON i.oid = ix.indexrelid
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        JOIN pg_am am ON am.oid = i.relam
+        WHERE c.relname = $1
+          AND n.nspname = $2
+        ORDER BY i.relname
+      `,
+      params: [tableName, schema],
+    })
+
+    if (!result.success) {
+      throw new Error(result.message)
+    }
+
+    return result.rows.map((row) => ({
+      name: row.index_name,
+      tableName,
+      isUnique: row.is_unique,
+      isPrimaryKey: row.is_primary,
+      indexType: row.index_type,
+      columns: row.column_names,
+      condition: row.condition ?? undefined,
+      sizeBytes: row.size_bytes,
+    }))
+  }
+
+  /**
+   * Get tables that reference this table
+   */
+  private async _getReferencedBy(
+    tableName: string,
+    schema: string
+  ): Promise<Array<{ table: string; column: string; constraintName: string }>> {
+    const result = await this._executor.execute<{
+      table_name: string
+      column_name: string
+      constraint_name: string
+    }>({
+      sql: `
+        SELECT
+          c.relname AS table_name,
+          a.attname AS column_name,
+          con.conname AS constraint_name
+        FROM pg_constraint con
+        JOIN pg_class c ON c.oid = con.conrelid
+        JOIN pg_namespace n ON n.oid = c.relnamespace
+        JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(con.conkey)
+        JOIN pg_class fk_c ON fk_c.oid = con.confrelid
+        JOIN pg_namespace fk_n ON fk_n.oid = fk_c.relnamespace
+        WHERE fk_c.relname = $1
+          AND fk_n.nspname = $2
+          AND con.contype = 'f'
+        ORDER BY c.relname, a.attname
+      `,
+      params: [tableName, schema],
+    })
+
+    if (!result.success) {
+      return []
+    }
+
+    return result.rows.map((row) => ({
+      table: row.table_name,
+      column: row.column_name,
+      constraintName: row.constraint_name,
+    }))
+  }
+}
+
+/**
+ * Create a new schema explorer
+ */
+export function createSchemaExplorer(executor: IQueryExecutor): ISchemaExplorer {
+  return new SchemaExplorer(executor)
+}