@neverinfamous/postgres-mcp 1.2.0 → 2.0.0

package/dist/adapters/postgresql/tools/introspection.js

@@ -0,0 +1,1682 @@
+/**
+ * PostgreSQL Introspection Tools
+ *
+ * Agent-optimized database analysis tools for dependency graphs,
+ * cascade simulation, schema snapshots, migration risk analysis,
+ * and schema version tracking.
+ * 11 tools total (6 read-only + 5 migration tracking).
+ */
+import { createHash } from "node:crypto";
+import { readOnly, write, destructive } from "../../../utils/annotations.js";
+import { getToolIcons } from "../../../utils/icons.js";
+import { DependencyGraphSchemaBase, DependencyGraphSchema, TopologicalSortSchemaBase, TopologicalSortSchema, CascadeSimulatorSchemaBase, CascadeSimulatorSchema, SchemaSnapshotSchemaBase, SchemaSnapshotSchema, ConstraintAnalysisSchemaBase, ConstraintAnalysisSchema, MigrationRisksSchemaBase, MigrationRisksSchema, MigrationInitSchemaBase, MigrationInitSchema, MigrationRecordSchemaBase, MigrationRecordSchema, MigrationApplySchemaBase, MigrationApplySchema, MigrationRollbackSchemaBase, MigrationRollbackSchema, MigrationHistorySchemaBase, MigrationHistorySchema, MigrationStatusSchemaBase, MigrationStatusSchema, 
+// Output schemas
+DependencyGraphOutputSchema, TopologicalSortOutputSchema, CascadeSimulatorOutputSchema, SchemaSnapshotOutputSchema, ConstraintAnalysisOutputSchema, MigrationRisksOutputSchema, MigrationInitOutputSchema, MigrationRecordOutputSchema, MigrationApplyOutputSchema, MigrationRollbackOutputSchema, MigrationHistoryOutputSchema, MigrationStatusOutputSchema, } from "../schemas/index.js";
+// =============================================================================
+// Shared queries
+// =============================================================================
+/**
+ * Fetch all foreign key relationships across user schemas
+ */
+async function fetchForeignKeys(adapter, schemaFilter, excludeExtensionSchemas) {
+    const params = [];
+    let schemaClause = "";
+    if (schemaFilter) {
+        params.push(schemaFilter);
+        schemaClause = `AND src_ns.nspname = $${String(params.length)}`;
+    }
+    const extensionSchemaExclude = !schemaFilter && excludeExtensionSchemas !== false
+        ? "AND src_ns.nspname NOT IN ('cron', 'topology', 'tiger', 'tiger_data')"
+        : "";
+    const result = await adapter.executeQuery(`SELECT
+      c.conname AS constraint_name,
+      src_ns.nspname AS from_schema,
+      src_t.relname AS from_table,
+      array_agg(DISTINCT src_a.attname ORDER BY src_a.attname) AS from_columns,
+      ref_ns.nspname AS to_schema,
+      ref_t.relname AS to_table,
+      array_agg(DISTINCT ref_a.attname ORDER BY ref_a.attname) AS to_columns,
+      CASE c.confdeltype
+        WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT'
+        WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL'
+        WHEN 'd' THEN 'SET DEFAULT'
+      END AS on_delete,
+      CASE c.confupdtype
+        WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT'
+        WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL'
+        WHEN 'd' THEN 'SET DEFAULT'
+      END AS on_update
+    FROM pg_constraint c
+    JOIN pg_class src_t ON src_t.oid = c.conrelid
+    JOIN pg_namespace src_ns ON src_ns.oid = src_t.relnamespace
+    JOIN pg_class ref_t ON ref_t.oid = c.confrelid
+    JOIN pg_namespace ref_ns ON ref_ns.oid = ref_t.relnamespace
+    JOIN pg_attribute src_a ON src_a.attrelid = src_t.oid AND src_a.attnum = ANY(c.conkey)
+    JOIN pg_attribute ref_a ON ref_a.attrelid = ref_t.oid AND ref_a.attnum = ANY(c.confkey)
+    WHERE c.contype = 'f'
+      AND src_ns.nspname NOT IN ('pg_catalog', 'information_schema')
+      AND src_ns.nspname !~ '^pg_toast'
+      ${extensionSchemaExclude}
+      ${schemaClause}
+    GROUP BY c.conname, src_ns.nspname, src_t.relname,
+             ref_ns.nspname, ref_t.relname, c.confdeltype, c.confupdtype
+    ORDER BY src_ns.nspname, src_t.relname, c.conname`, params.length > 0 ? params : undefined);
+    return (result.rows ?? []).map((row) => ({
+        constraintName: row["constraint_name"],
+        fromSchema: row["from_schema"],
+        fromTable: row["from_table"],
+        fromColumns: parseArrayColumn(row["from_columns"]),
+        toSchema: row["to_schema"],
+        toTable: row["to_table"],
+        toColumns: parseArrayColumn(row["to_columns"]),
+        onDelete: row["on_delete"],
+        onUpdate: row["on_update"],
+    }));
+}
+/**
+ * Fetch all user tables with row counts and sizes
+ */
+async function fetchTableNodes(adapter, schemaFilter, excludeExtensionSchemas) {
+    const params = [];
+    let schemaClause = "";
+    if (schemaFilter) {
+        params.push(schemaFilter);
+        schemaClause = `AND n.nspname = $${String(params.length)}`;
+    }
+    const extensionSchemaExclude = !schemaFilter && excludeExtensionSchemas !== false
+        ? "AND n.nspname NOT IN ('cron', 'topology', 'tiger', 'tiger_data')"
+        : "";
+    const result = await adapter.executeQuery(`SELECT
+      n.nspname AS schema,
+      c.relname AS table_name,
+      CASE WHEN c.reltuples = -1 THEN COALESCE(s.n_live_tup, 0)
+           ELSE c.reltuples END::bigint AS row_count,
+      pg_table_size(c.oid) AS size_bytes
+    FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
+    WHERE c.relkind IN ('r', 'p')
+      AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+      AND n.nspname !~ '^pg_toast'
+      ${extensionSchemaExclude}
+      ${schemaClause}
+    ORDER BY n.nspname, c.relname`, params.length > 0 ? params : undefined);
+    return (result.rows ?? []).map((row) => ({
+        schema: row["schema"],
+        table: row["table_name"],
+        rowCount: Number(row["row_count"]) || 0,
+        sizeBytes: Number(row["size_bytes"]) || 0,
+    }));
+}
+/**
+ * Parse PostgreSQL array column (handles both native arrays and string format)
+ */
+function parseArrayColumn(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === "string") {
+        const trimmed = value.replace(/^{|}$/g, "");
+        if (trimmed === "")
+            return [];
+        return trimmed.split(",").map((c) => c.trim().replace(/^"|"$/g, ""));
+    }
+    return [];
+}
+/**
+ * Create qualified table name
+ */
+function qualifiedName(schema, table) {
+    return `${schema}.${table}`;
+}
+// =============================================================================
+// Graph algorithms
+// =============================================================================
+/**
+ * Detect circular dependencies using DFS
+ */
+function detectCycles(adjacency) {
+    const cycles = [];
+    const visited = new Set();
+    const inStack = new Set();
+    const stack = [];
+    function dfs(node) {
+        if (inStack.has(node)) {
+            // Found a cycle - extract it from the stack
+            const cycleStart = stack.indexOf(node);
+            if (cycleStart !== -1) {
+                cycles.push([...stack.slice(cycleStart), node]);
+            }
+            return;
+        }
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        inStack.add(node);
+        stack.push(node);
+        for (const neighbor of adjacency.get(node) ?? []) {
+            dfs(neighbor);
+        }
+        stack.pop();
+        inStack.delete(node);
+    }
+    for (const node of adjacency.keys()) {
+        dfs(node);
+    }
+    return cycles;
+}
+/**
+ * Topological sort using Kahn's algorithm
+ * Returns null if cycles exist
+ */
+function topologicalSort(adjacency, allNodes) {
+    // Compute in-degrees
+    const inDegree = new Map();
+    for (const node of allNodes) {
+        inDegree.set(node, 0);
+    }
+    for (const [, neighbors] of adjacency) {
+        for (const n of neighbors) {
+            inDegree.set(n, (inDegree.get(n) ?? 0) + 1);
+        }
+    }
+    // Enqueue nodes with 0 in-degree
+    const queue = [];
+    for (const [node, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(node);
+        }
+    }
+    queue.sort(); // Deterministic ordering
+    const result = [];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        if (node === undefined)
+            break;
+        result.push(node);
+        for (const neighbor of adjacency.get(node) ?? []) {
+            const newDegree = (inDegree.get(neighbor) ?? 1) - 1;
+            inDegree.set(neighbor, newDegree);
+            if (newDegree === 0) {
+                // Insert in sorted position for deterministic output
+                const insertIdx = queue.findIndex((q) => q > neighbor);
+                if (insertIdx === -1) {
+                    queue.push(neighbor);
+                }
+                else {
+                    queue.splice(insertIdx, 0, neighbor);
+                }
+            }
+        }
+    }
+    return result.length === allNodes.size ? result : null;
+}
+/**
+ * Calculate max depth from root nodes in DAG
+ */
+function calculateMaxDepth(adjacency, roots) {
+    if (roots.length === 0)
+        return 0;
+    let maxDepth = 0;
+    const depthMap = new Map();
+    function dfs(node, depth, visited) {
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        const currentMax = depthMap.get(node) ?? -1;
+        if (depth > currentMax) {
+            depthMap.set(node, depth);
+            if (depth > maxDepth)
+                maxDepth = depth;
+        }
+        for (const neighbor of adjacency.get(node) ?? []) {
+            dfs(neighbor, depth + 1, visited);
+        }
+    }
+    for (const root of roots) {
+        dfs(root, 0, new Set());
+    }
+    return maxDepth;
+}
+// =============================================================================
+// Tool factory functions
+// =============================================================================
+/**
+ * Get all introspection tools
+ */
+export function getIntrospectionTools(adapter) {
+    return [
+        createDependencyGraphTool(adapter),
+        createTopologicalSortTool(adapter),
+        createCascadeSimulatorTool(adapter),
+        createSchemaSnapshotTool(adapter),
+        createConstraintAnalysisTool(adapter),
+        createMigrationRisksTool(adapter),
+        createMigrationInitTool(adapter),
+        createMigrationRecordTool(adapter),
+        createMigrationApplyTool(adapter),
+        createMigrationRollbackTool(adapter),
+        createMigrationHistoryTool(adapter),
+        createMigrationStatusTool(adapter),
+    ];
+}
+// =============================================================================
+// pg_dependency_graph
+// =============================================================================
+function createDependencyGraphTool(adapter) {
+    return {
+        name: "pg_dependency_graph",
+        description: "Get the full foreign key dependency graph with cascade paths, row counts, circular dependency detection, and severity assessment. Agent-optimized structured output.",
+        group: "introspection",
+        inputSchema: DependencyGraphSchemaBase,
+        outputSchema: DependencyGraphOutputSchema,
+        annotations: readOnly("Dependency Graph"),
+        icons: getToolIcons("introspection", readOnly("Dependency Graph")),
+        handler: async (params, _context) => {
+            const parsed = DependencyGraphSchema.parse(params);
+            const includeRowCounts = parsed.includeRowCounts !== false;
+            const excludeExt = parsed.excludeExtensionSchemas;
+            const [fks, tables] = await Promise.all([
+                fetchForeignKeys(adapter, parsed.schema, excludeExt),
+                includeRowCounts
+                    ? fetchTableNodes(adapter, parsed.schema, excludeExt)
+                    : Promise.resolve([]),
+            ]);
+            const tableMap = new Map(tables.map((t) => [qualifiedName(t.schema, t.table), t]));
+            // Build adjacency list (from → to, meaning "from" depends on "to")
+            const adjacency = new Map();
+            const allNodes = new Set();
+            // Ensure all tables are in the node set even if they have no FKs
+            for (const t of tables) {
+                allNodes.add(qualifiedName(t.schema, t.table));
+            }
+            for (const fk of fks) {
+                const from = qualifiedName(fk.fromSchema, fk.fromTable);
+                const to = qualifiedName(fk.toSchema, fk.toTable);
+                allNodes.add(from);
+                allNodes.add(to);
+                const existing = adjacency.get(from) ?? [];
+                existing.push(to);
+                adjacency.set(from, existing);
+            }
+            // Find root tables (no dependencies) and leaf tables (no dependents)
+            const dependents = new Set();
+            for (const [, neighbors] of adjacency) {
+                for (const n of neighbors) {
+                    dependents.add(n);
+                }
+            }
+            const rootTables = [...allNodes]
+                .filter((n) => !adjacency.has(n) || (adjacency.get(n)?.length ?? 0) === 0)
+                .sort();
+            const leafTables = [...allNodes].filter((n) => !dependents.has(n)).sort();
+            // Detect cycles
+            const cycles = detectCycles(adjacency);
+            const maxDepth = calculateMaxDepth(adjacency, leafTables);
+            // Build nodes
+            const nodes = [...allNodes].sort().map((name) => {
+                const info = tableMap.get(name);
+                const parts = name.split(".");
+                return {
+                    table: parts[1] ?? name,
+                    schema: parts[0] ?? "public",
+                    ...(includeRowCounts && info
+                        ? { rowCount: info.rowCount, sizeBytes: info.sizeBytes }
+                        : {}),
+                };
+            });
+            // Build edges
+            const edges = fks.map((fk) => ({
+                from: qualifiedName(fk.fromSchema, fk.fromTable),
+                to: qualifiedName(fk.toSchema, fk.toTable),
+                constraint: fk.constraintName,
+                columns: fk.fromColumns.map((col, i) => ({
+                    from: col,
+                    to: fk.toColumns[i] ?? col,
+                })),
+                onDelete: fk.onDelete,
+                onUpdate: fk.onUpdate,
+            }));
+            // Add hint for nonexistent/empty schema
+            const hint = parsed.schema !== undefined && allNodes.size === 0
+                ? `Schema '${parsed.schema}' returned no tables. Verify the schema exists with pg_list_schemas.`
+                : undefined;
+            return {
+                nodes,
+                edges,
+                circularDependencies: cycles,
+                stats: {
+                    totalTables: allNodes.size,
+                    totalRelationships: fks.length,
+                    maxDepth,
+                    rootTables,
+                    leafTables,
+                },
+                ...(hint !== undefined && { hint }),
+            };
+        },
+    };
+}
+// =============================================================================
+// pg_topological_sort
+// =============================================================================
+function createTopologicalSortTool(adapter) {
+    return {
+        name: "pg_topological_sort",
+        description: "Get tables in safe DDL execution order. 'create' direction: dependencies first (for CREATE TABLE). 'drop' direction: dependents first (for DROP TABLE).",
+        group: "introspection",
+        inputSchema: TopologicalSortSchemaBase,
+        outputSchema: TopologicalSortOutputSchema,
+        annotations: readOnly("Topological Sort"),
+        icons: getToolIcons("introspection", readOnly("Topological Sort")),
+        handler: async (params, _context) => {
+            const parsed = TopologicalSortSchema.parse(params);
+            const direction = parsed.direction ?? "create";
+            const excludeExt = parsed.excludeExtensionSchemas;
+            const fks = await fetchForeignKeys(adapter, parsed.schema, excludeExt);
+            const tables = await fetchTableNodes(adapter, parsed.schema, excludeExt);
+            // Build adjacency: A depends on B means A→B
+            // For "create" order, we need B before A (dependencies first)
+            // For "drop" order, we need A before B (dependents first)
+            const adjacency = new Map();
+            const allNodes = new Set();
+            for (const t of tables) {
+                allNodes.add(qualifiedName(t.schema, t.table));
+            }
+            for (const fk of fks) {
+                const from = qualifiedName(fk.fromSchema, fk.fromTable);
+                const to = qualifiedName(fk.toSchema, fk.toTable);
+                allNodes.add(from);
+                allNodes.add(to);
+            }
+            // Build dependency graph: from→to means "from depends on to"
+            const dependsOn = new Map();
+            for (const fk of fks) {
+                const from = qualifiedName(fk.fromSchema, fk.fromTable);
+                const to = qualifiedName(fk.toSchema, fk.toTable);
+                if (from === to)
+                    continue; // Self-references don't affect ordering
+                const deps = dependsOn.get(from) ?? new Set();
+                deps.add(to);
+                dependsOn.set(from, deps);
+            }
+            // For create order: edge from dependency → dependent (process deps first)
+            // For drop order: edge from dependent → dependency (process dependents first)
+            for (const fk of fks) {
+                const from = qualifiedName(fk.fromSchema, fk.fromTable);
+                const to = qualifiedName(fk.toSchema, fk.toTable);
+                if (from === to)
+                    continue; // Self-references don't affect ordering
+                if (direction === "create") {
+                    const existing = adjacency.get(to) ?? [];
+                    existing.push(from);
+                    adjacency.set(to, existing);
+                }
+                else {
+                    const existing = adjacency.get(from) ?? [];
+                    existing.push(to);
+                    adjacency.set(from, existing);
+                }
+            }
+            const sorted = topologicalSort(adjacency, allNodes);
+            const cycles = sorted === null ? detectCycles(adjacency) : [];
+            // Compute level (depth in the dependency graph)
+            // Always use create-order traversal for consistent levels regardless of direction
+            const levelMap = new Map();
+            if (sorted) {
+                // For create direction, sorted is already in dependency order.
+                // For drop direction, we need create-order to compute levels correctly.
+                let createOrder;
+                if (direction === "create") {
+                    createOrder = sorted;
+                }
+                else {
+                    // Build create-direction adjacency and sort
+                    const createAdj = new Map();
+                    for (const fk of fks) {
+                        const from = qualifiedName(fk.fromSchema, fk.fromTable);
+                        const to = qualifiedName(fk.toSchema, fk.toTable);
+                        if (from === to)
+                            continue;
+                        const existing = createAdj.get(to) ?? [];
+                        existing.push(from);
+                        createAdj.set(to, existing);
+                    }
+                    createOrder =
+                        topologicalSort(createAdj, allNodes) ?? [...allNodes].sort();
+                }
+                for (const node of createOrder) {
+                    const deps = dependsOn.get(node);
+                    if (!deps || deps.size === 0) {
+                        levelMap.set(node, 0);
+                    }
+                    else {
+                        let maxParentLevel = 0;
+                        for (const dep of deps) {
+                            const parentLevel = levelMap.get(dep) ?? 0;
+                            if (parentLevel >= maxParentLevel) {
+                                maxParentLevel = parentLevel + 1;
+                            }
+                        }
+                        levelMap.set(node, maxParentLevel);
+                    }
+                }
+            }
+            const order = (sorted ?? [...allNodes].sort()).map((name) => {
+                const parts = name.split(".");
+                return {
+                    table: parts[1] ?? name,
+                    schema: parts[0] ?? "public",
+                    level: levelMap.get(name) ?? 0,
+                    dependencies: [...(dependsOn.get(name) ?? [])].sort(),
+                };
+            });
+            // Add hint for nonexistent/empty schema
+            const hint = parsed.schema !== undefined && allNodes.size === 0
+                ? `Schema '${parsed.schema}' returned no tables. Verify the schema exists with pg_list_schemas.`
+                : undefined;
+            return {
+                order,
+                direction,
+                hasCycles: sorted === null,
+                ...(cycles.length > 0 ? { cycles } : {}),
+                ...(hint !== undefined && { hint }),
+            };
+        },
+    };
+}
+// =============================================================================
+// pg_cascade_simulator
+// =============================================================================
+function createCascadeSimulatorTool(adapter) {
+    return {
+        name: "pg_cascade_simulator",
+        description: "Simulate the impact of DELETE, DROP, or TRUNCATE on a table. Returns affected tables, estimated row counts, cascade paths, and severity assessment.",
+        group: "introspection",
+        inputSchema: CascadeSimulatorSchemaBase,
+        outputSchema: CascadeSimulatorOutputSchema,
+        annotations: readOnly("Cascade Simulator"),
+        icons: getToolIcons("introspection", readOnly("Cascade Simulator")),
+        handler: async (params, _context) => {
+            const parsed = CascadeSimulatorSchema.parse(params);
+            const schema = parsed.schema ?? "public";
+            const operation = parsed.operation ?? "DELETE";
+            const sourceQName = qualifiedName(schema, parsed.table);
+            // Cascade simulator must include ALL schemas for accurate cascade path tracing
+            const [fks, tables] = await Promise.all([
+                fetchForeignKeys(adapter, undefined, false),
+                fetchTableNodes(adapter, undefined, false),
+            ]);
+            const tableMap = new Map(tables.map((t) => [qualifiedName(t.schema, t.table), t]));
+            // Check if source table exists
+            if (!tableMap.has(sourceQName)) {
+                return {
+                    sourceTable: sourceQName,
+                    operation,
+                    affectedTables: [],
+                    severity: "low",
+                    stats: {
+                        totalTablesAffected: 0,
+                        cascadeActions: 0,
+                        blockingActions: 0,
+                        setNullActions: 0,
+                        maxDepth: 0,
+                    },
+                    error: `Table '${sourceQName}' not found. Use pg_list_tables to verify.`,
+                };
+            }
+            // Build reverse adjacency: for each table, find what references it
+            // (which tables have FKs pointing TO this table)
+            const referencedBy = new Map();
+            for (const fk of fks) {
+                const to = qualifiedName(fk.toSchema, fk.toTable);
+                const existing = referencedBy.get(to) ?? [];
+                existing.push(fk);
+                referencedBy.set(to, existing);
+            }
+            const affected = [];
+            const visited = new Set();
+            const queue = [{ tableName: sourceQName, path: [sourceQName], depth: 0 }];
+            visited.add(sourceQName);
+            let cascadeActions = 0;
+            let blockingActions = 0;
+            let setNullActions = 0;
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (current === undefined)
+                    break;
+                const refs = referencedBy.get(current.tableName) ?? [];
+                for (const ref of refs) {
+                    const refQName = qualifiedName(ref.fromSchema, ref.fromTable);
+                    if (visited.has(refQName))
+                        continue;
+                    visited.add(refQName);
+                    const action = operation === "DELETE" ? ref.onDelete : "CASCADE";
+                    const tableInfo = tableMap.get(refQName);
+                    if (action === "CASCADE") {
+                        cascadeActions++;
+                        affected.push({
+                            table: ref.fromTable,
+                            schema: ref.fromSchema,
+                            action: "CASCADE",
+                            estimatedRows: tableInfo?.rowCount,
+                            path: [...current.path, refQName],
+                            depth: current.depth + 1,
+                        });
+                        // Continue traversal for cascade
+                        queue.push({
+                            tableName: refQName,
+                            path: [...current.path, refQName],
+                            depth: current.depth + 1,
+                        });
+                    }
+                    else if (action === "RESTRICT" || action === "NO ACTION") {
+                        blockingActions++;
+                        affected.push({
+                            table: ref.fromTable,
+                            schema: ref.fromSchema,
+                            action,
+                            estimatedRows: tableInfo?.rowCount,
+                            path: [...current.path, refQName],
+                            depth: current.depth + 1,
+                        });
+                    }
+                    else if (action === "SET NULL" || action === "SET DEFAULT") {
+                        setNullActions++;
+                        affected.push({
+                            table: ref.fromTable,
+                            schema: ref.fromSchema,
+                            action,
+                            estimatedRows: tableInfo?.rowCount,
+                            path: [...current.path, refQName],
+                            depth: current.depth + 1,
+                        });
+                    }
+                }
+            }
+            const maxDepth = affected.reduce((max, a) => Math.max(max, a.depth), 0);
+            // Severity assessment
+            let severity;
+            if (blockingActions > 0) {
+                severity = "critical"; // Operation will fail
+            }
+            else if (operation !== "DELETE" && cascadeActions > 0) {
+                severity = "critical"; // DROP/TRUNCATE force-cascades everything
+            }
+            else if (cascadeActions > 5 || maxDepth > 3) {
+                severity = "high";
+            }
+            else if (cascadeActions > 0) {
+                severity = "medium";
+            }
+            else {
+                severity = "low";
+            }
+            return {
+                sourceTable: sourceQName,
+                operation,
+                affectedTables: affected,
+                severity,
+                stats: {
+                    totalTablesAffected: affected.length,
+                    cascadeActions,
+                    blockingActions,
+                    setNullActions,
+                    maxDepth,
+                },
+            };
+        },
+    };
+}
+// =============================================================================
+// pg_schema_snapshot
+// =============================================================================
+function createSchemaSnapshotTool(adapter) {
+    return {
+        name: "pg_schema_snapshot",
+        description: "Get a complete schema snapshot in a single agent-optimized JSON structure. Includes tables, columns, types, constraints, indexes, triggers, sequences, and extensions.",
+        group: "introspection",
+        inputSchema: SchemaSnapshotSchemaBase,
+        outputSchema: SchemaSnapshotOutputSchema,
+        annotations: readOnly("Schema Snapshot"),
+        icons: getToolIcons("introspection", readOnly("Schema Snapshot")),
+        handler: async (params, _context) => {
+            const parsed = SchemaSnapshotSchema.parse(params);
+            const includeAll = !parsed.sections || parsed.sections.length === 0;
+            const sections = new Set(parsed.sections ?? []);
+            const snapshot = {};
+            const stats = {
+                tables: 0,
+                views: 0,
+                indexes: 0,
+                constraints: 0,
+                functions: 0,
+                triggers: 0,
+                sequences: 0,
+                customTypes: 0,
+                extensions: 0,
+            };
+            const schemaExclude = parsed.includeSystem
+                ? ""
+                : "AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname !~ '^pg_toast'";
+            const extensionSchemaExclude = !parsed.schema &&
+                !parsed.includeSystem &&
+                parsed.excludeExtensionSchemas !== false
+                ? "AND n.nspname NOT IN ('cron', 'topology', 'tiger', 'tiger_data')"
+                : "";
+            // Exclude extension-owned objects (e.g. spatial_ref_sys, part_config) from public schema
+            const extOwnedActive = !parsed.includeSystem && parsed.excludeExtensionSchemas !== false;
+            const extOwnedClause = (oidExpr) => extOwnedActive
+                ? `AND NOT EXISTS (SELECT 1 FROM pg_depend dep WHERE dep.objid = ${oidExpr} AND dep.deptype = 'e')`
+                : "";
+            const schemaParams = [];
+            let schemaWhere = "";
+            if (parsed.schema) {
+                schemaParams.push(parsed.schema);
+                schemaWhere = `AND n.nspname = $${String(schemaParams.length)}`;
+            }
+            // Tables + columns (or compact mode without columns)
+            if (includeAll || sections.has("tables")) {
+                const columnsSubquery = parsed.compact
+                    ? ""
+                    : `,
+            (SELECT json_agg(json_build_object(
+              'name', a.attname,
+              'type', pg_catalog.format_type(a.atttypid, a.atttypmod),
+              'nullable', NOT a.attnotnull,
+              'default', pg_get_expr(d.adbin, d.adrelid),
+              'primaryKey', COALESCE((SELECT true FROM pg_constraint pk
+                WHERE pk.conrelid = a.attrelid AND a.attnum = ANY(pk.conkey)
+                AND pk.contype = 'p'), false)
+            ) ORDER BY a.attnum)
+            FROM pg_attribute a
+            LEFT JOIN pg_attrdef d ON (a.attrelid, a.attnum) = (d.adrelid, d.adnum)
+            WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+            ) AS columns`;
+                const tablesResult = await adapter.executeQuery(`SELECT
+            n.nspname AS schema, c.relname AS name,
+            CASE c.relkind WHEN 'r' THEN 'table' WHEN 'p' THEN 'partitioned_table' END AS type,
+            CASE WHEN c.reltuples = -1 THEN COALESCE(s.n_live_tup, 0) ELSE c.reltuples END::bigint AS row_count,
+            pg_table_size(c.oid) AS size_bytes,
+            obj_description(c.oid, 'pg_class') AS comment${columnsSubquery}
+          FROM pg_class c
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
+          WHERE c.relkind IN ('r', 'p')
+            ${schemaExclude} ${extensionSchemaExclude} ${extOwnedClause("c.oid")} ${schemaWhere}
+          ORDER BY n.nspname, c.relname`, schemaParams.length > 0 ? schemaParams : undefined);
+                snapshot["tables"] = tablesResult.rows ?? [];
+                stats.tables = tablesResult.rows?.length ?? 0;
+            }
+            // Views
+            if (includeAll || sections.has("views")) {
+                const viewsResult = await adapter.executeQuery(`SELECT
+            n.nspname AS schema, c.relname AS name,
+            CASE c.relkind WHEN 'v' THEN 'view' WHEN 'm' THEN 'materialized_view' END AS type,
+            pg_get_viewdef(c.oid, true) AS definition
+          FROM pg_class c
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE c.relkind IN ('v', 'm')
+            ${schemaExclude} ${extensionSchemaExclude} ${extOwnedClause("c.oid")} ${schemaWhere}
+          ORDER BY n.nspname, c.relname`, schemaParams.length > 0 ? schemaParams : undefined);
+                snapshot["views"] = viewsResult.rows ?? [];
+                stats.views = viewsResult.rows?.length ?? 0;
+            }
+            // Indexes
+            if (includeAll || sections.has("indexes")) {
+                const indexesResult = await adapter.executeQuery(`SELECT
+            i.relname AS name, t.relname AS table_name, n.nspname AS schema,
+            am.amname AS type, ix.indisunique AS is_unique,
+            pg_get_indexdef(ix.indexrelid) AS definition,
+            pg_relation_size(i.oid) AS size_bytes
+          FROM pg_index ix
+          JOIN pg_class t ON t.oid = ix.indrelid
+          JOIN pg_class i ON i.oid = ix.indexrelid
+          JOIN pg_namespace n ON n.oid = t.relnamespace
+          JOIN pg_am am ON am.oid = i.relam
+          WHERE ${parsed.includeSystem ? "true" : "n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname !~ '^pg_toast'"}
+            ${extensionSchemaExclude} ${extOwnedClause("t.oid")} ${schemaWhere}
+          ORDER BY n.nspname, t.relname, i.relname`, schemaParams.length > 0 ? schemaParams : undefined);
+                snapshot["indexes"] = indexesResult.rows ?? [];
+                stats.indexes = indexesResult.rows?.length ?? 0;
+            }
+            // Constraints
+            if (includeAll || sections.has("constraints")) {
+                const constraintsResult = await adapter.executeQuery(`SELECT
+            c.conname AS name, t.relname AS table_name, n.nspname AS schema,
+            CASE c.contype WHEN 'p' THEN 'primary_key' WHEN 'f' THEN 'foreign_key'
+              WHEN 'u' THEN 'unique' WHEN 'c' THEN 'check' WHEN 'x' THEN 'exclusion' END AS type,
+            pg_get_constraintdef(c.oid) AS definition
+          FROM pg_constraint c
+          JOIN pg_class t ON t.oid = c.conrelid
+          JOIN pg_namespace n ON n.oid = t.relnamespace
+          WHERE ${parsed.includeSystem ? "true" : "n.nspname NOT IN ('pg_catalog', 'information_schema')"}
+            ${extensionSchemaExclude} ${extOwnedClause("t.oid")} ${schemaWhere}
+          ORDER BY n.nspname, t.relname, c.conname`, schemaParams.length > 0 ? schemaParams : undefined);
+                snapshot["constraints"] = constraintsResult.rows ?? [];
+                stats.constraints = constraintsResult.rows?.length ?? 0;
+            }
+            // Functions
+            if (includeAll || sections.has("functions")) {
+                const functionsResult = await adapter.executeQuery(`SELECT
+            n.nspname AS schema, p.proname AS name,
+            pg_get_function_arguments(p.oid) AS arguments,
+            pg_get_function_result(p.oid) AS return_type,
+            l.lanname AS language, p.provolatile AS volatility
+          FROM pg_proc p
+          JOIN pg_namespace n ON n.oid = p.pronamespace
+          JOIN pg_language l ON l.oid = p.prolang
+          WHERE ${parsed.includeSystem ? "true" : "n.nspname NOT IN ('pg_catalog', 'information_schema')"}
+            ${extensionSchemaExclude} ${extOwnedClause("p.oid")} ${schemaWhere}
+          ORDER BY n.nspname, p.proname`, schemaParams.length > 0 ? schemaParams : undefined);
+                snapshot["functions"] = functionsResult.rows ?? [];
+                stats.functions = functionsResult.rows?.length ?? 0;
+            }
+            // Triggers
+            if (includeAll || sections.has("triggers")) {
+                const triggersResult = await adapter.executeQuery(`SELECT
+            t.tgname AS name, c.relname AS table_name, n.nspname AS schema,
+            CASE WHEN t.tgtype & 2 = 2 THEN 'BEFORE' WHEN t.tgtype & 64 = 64 THEN 'INSTEAD OF' ELSE 'AFTER' END AS timing,
+            array_remove(ARRAY[
+              CASE WHEN t.tgtype & 4 = 4 THEN 'INSERT' END,
+              CASE WHEN t.tgtype & 8 = 8 THEN 'DELETE' END,
+              CASE WHEN t.tgtype & 16 = 16 THEN 'UPDATE' END,
+              CASE WHEN t.tgtype & 32 = 32 THEN 'TRUNCATE' END
+            ], NULL) AS events,
+            p.proname AS function_name
+          FROM pg_trigger t
+          JOIN pg_class c ON c.oid = t.tgrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          JOIN pg_proc p ON p.oid = t.tgfoid
+          WHERE NOT t.tgisinternal
+            ${schemaExclude} ${extensionSchemaExclude} ${extOwnedClause("c.oid")} ${schemaWhere}
+          ORDER BY n.nspname, c.relname, t.tgname`, schemaParams.length > 0 ? schemaParams : undefined);
+                snapshot["triggers"] = triggersResult.rows ?? [];
+                stats.triggers = triggersResult.rows?.length ?? 0;
+            }
+            // Sequences
+            if (includeAll || sections.has("sequences")) {
+                const seqResult = await adapter.executeQuery(`SELECT
+            n.nspname AS schema, c.relname AS name,
+            (SELECT tc.relname || '.' || a.attname
+             FROM pg_depend d
+             JOIN pg_class tc ON tc.oid = d.refobjid
+             JOIN pg_attribute a ON a.attrelid = tc.oid AND a.attnum = d.refobjsubid
+             WHERE d.objid = c.oid AND d.classid = 'pg_class'::regclass AND d.deptype = 'a'
+             LIMIT 1) AS owned_by
+          FROM pg_class c
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE c.relkind = 'S'
+            ${schemaExclude} ${extensionSchemaExclude} ${extOwnedClause("c.oid")} ${schemaWhere}
+          ORDER BY n.nspname, c.relname`, schemaParams.length > 0 ? schemaParams : undefined);
+                snapshot["sequences"] = seqResult.rows ?? [];
+                stats.sequences = seqResult.rows?.length ?? 0;
+            }
+            // Custom types
+            if (includeAll || sections.has("types")) {
+                const typesResult = await adapter.executeQuery(`SELECT
+            n.nspname AS schema, t.typname AS name,
+            CASE t.typtype WHEN 'e' THEN 'enum' WHEN 'c' THEN 'composite' WHEN 'd' THEN 'domain' WHEN 'r' THEN 'range' END AS type,
+            CASE WHEN t.typtype = 'e' THEN
+              (SELECT json_agg(e.enumlabel ORDER BY e.enumsortorder) FROM pg_enum e WHERE e.enumtypid = t.oid)
+            END AS values
+          FROM pg_type t
+          JOIN pg_namespace n ON n.oid = t.typnamespace
+          WHERE t.typtype IN ('e', 'c', 'd', 'r')
+            AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+            ${extensionSchemaExclude} ${extOwnedClause("t.oid")} ${schemaWhere}
+          ORDER BY n.nspname, t.typname`, schemaParams.length > 0 ? schemaParams : undefined);
+                snapshot["types"] = typesResult.rows ?? [];
+                stats.customTypes = typesResult.rows?.length ?? 0;
+            }
+            // Extensions (skip when schema filter is active — extensions are global objects)
+            if ((includeAll || sections.has("extensions")) && !parsed.schema) {
+                const extResult = await adapter.executeQuery(`SELECT extname AS name, extversion AS version,
+                  n.nspname AS schema
+           FROM pg_extension e
+           JOIN pg_namespace n ON n.oid = e.extnamespace
+           ORDER BY e.extname`);
+                snapshot["extensions"] = extResult.rows ?? [];
+                stats.extensions = extResult.rows?.length ?? 0;
+            }
+            // Add hint for nonexistent/empty schema
+            const allEmpty = Object.values(stats).every((v) => v === 0);
+            const hint = parsed.schema !== undefined && allEmpty
+                ? `Schema '${parsed.schema}' returned no tables. Verify the schema exists with pg_list_schemas.`
+                : undefined;
+            return {
+                snapshot,
+                stats,
+                generatedAt: new Date().toISOString(),
+                ...(parsed.compact && { compact: true }),
+                ...(hint !== undefined && { hint }),
+            };
+        },
+    };
+}
+// =============================================================================
+// pg_constraint_analysis
+// =============================================================================
+function createConstraintAnalysisTool(adapter) {
+    return {
+        name: "pg_constraint_analysis",
+        description: "Analyze all constraints for issues: redundant indexes, missing foreign keys, missing NOT NULL, missing primary keys, and unindexed foreign keys.",
+        group: "introspection",
+        inputSchema: ConstraintAnalysisSchemaBase,
+        outputSchema: ConstraintAnalysisOutputSchema,
+        annotations: readOnly("Constraint Analysis"),
+        icons: getToolIcons("introspection", readOnly("Constraint Analysis")),
+        handler: async (params, _context) => {
+            const parsed = ConstraintAnalysisSchema.parse(params);
+            const runAll = !parsed.checks || parsed.checks.length === 0;
+            const checks = new Set(parsed.checks ?? []);
+            const findings = [];
+            const schemaParams = [];
+            let schemaWhere = "";
+            let tableWhere = "";
+            if (parsed.schema) {
+                schemaParams.push(parsed.schema);
+                schemaWhere = `AND n.nspname = $${String(schemaParams.length)}`;
+            }
+            if (parsed.table) {
+                schemaParams.push(parsed.table);
+                tableWhere = `AND c.relname = $${String(schemaParams.length)}`;
+            }
+            const extensionSchemaExclude = !parsed.schema &&
+                !parsed.table &&
+                parsed.excludeExtensionSchemas !== false
+                ? "AND n.nspname NOT IN ('cron', 'topology', 'tiger', 'tiger_data')"
+                : "";
+            // Check: Tables without primary keys
+            if (runAll || checks.has("missing_pk")) {
+                const result = await adapter.executeQuery(`SELECT n.nspname AS schema, c.relname AS table_name
+           FROM pg_class c
+           JOIN pg_namespace n ON n.oid = c.relnamespace
+           WHERE c.relkind IN ('r', 'p')
+             AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+             AND n.nspname !~ '^pg_toast'
+             AND NOT EXISTS (
+               SELECT 1 FROM pg_constraint pk
+               WHERE pk.conrelid = c.oid AND pk.contype = 'p'
+             )
+             ${extensionSchemaExclude} ${schemaWhere} ${tableWhere}
+           ORDER BY n.nspname, c.relname`, schemaParams.length > 0 ? schemaParams : undefined);
+                for (const row of result.rows ?? []) {
+                    findings.push({
+                        type: "missing_pk",
+                        severity: "error",
+                        table: qualifiedName(row["schema"], row["table_name"]),
+                        description: "Table has no primary key",
+                        suggestion: "Add a primary key column (e.g., id SERIAL PRIMARY KEY) for data integrity and efficient lookups",
+                    });
+                }
+            }
+            // Check: Unindexed foreign keys
+            if (runAll || checks.has("unindexed_fk")) {
+                const result = await adapter.executeQuery(`SELECT
+            n.nspname AS schema, t.relname AS table_name,
+            c.conname AS constraint_name,
+            array_agg(a.attname ORDER BY x.ordinality) AS columns
+          FROM pg_constraint c
+          JOIN pg_class t ON t.oid = c.conrelid
+          JOIN pg_namespace n ON n.oid = t.relnamespace
+          CROSS JOIN LATERAL unnest(c.conkey) WITH ORDINALITY AS x(attnum, ordinality)
+          JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = x.attnum
+          WHERE c.contype = 'f'
+            AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+            ${extensionSchemaExclude}
+            AND NOT EXISTS (
+              SELECT 1 FROM pg_index ix
+              WHERE ix.indrelid = t.oid
+                AND c.conkey <@ ix.indkey::smallint[]
+            )
+            ${schemaWhere} ${tableWhere.replace("c.relname", "t.relname")}
+          GROUP BY n.nspname, t.relname, c.conname
+          ORDER BY n.nspname, t.relname`, schemaParams.length > 0 ? schemaParams : undefined);
+                for (const row of result.rows ?? []) {
+                    const cols = parseArrayColumn(row["columns"]);
+                    findings.push({
+                        type: "unindexed_fk",
+                        severity: "warning",
+                        table: qualifiedName(row["schema"], row["table_name"]),
+                        description: `Foreign key '${row["constraint_name"]}' on column(s) [${cols.join(", ")}] has no supporting index`,
+                        suggestion: `CREATE INDEX ON ${qualifiedName(row["schema"], row["table_name"])} (${cols.join(", ")})`,
+                    });
+                }
+            }
+            // Check: Tables with columns that likely should have NOT NULL
+            if (runAll || checks.has("missing_not_null")) {
+                const result = await adapter.executeQuery(`SELECT
+            n.nspname AS schema, c.relname AS table_name,
+            a.attname AS column_name, pg_catalog.format_type(a.atttypid, a.atttypmod) AS type
+          FROM pg_attribute a
+          JOIN pg_class c ON c.oid = a.attrelid
+          JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE c.relkind IN ('r', 'p')
+            AND a.attnum > 0 AND NOT a.attisdropped AND a.attnotnull = false
+            AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+            AND n.nspname !~ '^pg_toast'
+            ${extensionSchemaExclude}
+            AND a.attname IN ('id', 'uuid', 'email', 'name', 'created_at', 'updated_at', 'status', 'type')
+            AND NOT EXISTS (SELECT 1 FROM pg_constraint pk WHERE pk.conrelid = c.oid AND a.attnum = ANY(pk.conkey) AND pk.contype = 'p')
+            ${schemaWhere} ${tableWhere}
+          ORDER BY n.nspname, c.relname, a.attname`, schemaParams.length > 0 ? schemaParams : undefined);
+                for (const row of result.rows ?? []) {
+                    findings.push({
+                        type: "missing_not_null",
+                        severity: "info",
+                        table: qualifiedName(row["schema"], row["table_name"]),
+                        description: `Column '${row["column_name"]}' (${row["type"]}) is nullable but commonly expected to be NOT NULL`,
+                        suggestion: `ALTER TABLE ${qualifiedName(row["schema"], row["table_name"])} ALTER COLUMN "${row["column_name"]}" SET NOT NULL`,
+                    });
+                }
+            }
+            // Build summary
+            const byType = {};
+            const bySeverity = {};
+            for (const f of findings) {
+                byType[f.type] = (byType[f.type] ?? 0) + 1;
+                bySeverity[f.severity] = (bySeverity[f.severity] ?? 0) + 1;
+            }
+            // Add hint for nonexistent table
+            const hint = parsed.table !== undefined && findings.length === 0
+                ? `No findings for table '${parsed.schema ? parsed.schema + "." : "public."}${parsed.table}'. Verify the table exists with pg_list_tables.`
+                : undefined;
+            return {
+                findings,
+                summary: {
+                    totalFindings: findings.length,
+                    byType,
+                    bySeverity,
+                },
+                ...(hint !== undefined && { hint }),
+            };
+        },
+    };
+}
+// =============================================================================
+// pg_migration_risks
+// =============================================================================
+/** DDL patterns and their associated risks */
+const DDL_RISK_PATTERNS = [
+    {
+        pattern: /\bDROP\s+TABLE\b/i,
+        category: "data_loss",
+        riskLevel: "critical",
+        description: "DROP TABLE permanently deletes the table and all its data",
+        mitigation: "Back up the table first (pg_dump_table), verify no active references",
+        requiresDowntime: false,
+        lockImpact: "ACCESS EXCLUSIVE on the table",
+    },
+    {
+        pattern: /\bTRUNCATE\b/i,
+        category: "data_loss",
+        riskLevel: "critical",
+        description: "TRUNCATE removes all rows from the table",
+        mitigation: "Verify you intend to delete all data, check CASCADE effects",
+        requiresDowntime: false,
+        lockImpact: "ACCESS EXCLUSIVE on the table",
+    },
+    {
+        pattern: /\bDROP\s+COLUMN\b/i,
+        category: "data_loss",
+        riskLevel: "high",
+        description: "DROP COLUMN permanently removes the column and its data",
+        mitigation: "Back up the column data first, verify no application dependencies",
+        requiresDowntime: false,
+        lockImpact: "ACCESS EXCLUSIVE on the table",
+    },
+    {
+        pattern: /\bALTER\s+(?:TABLE|COLUMN)\b.*\bSET\s+NOT\s+NULL\b/i,
+        category: "constraint",
+        riskLevel: "high",
+        description: "Adding NOT NULL requires a full table scan to verify no NULL values exist",
+        mitigation: "First check for NULLs: SELECT COUNT(*) FROM table WHERE column IS NULL",
+        requiresDowntime: false,
+        lockImpact: "ACCESS EXCLUSIVE during verification scan",
+    },
+    {
+        pattern: /\bALTER\s+TABLE\b.*\bADD\s+(?:CONSTRAINT\b.*\b)?FOREIGN\s+KEY\b/i,
+        category: "constraint",
+        riskLevel: "medium",
+        description: "Adding a foreign key requires validating all existing rows",
+        mitigation: "Use NOT VALID to skip validation, then VALIDATE CONSTRAINT separately",
+        requiresDowntime: false,
+        lockImpact: "SHARE ROW EXCLUSIVE on both tables",
+    },
+    {
+        pattern: /\bALTER\s+TABLE\b.*\bADD\s+COLUMN\b/i,
+        category: "schema_change",
+        riskLevel: "low",
+        description: "Adding a nullable column without a default is a metadata-only change",
+        requiresDowntime: false,
+        lockImpact: "ACCESS EXCLUSIVE (very brief)",
+    },
+    {
+        pattern: /\bALTER\s+TABLE\b.*\bADD\s+COLUMN\b.*\bDEFAULT\b/i,
+        category: "schema_change",
+        riskLevel: "medium",
+        description: "Adding a column with a volatile DEFAULT may require rewriting all rows (PG < 11) or is metadata-only (PG >= 11)",
+        mitigation: "On PG >= 11, this is usually fast. On older versions, consider adding without default then updating",
+        requiresDowntime: false,
+        lockImpact: "ACCESS EXCLUSIVE (metadata-only on PG >= 11)",
+    },
+    {
+        pattern: /\bALTER\s+TABLE\b.*\bALTER\s+COLUMN\b.*\bTYPE\b/i,
+        category: "schema_change",
+        riskLevel: "high",
+        description: "Changing column type requires rewriting the entire table",
+        mitigation: "Consider creating a new column, migrating data, then dropping the old one",
+        requiresDowntime: true,
+        lockImpact: "ACCESS EXCLUSIVE for the entire rewrite",
+    },
+    {
+        pattern: /\bCREATE\s+INDEX\b(?!\s+CONCURRENTLY)/i,
+        category: "locking",
+        riskLevel: "high",
+        description: "CREATE INDEX (non-concurrent) blocks writes to the table for the entire build duration",
+        mitigation: "Use CREATE INDEX CONCURRENTLY to avoid blocking writes",
+        requiresDowntime: false,
+        lockImpact: "SHARE lock on the table (blocks INSERT/UPDATE/DELETE)",
+    },
+    {
+        pattern: /\bCREATE\s+INDEX\s+CONCURRENTLY\b/i,
+        category: "locking",
+        riskLevel: "low",
+        description: "CREATE INDEX CONCURRENTLY allows concurrent writes but takes longer",
+        requiresDowntime: false,
+        lockImpact: "No blocking locks (uses ShareUpdateExclusiveLock)",
+    },
+    {
+        pattern: /\bDROP\s+INDEX\b(?!\s+CONCURRENTLY)/i,
+        category: "locking",
+        riskLevel: "medium",
+        description: "DROP INDEX blocks writes briefly. May degrade query performance",
+        mitigation: "Use DROP INDEX CONCURRENTLY in production, verify no critical queries depend on it",
+        requiresDowntime: false,
+        lockImpact: "ACCESS EXCLUSIVE (brief)",
+    },
+    {
+        pattern: /\bRENAME\s+(?:TABLE|COLUMN|TO)\b/i,
+        category: "breaking_change",
+        riskLevel: "high",
+        description: "Renaming a table or column will break any application queries referencing the old name",
+        mitigation: "Create a view with the old name pointing to the new name for backward compatibility",
+        requiresDowntime: false,
+        lockImpact: "ACCESS EXCLUSIVE (brief)",
+    },
+    {
+        pattern: /\bDROP\s+SCHEMA\b.*\bCASCADE\b/i,
+        category: "data_loss",
+        riskLevel: "critical",
+        description: "DROP SCHEMA CASCADE deletes the schema and ALL objects within it",
+        mitigation: "List all objects in the schema first, verify intent, and back up critical data",
+        requiresDowntime: false,
+        lockImpact: "ACCESS EXCLUSIVE on all objects in the schema",
+    },
+];
+function createMigrationRisksTool(adapter) {
+    return {
+        name: "pg_migration_risks",
+        description: "Analyze proposed DDL statements for risks: data loss, lock contention, constraint violations, and breaking changes. Pre-flight check before executing migrations.",
+        group: "introspection",
+        inputSchema: MigrationRisksSchemaBase,
+        outputSchema: MigrationRisksOutputSchema,
+        annotations: readOnly("Migration Risks"),
+        icons: getToolIcons("introspection", readOnly("Migration Risks")),
+        handler: (params, _context) => Promise.resolve().then(() => {
+            // adapter is available for future enhancements (e.g., checking table existence)
+            void adapter;
+            const parsed = MigrationRisksSchema.parse(params);
+            const risks = [];
+            let requiresDowntime = false;
+            let highestRiskLevel = "low";
+            const lockImpacts = new Set();
+            const riskOrder = { low: 0, medium: 1, high: 2, critical: 3 };
+            for (let i = 0; i < parsed.statements.length; i++) {
+                const stmt = parsed.statements[i] ?? "";
+                for (const pattern of DDL_RISK_PATTERNS) {
+                    if (pattern.pattern.test(stmt)) {
+                        risks.push({
+                            statement: stmt.length > 200 ? stmt.slice(0, 200) + "..." : stmt,
+                            statementIndex: i,
+                            riskLevel: pattern.riskLevel,
+                            category: pattern.category,
+                            description: pattern.description,
+                            mitigation: pattern.mitigation,
+                        });
+                        if (pattern.requiresDowntime) {
+                            requiresDowntime = true;
+                        }
+                        if (riskOrder[pattern.riskLevel] > riskOrder[highestRiskLevel]) {
+                            highestRiskLevel = pattern.riskLevel;
+                        }
+                        lockImpacts.add(pattern.lockImpact);
+                    }
+                }
+            }
+            return {
+                risks,
+                summary: {
+                    totalStatements: parsed.statements.length,
+                    totalRisks: risks.length,
+                    highestRisk: highestRiskLevel,
+                    requiresDowntime,
+                    estimatedLockImpact: lockImpacts.size > 0 ? [...lockImpacts].join("; ") : "None",
+                },
+            };
+        }),
+    };
+}
+// =============================================================================
+// Migration tracking — shared helpers
+// =============================================================================
+const TRACKING_TABLE = "_mcp_schema_versions";
+const CREATE_TRACKING_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS ${TRACKING_TABLE} (
+  id SERIAL PRIMARY KEY,
+  version VARCHAR(50) NOT NULL,
+  description TEXT,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  applied_by VARCHAR(255),
+  migration_hash VARCHAR(64) NOT NULL,
+  migration_sql TEXT NOT NULL,
+  source_system VARCHAR(50),
+  rollback_sql TEXT,
+  status VARCHAR(20) NOT NULL DEFAULT 'applied',
+  CONSTRAINT valid_status CHECK (status IN ('applied', 'rolled_back', 'failed'))
+)`;
+/**
+ * Ensure the _mcp_schema_versions table exists.
+ * Returns true if the table was newly created, false if it already existed.
+ */
+async function ensureTrackingTable(adapter) {
+    const check = await adapter.executeQuery(`SELECT EXISTS (
+      SELECT 1 FROM pg_tables
+      WHERE schemaname = 'public' AND tablename = $1
+    ) AS "table_exists"`, [TRACKING_TABLE]);
+    const firstRow = (check.rows ?? [])[0];
+    const existed = firstRow?.["table_exists"] === true;
+    if (!existed) {
+        await adapter.executeQuery(CREATE_TRACKING_TABLE_SQL);
+    }
+    return !existed;
+}
+function hashMigrationSql(sql) {
+    return createHash("sha256").update(sql).digest("hex");
+}
+function formatRecord(row) {
+    const appliedAt = row["applied_at"];
+    const appliedAtStr = appliedAt instanceof Date
+        ? appliedAt.toISOString()
+        : (appliedAt ?? "");
+    return {
+        id: row["id"],
+        version: row["version"],
+        description: row["description"] ?? null,
+        appliedAt: appliedAtStr,
+        appliedBy: row["applied_by"] ?? null,
+        migrationHash: row["migration_hash"],
+        sourceSystem: row["source_system"] ?? null,
+        status: row["status"],
+    };
+}
+// =============================================================================
+// pg_migration_init
+// =============================================================================
+function createMigrationInitTool(adapter) {
+    const annotations = write("Initialize migration tracking");
+    return {
+        name: "pg_migration_init",
+        description: "Initialize or verify the schema version tracking table (_mcp_schema_versions). " +
+            "Idempotent — safe to call repeatedly. Returns current tracking state.",
+        group: "introspection",
+        inputSchema: MigrationInitSchemaBase,
+        outputSchema: MigrationInitOutputSchema,
+        annotations,
+        icons: getToolIcons("introspection", annotations),
+        handler: async (params, _context) => {
+            const parsed = MigrationInitSchema.parse(params);
+            const targetSchema = parsed.schema ?? "public";
+            // Create table in target schema
+            const createSql = targetSchema === "public"
+                ? CREATE_TRACKING_TABLE_SQL
+                : CREATE_TRACKING_TABLE_SQL.replace(TRACKING_TABLE, `${targetSchema}.${TRACKING_TABLE}`);
+            const check = await adapter.executeQuery(`SELECT EXISTS (
+          SELECT 1 FROM pg_tables
+          WHERE schemaname = $1 AND tablename = $2
+        ) AS "table_exists"`, [targetSchema, TRACKING_TABLE]);
+            const firstRow = (check.rows ?? [])[0];
+            const existed = firstRow?.["table_exists"] === true;
+            if (!existed) {
+                await adapter.executeQuery(createSql);
+            }
+            const qualifiedTable = targetSchema === "public"
+                ? TRACKING_TABLE
+                : `${targetSchema}.${TRACKING_TABLE}`;
+            const countResult = await adapter.executeQuery(`SELECT COUNT(*)::int AS count FROM ${qualifiedTable}`);
+            const countRow = (countResult.rows ?? [])[0];
+            const existingRecords = countRow?.["count"] ?? 0;
+            return {
+                success: true,
+                tableCreated: !existed,
+                tableName: qualifiedTable,
+                existingRecords,
+            };
+        },
+    };
+}
+// =============================================================================
+// pg_migration_record
+// =============================================================================
+function createMigrationRecordTool(adapter) {
+    const annotations = write("Record migration");
+    return {
+        name: "pg_migration_record",
+        description: "Record a migration in the schema version tracking table. " +
+            "Auto-provisions the tracking table on first use. " +
+            "Computes SHA-256 hash for idempotency detection.",
+        group: "introspection",
+        inputSchema: MigrationRecordSchemaBase,
+        outputSchema: MigrationRecordOutputSchema,
+        annotations,
+        icons: getToolIcons("introspection", annotations),
+        handler: async (params, _context) => {
+            let parsed;
+            try {
+                parsed = MigrationRecordSchema.parse(params);
+            }
+            catch (error) {
+                if (error !== null &&
+                    typeof error === "object" &&
+                    "issues" in error &&
+                    Array.isArray(error.issues)) {
+                    const issues = error.issues;
+                    const messages = issues.map((i) => i.message).join("; ");
+                    return {
+                        success: false,
+                        error: `Validation error: ${messages}`,
+                    };
+                }
+                throw error;
+            }
+            await ensureTrackingTable(adapter);
+            const migrationHash = hashMigrationSql(parsed.migrationSql);
+            // Check for duplicate hash
+            const dupCheck = await adapter.executeQuery(`SELECT id, version, status FROM ${TRACKING_TABLE}
+         WHERE migration_hash = $1 AND status = 'applied'`, [migrationHash]);
+            const dupRows = dupCheck.rows ?? [];
+            if (dupRows.length > 0) {
+                const dup = dupRows[0] ?? {};
+                const dupId = dup["id"];
+                const dupVersion = dup["version"];
+                return {
+                    success: false,
+                    error: `Duplicate migration detected: version "${dupVersion}" (id: ${String(dupId)}) has the same SQL hash. ` +
+                        `Use a different migration SQL or roll back the existing one first.`,
+                };
+            }
+            const result = await adapter.executeQuery(`INSERT INTO ${TRACKING_TABLE}
+         (version, description, applied_by, migration_hash, migration_sql, source_system, rollback_sql)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)
+         RETURNING *`, [
+                parsed.version,
+                parsed.description ?? null,
+                parsed.appliedBy ?? null,
+                migrationHash,
+                parsed.migrationSql,
+                parsed.sourceSystem ?? null,
+                parsed.rollbackSql ?? null,
+            ]);
+            const resultRows = result.rows ?? [];
+            if (resultRows.length === 0) {
+                return {
+                    success: false,
+                    error: "Failed to insert migration record.",
+                };
+            }
+            const row = resultRows[0] ?? {};
+            return {
+                success: true,
+                record: formatRecord(row),
+            };
+        },
+    };
+}
+// =============================================================================
+// pg_migration_apply
+// =============================================================================
+function createMigrationApplyTool(adapter) {
+    const annotations = destructive("Apply migration");
+    return {
+        name: "pg_migration_apply",
+        description: "Execute migration SQL and record it atomically in a single transaction. " +
+            "Auto-provisions the tracking table on first use. " +
+            "On failure, rolls back and records a 'failed' entry. " +
+            "Use pg_migration_record instead if you only need to log an already-applied migration.",
+        group: "introspection",
+        inputSchema: MigrationApplySchemaBase,
+        outputSchema: MigrationApplyOutputSchema,
+        annotations,
+        icons: getToolIcons("introspection", annotations),
+        handler: async (params, _context) => {
+            let parsed;
+            try {
+                parsed = MigrationApplySchema.parse(params);
+            }
+            catch (error) {
+                if (error !== null &&
+                    typeof error === "object" &&
+                    "issues" in error &&
+                    Array.isArray(error.issues)) {
+                    const issues = error.issues;
+                    const messages = issues.map((i) => i.message).join("; ");
+                    return {
+                        success: false,
+                        error: `Validation error: ${messages}`,
+                    };
+                }
+                throw error;
+            }
+            await ensureTrackingTable(adapter);
+            const migrationHash = hashMigrationSql(parsed.migrationSql);
+            // Check for duplicate hash
+            const dupCheck = await adapter.executeQuery(`SELECT id, version, status FROM ${TRACKING_TABLE}
+         WHERE migration_hash = $1 AND status = 'applied'`, [migrationHash]);
+            const dupRows = dupCheck.rows ?? [];
+            if (dupRows.length > 0) {
+                const dup = dupRows[0] ?? {};
+                const dupId = dup["id"];
+                const dupVersion = dup["version"];
+                return {
+                    success: false,
+                    error: `Duplicate migration detected: version "${dupVersion}" (id: ${String(dupId)}) has the same SQL hash. ` +
+                        `Use a different migration SQL or roll back the existing one first.`,
+                };
+            }
+            // Execute migration SQL and record atomically
+            try {
+                await adapter.executeQuery("BEGIN");
+                // Execute the migration SQL
+                await adapter.executeQuery(parsed.migrationSql);
+                // Record in tracking table
+                const result = await adapter.executeQuery(`INSERT INTO ${TRACKING_TABLE}
+           (version, description, applied_by, migration_hash, migration_sql, source_system, rollback_sql)
+           VALUES ($1, $2, $3, $4, $5, $6, $7)
+           RETURNING *`, [
+                    parsed.version,
+                    parsed.description ?? null,
+                    parsed.appliedBy ?? null,
+                    migrationHash,
+                    parsed.migrationSql,
+                    parsed.sourceSystem ?? null,
+                    parsed.rollbackSql ?? null,
+                ]);
+                await adapter.executeQuery("COMMIT");
+                const resultRows = result.rows ?? [];
+                if (resultRows.length === 0) {
+                    return {
+                        success: false,
+                        error: "Migration was applied but failed to insert tracking record.",
+                    };
+                }
+                const row = resultRows[0] ?? {};
+                return {
+                    success: true,
+                    record: formatRecord(row),
+                };
+            }
+            catch (err) {
+                // Roll back the entire transaction (migration SQL + INSERT)
+                await adapter.executeQuery("ROLLBACK");
+                const message = err instanceof Error ? err.message : "Unknown error";
+                // Record a 'failed' entry outside the rolled-back transaction
+                try {
+                    await adapter.executeQuery(`INSERT INTO ${TRACKING_TABLE}
+             (version, description, applied_by, migration_hash, migration_sql, source_system, rollback_sql, status)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, 'failed')`, [
+                        parsed.version,
+                        parsed.description ?? null,
+                        parsed.appliedBy ?? null,
+                        migrationHash,
+                        parsed.migrationSql,
+                        parsed.sourceSystem ?? null,
+                        parsed.rollbackSql ?? null,
+                    ]);
+                }
+                catch {
+                    // Best-effort: if we can't record the failure, still return the error
+                }
+                return {
+                    success: false,
+                    error: `Migration "${parsed.version}" failed: ${message}. Transaction was rolled back.`,
+                };
+            }
+        },
+    };
+}
+// =============================================================================
+// pg_migration_rollback
+// =============================================================================
+function createMigrationRollbackTool(adapter) {
+    const annotations = destructive("Roll back migration");
+    return {
+        name: "pg_migration_rollback",
+        description: "Roll back a specific migration by ID or version. " +
+            "Executes the stored rollback_sql in a transaction and updates status to 'rolled_back'. " +
+            "Use dryRun: true to preview the rollback SQL without executing.",
+        group: "introspection",
+        inputSchema: MigrationRollbackSchemaBase,
+        outputSchema: MigrationRollbackOutputSchema,
+        annotations,
+        icons: getToolIcons("introspection", annotations),
+        handler: async (params, _context) => {
+            const parsed = MigrationRollbackSchema.parse(params);
+            await ensureTrackingTable(adapter);
+            if (parsed.id === undefined && parsed.version === undefined) {
+                return {
+                    success: false,
+                    error: "Either 'id' or 'version' is required to identify the migration to roll back.",
+                };
+            }
+            // Find the migration
+            const whereClause = parsed.id !== undefined ? "id = $1" : "version = $1";
+            const whereValue = parsed.id ?? parsed.version;
+            const findResult = await adapter.executeQuery(`SELECT * FROM ${TRACKING_TABLE} WHERE ${whereClause} ORDER BY id DESC LIMIT 1`, [whereValue]);
+            const findRows = findResult.rows ?? [];
+            if (findRows.length === 0) {
+                const identifier = parsed.id !== undefined
+                    ? `id ${String(parsed.id)}`
+                    : `version "${parsed.version ?? ""}"`;
+                return {
+                    success: false,
+                    error: `Migration not found: ${identifier}`,
+                };
+            }
+            const row = findRows[0] ?? {};
+            const rowId = row["id"];
+            const rowVersion = row["version"];
+            const rowStatus = row["status"];
+            const rollbackSql = row["rollback_sql"] ?? null;
+            if (rowStatus === "rolled_back") {
+                return {
+                    success: false,
+                    error: `Migration "${rowVersion}" (id: ${String(rowId)}) has already been rolled back.`,
+                };
+            }
+            if (rollbackSql === null) {
+                return {
+                    success: false,
+                    error: `Migration "${rowVersion}" (id: ${String(rowId)}) has no rollback SQL stored. Manual rollback required.`,
+                };
+            }
+            if (parsed.dryRun === true) {
+                return {
+                    success: true,
+                    dryRun: true,
+                    rollbackSql,
+                    record: formatRecord(row),
+                };
+            }
+            // Execute rollback in a transaction
+            try {
+                await adapter.executeQuery("BEGIN");
+                await adapter.executeQuery(rollbackSql);
+                await adapter.executeQuery(`UPDATE ${TRACKING_TABLE} SET status = 'rolled_back' WHERE id = $1`, [rowId]);
+                await adapter.executeQuery("COMMIT");
+                return {
+                    success: true,
+                    dryRun: false,
+                    rollbackSql,
+                    record: {
+                        ...formatRecord(row),
+                        status: "rolled_back",
+                    },
+                };
+            }
+            catch (err) {
+                await adapter.executeQuery("ROLLBACK");
+                const message = err instanceof Error ? err.message : "Unknown error";
+                return {
+                    success: false,
+                    error: `Rollback failed for migration "${rowVersion}" (id: ${String(rowId)}): ${message}. Transaction was rolled back.`,
+                };
+            }
+        },
+    };
+}
+// =============================================================================
+// pg_migration_history
+// =============================================================================
+function createMigrationHistoryTool(adapter) {
+    const annotations = readOnly("Migration history");
+    return {
+        name: "pg_migration_history",
+        description: "Query migration history with optional filtering by status and source system. " +
+            "Returns paginated results ordered by applied_at descending.",
+        group: "introspection",
+        inputSchema: MigrationHistorySchemaBase,
+        outputSchema: MigrationHistoryOutputSchema,
+        annotations,
+        icons: getToolIcons("introspection", annotations),
+        handler: async (params, _context) => {
+            const parsed = MigrationHistorySchema.parse(params);
+            await ensureTrackingTable(adapter);
+            const limit = parsed.limit ?? 50;
+            const offset = parsed.offset ?? 0;
+            // Build dynamic WHERE clause
+            const conditions = [];
+            const values = [];
+            let paramIdx = 1;
+            if (parsed.status != null) {
+                conditions.push(`status = $${String(paramIdx)}`);
+                paramIdx++;
+                values.push(parsed.status);
+            }
+            if (parsed.sourceSystem != null) {
+                conditions.push(`source_system = $${String(paramIdx)}`);
+                paramIdx++;
+                values.push(parsed.sourceSystem);
+            }
+            const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+            // Get total count
+            const countResult = await adapter.executeQuery(`SELECT COUNT(*)::int AS count FROM ${TRACKING_TABLE} ${whereClause}`, values.length > 0 ? values : undefined);
+            const countRow = (countResult.rows ?? [])[0];
+            const total = countRow?.["count"] ?? 0;
+            // Get page of results (exclude migration_sql for payload efficiency)
+            const limitIdx = String(paramIdx);
+            paramIdx++;
+            const offsetIdx = String(paramIdx);
+            const dataResult = await adapter.executeQuery(`SELECT id, version, description, applied_at, applied_by,
+                migration_hash, source_system, rollback_sql IS NOT NULL AS has_rollback, status
+         FROM ${TRACKING_TABLE}
+         ${whereClause}
+         ORDER BY applied_at DESC
+         LIMIT $${limitIdx} OFFSET $${offsetIdx}`, [...values, limit, offset]);
+            const records = (dataResult.rows ?? []).map(formatRecord);
+            return {
+                records,
+                total,
+                limit,
+                offset,
+            };
+        },
+    };
+}
+// =============================================================================
+// pg_migration_status
+// =============================================================================
+function createMigrationStatusTool(adapter) {
+    const annotations = readOnly("Migration status");
+    return {
+        name: "pg_migration_status",
+        description: "Get current migration tracking status: latest version, counts by status, " +
+            "and list of source systems. Returns initialized: false if tracking table doesn't exist.",
+        group: "introspection",
+        inputSchema: MigrationStatusSchemaBase,
+        outputSchema: MigrationStatusOutputSchema,
+        annotations,
+        icons: getToolIcons("introspection", annotations),
+        handler: async (params, _context) => {
+            const parsed = MigrationStatusSchema.parse(params);
+            const targetSchema = parsed.schema ?? "public";
+            // Check if tracking table exists
+            const check = await adapter.executeQuery(`SELECT EXISTS (
+          SELECT 1 FROM pg_tables
+          WHERE schemaname = $1 AND tablename = $2
+        ) AS "table_exists"`, [targetSchema, TRACKING_TABLE]);
+            const firstRow = (check.rows ?? [])[0];
+            const tableExists = firstRow?.["table_exists"] === true;
+            if (!tableExists) {
+                return {
+                    initialized: false,
+                    latestVersion: null,
+                    latestAppliedAt: null,
+                    counts: { total: 0, applied: 0, rolledBack: 0, failed: 0 },
+                    sourceSystems: [],
+                };
+            }
+            const qualifiedTable = targetSchema === "public"
+                ? TRACKING_TABLE
+                : `${targetSchema}.${TRACKING_TABLE}`;
+            // Get aggregate status
+            const statsResult = await adapter.executeQuery(`SELECT
+          COUNT(*)::int AS total,
+          COUNT(*) FILTER (WHERE status = 'applied')::int AS applied,
+          COUNT(*) FILTER (WHERE status = 'rolled_back')::int AS rolled_back,
+          COUNT(*) FILTER (WHERE status = 'failed')::int AS failed
+        FROM ${qualifiedTable}`);
+            const statsRow = (statsResult.rows ?? [])[0] ?? {};
+            // Get latest applied migration
+            const latestResult = await adapter.executeQuery(`SELECT version, applied_at FROM ${qualifiedTable}
+         WHERE status = 'applied'
+         ORDER BY applied_at DESC LIMIT 1`);
+            const latestRow = (latestResult.rows ?? [])[0];
+            // Get distinct source systems
+            const systemsResult = await adapter.executeQuery(`SELECT DISTINCT source_system FROM ${qualifiedTable}
+         WHERE source_system IS NOT NULL
+         ORDER BY source_system`);
+            const sourceSystems = (systemsResult.rows ?? []).map((r) => r["source_system"]);
+            let latestAppliedAt = null;
+            if (latestRow != null) {
+                const appliedAt = latestRow["applied_at"];
+                latestAppliedAt =
+                    appliedAt instanceof Date
+                        ? appliedAt.toISOString()
+                        : (appliedAt ?? "");
+            }
+            return {
+                initialized: true,
+                latestVersion: latestRow != null ? latestRow["version"] : null,
+                latestAppliedAt,
+                counts: {
+                    total: statsRow["total"],
+                    applied: statsRow["applied"],
+                    rolledBack: statsRow["rolled_back"],
+                    failed: statsRow["failed"],
+                },
+                sourceSystems,
+            };
+        },
+    };
+}
+//# sourceMappingURL=introspection.js.map