@neverinfamous/postgres-mcp 1.2.0 → 2.0.0

package/dist/adapters/postgresql/tools/jsonb/advanced.js

@@ -6,6 +6,8 @@
 import { z } from "zod";
 import { readOnly } from "../../../../utils/annotations.js";
 import { getToolIcons } from "../../../../utils/icons.js";
+import { formatPostgresError } from "../core/error-helpers.js";
+import { sanitizeWhereClause } from "../../../../utils/where-clause.js";
 import { sanitizeIdentifier, sanitizeTableName, } from "../../../../utils/identifiers.js";
 import { JsonbValidatePathOutputSchema, JsonbMergeOutputSchema, JsonbNormalizeOutputSchema, JsonbDiffOutputSchema, JsonbIndexSuggestOutputSchema, JsonbSecurityScanOutputSchema, JsonbStatsOutputSchema, 
 // Base schemas for MCP visibility (Split Schema pattern)
@@ -180,23 +182,30 @@ export function createJsonbMergeTool(adapter) {
         annotations: readOnly("JSONB Merge"),
         icons: getToolIcons("jsonb", readOnly("JSONB Merge")),
         handler: async (params, _context) => {
-            const parsed = parseMergeParams(params);
-            const useDeep = parsed.deep !== false;
-            const useMergeArrays = parsed.mergeArrays === true;
-            if (useDeep) {
-                // Perform recursive deep merge in TypeScript
-                const merged = deepMergeObjects(parsed.base, parsed.overlay, useMergeArrays);
-                // Return the merged result directly (no PostgreSQL round-trip needed)
-                return { merged, deep: true, mergeArrays: useMergeArrays };
+            try {
+                const parsed = parseMergeParams(params);
+                const useDeep = parsed.deep !== false;
+                const useMergeArrays = parsed.mergeArrays === true;
+                if (useDeep) {
+                    const merged = deepMergeObjects(parsed.base, parsed.overlay, useMergeArrays);
+                    return { merged, deep: true, mergeArrays: useMergeArrays };
+                }
+                else {
+                    const sql = `SELECT $1::jsonb || $2::jsonb as result`;
+                    const result = await adapter.executeQuery(sql, [
+                        toJsonString(parsed.base),
+                        toJsonString(parsed.overlay),
+                    ]);
+                    return { merged: result.rows?.[0]?.["result"], deep: false };
+                }
             }
-            else {
-                // Shallow merge using PostgreSQL || operator
-                const sql = `SELECT $1::jsonb || $2::jsonb as result`;
-                const result = await adapter.executeQuery(sql, [
-                    toJsonString(parsed.base),
-                    toJsonString(parsed.overlay),
-                ]);
-                return { merged: result.rows?.[0]?.["result"], deep: false };
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_jsonb_merge",
+                    }),
+                };
             }
         },
     };
@@ -214,74 +223,86 @@ export function createJsonbNormalizeTool(adapter) {
         annotations: readOnly("JSONB Normalize"),
         icons: getToolIcons("jsonb", readOnly("JSONB Normalize")),
         handler: async (params, _context) => {
-            // Parse with preprocess schema to resolve aliases (tableName→table, col→column, filter→where)
-            const parsed = JsonbNormalizeSchema.parse(params);
-            const table = parsed.table;
-            const column = parsed.column;
-            if (!table || !column) {
-                throw new Error("table and column are required");
-            }
-            const whereClause = parsed.where ? ` WHERE ${parsed.where}` : "";
-            const mode = parsed.mode ?? "keys";
-            // Validate mode parameter
-            const validModes = ["keys", "array", "pairs", "flatten"];
-            if (!validModes.includes(mode)) {
-                throw new Error(`pg_jsonb_normalize: Invalid mode '${mode}'. Valid modes: ${validModes.join(", ")}`);
-            }
-            const tableName = sanitizeTableName(table);
-            const columnName = sanitizeIdentifier(column);
-            // Determine row identifier column
-            let rowIdExpr;
-            let rowIdAlias = "source_id";
-            if (parsed.idColumn) {
-                // User specified - use it directly
-                rowIdExpr = sanitizeIdentifier(parsed.idColumn);
-            }
-            else {
-                // Try to detect 'id' column, fall back to ctid
-                try {
-                    const checkSql = `SELECT column_name FROM information_schema.columns WHERE table_name = $1 AND column_name = 'id' LIMIT 1`;
-                    const checkResult = await adapter.executeQuery(checkSql, [
-                        parsed.table,
-                    ]);
-                    if (checkResult.rows && checkResult.rows.length > 0) {
-                        rowIdExpr = '"id"';
+            try {
+                // Parse with preprocess schema to resolve aliases (tableName→table, col→column, filter→where)
+                const parsed = JsonbNormalizeSchema.parse(params);
+                const table = parsed.table;
+                const column = parsed.column;
+                if (!table || !column) {
+                    return { success: false, error: "table and column are required" };
+                }
+                const whereClause = parsed.where
+                    ? ` WHERE ${sanitizeWhereClause(parsed.where)}`
+                    : "";
+                const mode = parsed.mode ?? "keys";
+                // Validate mode parameter
+                const validModes = ["keys", "array", "pairs", "flatten"];
+                if (!validModes.includes(mode)) {
+                    return {
+                        success: false,
+                        error: `pg_jsonb_normalize: Invalid mode '${mode}'. Valid modes: ${validModes.join(", ")}`,
+                    };
+                }
+                // Validate schema existence for non-public schemas
+                const schemaName = parsed.schema ?? "public";
+                if (schemaName !== "public") {
+                    const schemaResult = await adapter.executeQuery(`SELECT 1 FROM information_schema.schemata WHERE schema_name = $1`, [schemaName]);
+                    if (!schemaResult.rows || schemaResult.rows.length === 0) {
+                        return {
+                            success: false,
+                            error: `Schema '${schemaName}' does not exist. Use pg_list_objects with type 'table' to see available schemas.`,
+                        };
                     }
-                    else {
+                }
+                const tableName = sanitizeTableName(table, schemaName);
+                const columnName = sanitizeIdentifier(column);
+                // Determine row identifier column
+                let rowIdExpr;
+                let rowIdAlias = "source_id";
+                if (parsed.idColumn) {
+                    rowIdExpr = sanitizeIdentifier(parsed.idColumn);
+                }
+                else {
+                    try {
+                        const checkSql = `SELECT column_name FROM information_schema.columns WHERE table_name = $1 AND column_name = 'id' LIMIT 1`;
+                        const checkResult = await adapter.executeQuery(checkSql, [
+                            parsed.table,
+                        ]);
+                        if (checkResult.rows && checkResult.rows.length > 0) {
+                            rowIdExpr = '"id"';
+                        }
+                        else {
+                            rowIdExpr = "ctid::text";
+                            rowIdAlias = "source_ctid";
+                        }
+                    }
+                    catch {
                         rowIdExpr = "ctid::text";
                         rowIdAlias = "source_ctid";
                     }
                 }
-                catch {
-                    rowIdExpr = "ctid::text";
-                    rowIdAlias = "source_ctid";
+                let sql;
+                if (mode === "array") {
+                    sql = `SELECT ${rowIdExpr} as ${rowIdAlias}, jsonb_array_elements(${columnName}) as element FROM ${tableName}${whereClause}`;
                 }
-            }
-            let sql;
-            if (mode === "array") {
-                sql = `SELECT ${rowIdExpr} as ${rowIdAlias}, jsonb_array_elements(${columnName}) as element FROM ${tableName}${whereClause}`;
-            }
-            else if (mode === "flatten") {
-                // Recursive CTE to flatten nested objects to dot-notation keys
-                sql = `
-                    WITH RECURSIVE 
+                else if (mode === "flatten") {
+                    sql = `
+                    WITH RECURSIVE
                     source_rows AS (
                         SELECT ${rowIdExpr} as ${rowIdAlias}, ${columnName} as doc
                         FROM ${tableName}${whereClause}
                     ),
                     flattened AS (
-                        -- Base case: start with top-level keys
-                        SELECT 
+                        SELECT
                             sr.${rowIdAlias},
                             kv.key as path,
                             kv.value,
                             jsonb_typeof(kv.value) as value_type
                         FROM source_rows sr, jsonb_each(sr.doc) kv
-                        
+
                         UNION ALL
-                        
-                        -- Recursive case: expand nested objects
-                        SELECT 
+
+                        SELECT
                             f.${rowIdAlias},
                             f.path || '.' || kv.key,
                             kv.value,
@@ -289,27 +310,27 @@ export function createJsonbNormalizeTool(adapter) {
                         FROM flattened f, jsonb_each(f.value) kv
                         WHERE jsonb_typeof(f.value) = 'object'
                     )
-                    SELECT ${rowIdAlias}, path as key, value, value_type FROM flattened 
+                    SELECT ${rowIdAlias}, path as key, value, value_type FROM flattened
                     WHERE value_type != 'object' OR value = '{}'::jsonb
                     ORDER BY ${rowIdAlias}, path
                 `;
-            }
-            else if (mode === "pairs") {
-                sql = `SELECT ${rowIdExpr} as ${rowIdAlias}, key, value FROM ${tableName}, jsonb_each(${columnName}) ${whereClause}`;
-            }
-            else {
-                // Default 'keys' mode
-                sql = `SELECT ${rowIdExpr} as ${rowIdAlias}, key, value FROM ${tableName}, jsonb_each_text(${columnName}) ${whereClause}`;
-            }
-            try {
+                }
+                else if (mode === "pairs") {
+                    sql = `SELECT ${rowIdExpr} as ${rowIdAlias}, key, value FROM ${tableName}, jsonb_each(${columnName}) ${whereClause}`;
+                }
+                else {
+                    sql = `SELECT ${rowIdExpr} as ${rowIdAlias}, key, value FROM ${tableName}, jsonb_each_text(${columnName}) ${whereClause}`;
+                }
                 const result = await adapter.executeQuery(sql);
                 // Check for empty flatten results on array columns
                 if (mode === "flatten" && (result.rows?.length ?? 0) === 0) {
-                    // Verify if this is because column contains arrays
                     const typeCheckSql = `SELECT jsonb_typeof(${columnName}) as type FROM ${tableName}${whereClause} LIMIT 1`;
                     const typeResult = await adapter.executeQuery(typeCheckSql);
                     if (typeResult.rows?.[0]?.["type"] === "array") {
-                        throw new Error(`pg_jsonb_normalize flatten mode requires object columns. Column appears to contain arrays - use 'array' mode instead.`);
+                        return {
+                            success: false,
+                            error: `pg_jsonb_normalize flatten mode requires object columns. Column appears to contain arrays - use 'array' mode instead.`,
+                        };
                     }
                 }
                 return { rows: result.rows, count: result.rows?.length ?? 0, mode };
@@ -318,14 +339,24 @@ export function createJsonbNormalizeTool(adapter) {
                 // Improve error for array columns with object-only modes
                 if (error instanceof Error &&
                     error.message.includes("cannot call jsonb_each")) {
-                    throw new Error(`pg_jsonb_normalize '${mode}' mode requires object columns. For array columns, use mode: 'array'.`);
+                    return {
+                        success: false,
+                        error: `pg_jsonb_normalize requires object columns for this mode. For array columns, use mode: 'array'.`,
+                    };
                 }
-                // Improve error for object columns with array mode
                 if (error instanceof Error &&
                     error.message.includes("cannot extract elements from an object")) {
-                    throw new Error(`pg_jsonb_normalize 'array' mode requires array columns. For object columns, use mode: 'keys' or 'pairs'.`);
+                    return {
+                        success: false,
+                        error: `pg_jsonb_normalize 'array' mode requires array columns. For object columns, use mode: 'keys' or 'pairs'.`,
+                    };
                 }
-                throw error;
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_jsonb_normalize",
+                    }),
+                };
             }
         },
     };
@@ -353,23 +384,26 @@ export function createJsonbDiffTool(adapter) {
         annotations: readOnly("JSONB Diff"),
         icons: getToolIcons("jsonb", readOnly("JSONB Diff")),
         handler: async (params, _context) => {
-            let parsed;
             try {
-                parsed = JsonbDiffSchema.parse(params);
-            }
-            catch {
-                // Provide friendly error for array/non-object inputs
-                throw new Error("pg_jsonb_diff requires two JSONB objects. Arrays and primitive values are not supported. Use {} format for both doc1 and doc2.");
-            }
-            const sql = `
-                WITH 
+                let parsed;
+                try {
+                    parsed = JsonbDiffSchema.parse(params);
+                }
+                catch {
+                    return {
+                        success: false,
+                        error: "pg_jsonb_diff requires two JSONB objects. Arrays and primitive values are not supported. Use {} format for both doc1 and doc2.",
+                    };
+                }
+                const sql = `
+                WITH
                     j1 AS (SELECT key, value FROM jsonb_each($1::jsonb)),
                     j2 AS (SELECT key, value FROM jsonb_each($2::jsonb))
-                SELECT 
+                SELECT
                     COALESCE(j1.key, j2.key) as key,
                     j1.value as value1,
                     j2.value as value2,
-                    CASE 
+                    CASE
                         WHEN j1.key IS NULL THEN 'added'
                         WHEN j2.key IS NULL THEN 'removed'
                         WHEN j1.value = j2.value THEN 'unchanged'
@@ -378,16 +412,25 @@ export function createJsonbDiffTool(adapter) {
                 FROM j1 FULL OUTER JOIN j2 ON j1.key = j2.key
                 WHERE j1.value IS DISTINCT FROM j2.value
             `;
-            const result = await adapter.executeQuery(sql, [
-                toJsonString(parsed.doc1),
-                toJsonString(parsed.doc2),
-            ]);
-            return {
-                differences: result.rows,
-                hasDifferences: (result.rows?.length ?? 0) > 0,
-                comparison: "shallow",
-                hint: "Compares top-level keys only. Nested object changes show as modified.",
-            };
+                const result = await adapter.executeQuery(sql, [
+                    toJsonString(parsed.doc1),
+                    toJsonString(parsed.doc2),
+                ]);
+                return {
+                    differences: result.rows,
+                    hasDifferences: (result.rows?.length ?? 0) > 0,
+                    comparison: "shallow",
+                    hint: "Compares top-level keys only. Nested object changes show as modified.",
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_jsonb_diff",
+                    }),
+                };
+            }
         },
     };
 }
@@ -404,86 +447,102 @@ export function createJsonbIndexSuggestTool(adapter) {
         annotations: readOnly("JSONB Index Suggest"),
         icons: getToolIcons("jsonb", readOnly("JSONB Index Suggest")),
         handler: async (params, _context) => {
-            // Parse with preprocess schema to resolve aliases (tableName→table, col→column, filter→where)
-            const parsed = JsonbIndexSuggestSchema.parse(params);
-            const table = parsed.table;
-            const column = parsed.column;
-            if (!table || !column) {
-                throw new Error("table and column are required");
-            }
-            const sample = parsed.sampleSize ?? 1000;
-            const whereClause = parsed.where ? ` WHERE ${parsed.where}` : "";
-            const tableName = sanitizeTableName(table);
-            const columnName = sanitizeIdentifier(column);
-            const keySql = `
-                SELECT key, COUNT(*) as frequency, 
+            try {
+                // Parse with preprocess schema to resolve aliases (tableName→table, col→column, filter→where)
+                const parsed = JsonbIndexSuggestSchema.parse(params);
+                const table = parsed.table;
+                const column = parsed.column;
+                if (!table || !column) {
+                    return { success: false, error: "table and column are required" };
+                }
+                const sample = parsed.sampleSize ?? 1000;
+                const whereClause = parsed.where
+                    ? ` WHERE ${sanitizeWhereClause(parsed.where)}`
+                    : "";
+                // Validate schema existence for non-public schemas
+                const schemaName = parsed.schema ?? "public";
+                if (schemaName !== "public") {
+                    const schemaResult = await adapter.executeQuery(`SELECT 1 FROM information_schema.schemata WHERE schema_name = $1`, [schemaName]);
+                    if (!schemaResult.rows || schemaResult.rows.length === 0) {
+                        return {
+                            success: false,
+                            error: `Schema '${schemaName}' does not exist. Use pg_list_objects with type 'table' to see available schemas.`,
+                        };
+                    }
+                }
+                const tableName = sanitizeTableName(table, schemaName);
+                const columnName = sanitizeIdentifier(column);
+                const keySql = `
+                SELECT key, COUNT(*) as frequency,
                        jsonb_typeof(value) as value_type
                 FROM (SELECT * FROM ${tableName}${whereClause} LIMIT ${String(sample)}) t,
-                     jsonb_each(${columnName}) 
+                     jsonb_each(${columnName})
                 GROUP BY key, jsonb_typeof(value)
                 ORDER BY frequency DESC
                 LIMIT 20
             `;
-            let keyResult;
-            try {
-                keyResult = await adapter.executeQuery(keySql);
-            }
-            catch (error) {
-                if (error instanceof Error &&
-                    (error.message.includes("function jsonb_each") ||
-                        error.message.includes("cannot call jsonb_each"))) {
-                    throw new Error(`pg_jsonb_index_suggest requires JSONB objects (not arrays). Column '${column}' may not be JSONB type or contains arrays.`);
-                }
-                throw error;
-            }
-            const indexSql = `
+                const keyResult = await adapter.executeQuery(keySql);
+                const indexSql = `
                 SELECT indexname, indexdef
                 FROM pg_indexes
                 WHERE tablename = $1
                 AND indexdef LIKE '%' || $2 || '%'
             `;
-            const indexResult = await adapter.executeQuery(indexSql, [
-                parsed.table,
-                parsed.column,
-            ]);
-            const recommendations = [];
-            // Cast frequency to number (PostgreSQL returns bigint as string)
-            const keys = (keyResult.rows ?? []).map((row) => ({
-                key: row["key"],
-                frequency: Number(row["frequency"]),
-                value_type: row["value_type"],
-            }));
-            // Only recommend GIN index if there's data to analyze
-            if ((indexResult.rows?.length ?? 0) === 0 && keys.length > 0) {
-                recommendations.push(`CREATE INDEX ON ${tableName} USING GIN (${columnName})`);
-            }
-            for (const keyInfo of keys.slice(0, 5)) {
-                if (keyInfo.frequency > sample * 0.5) {
-                    recommendations.push(`CREATE INDEX ON ${tableName} ((${columnName} ->> '${keyInfo.key.replace(/'/g, "''")}'))`);
+                const indexResult = await adapter.executeQuery(indexSql, [
+                    parsed.table,
+                    parsed.column,
+                ]);
+                const recommendations = [];
+                const keys = (keyResult.rows ?? []).map((row) => ({
+                    key: row["key"],
+                    frequency: Number(row["frequency"]),
+                    value_type: row["value_type"],
+                }));
+                if ((indexResult.rows?.length ?? 0) === 0 && keys.length > 0) {
+                    recommendations.push(`CREATE INDEX ON ${tableName} USING GIN (${columnName})`);
                 }
-            }
-            // Build response with helpful hints
-            const response = {
-                keyDistribution: keys,
-                existingIndexes: indexResult.rows,
-                recommendations,
-            };
-            // Add explanation when no recommendations
-            if (recommendations.length === 0) {
-                if ((indexResult.rows?.length ?? 0) > 0) {
-                    response.hint =
-                        "No new recommendations - existing indexes already cover this column";
-                }
-                else if (keys.length === 0) {
-                    response.hint =
-                        "No recommendations - table is empty or column has no keys to analyze";
+                for (const keyInfo of keys.slice(0, 5)) {
+                    if (keyInfo.frequency > sample * 0.5) {
+                        recommendations.push(`CREATE INDEX ON ${tableName} ((${columnName} ->> '${keyInfo.key.replace(/'/g, "''")}'))`);
+                    }
                 }
-                else {
-                    response.hint =
-                        "No recommendations - no keys appeared in >50% of sampled rows";
+                const response = {
+                    keyDistribution: keys,
+                    existingIndexes: indexResult.rows,
+                    recommendations,
+                };
+                if (recommendations.length === 0) {
+                    if ((indexResult.rows?.length ?? 0) > 0) {
+                        response.hint =
+                            "No new recommendations - existing indexes already cover this column";
+                    }
+                    else if (keys.length === 0) {
+                        response.hint =
+                            "No recommendations - table is empty or column has no keys to analyze";
+                    }
+                    else {
+                        response.hint =
+                            "No recommendations - no keys appeared in >50% of sampled rows";
+                    }
                 }
+                return response;
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    (error.message.includes("function jsonb_each") ||
+                        error.message.includes("cannot call jsonb_each"))) {
+                    return {
+                        success: false,
+                        error: `pg_jsonb_index_suggest requires JSONB objects (not arrays). Column may not be JSONB type or contains arrays.`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_jsonb_index_suggest",
+                    }),
+                };
             }
-            return response;
         },
     };
 }
@@ -500,85 +559,105 @@ export function createJsonbSecurityScanTool(adapter) {
         annotations: readOnly("JSONB Security Scan"),
         icons: getToolIcons("jsonb", readOnly("JSONB Security Scan")),
         handler: async (params, _context) => {
-            // Parse with preprocess schema to resolve aliases (tableName→table, col→column, filter→where)
-            const parsed = JsonbSecurityScanSchema.parse(params);
-            const table = parsed.table;
-            const column = parsed.column;
-            if (!table || !column) {
-                throw new Error("table and column are required");
-            }
-            const sample = parsed.sampleSize ?? 100;
-            const whereClause = parsed.where ? ` WHERE ${parsed.where}` : "";
-            const issues = [];
-            const tableName = sanitizeTableName(table);
-            const columnName = sanitizeIdentifier(column);
-            // Count actual rows scanned (may be less than sample if table is small)
-            const countSql = `SELECT COUNT(*) as count FROM (SELECT * FROM ${tableName}${whereClause} LIMIT ${String(sample)}) t`;
-            const countResult = await adapter.executeQuery(countSql);
-            const actualRowsScanned = Number(countResult.rows?.[0]?.["count"] ?? 0);
-            const sensitiveKeysSql = `
+            try {
+                // Parse with preprocess schema to resolve aliases (tableName→table, col→column, filter→where)
+                const parsed = JsonbSecurityScanSchema.parse(params);
+                const table = parsed.table;
+                const column = parsed.column;
+                if (!table || !column) {
+                    return { success: false, error: "table and column are required" };
+                }
+                const sample = parsed.sampleSize ?? 100;
+                const whereClause = parsed.where
+                    ? ` WHERE ${sanitizeWhereClause(parsed.where)}`
+                    : "";
+                const issues = [];
+                // Validate schema existence for non-public schemas
+                const schemaName = parsed.schema ?? "public";
+                if (schemaName !== "public") {
+                    const schemaResult = await adapter.executeQuery(`SELECT 1 FROM information_schema.schemata WHERE schema_name = $1`, [schemaName]);
+                    if (!schemaResult.rows || schemaResult.rows.length === 0) {
+                        return {
+                            success: false,
+                            error: `Schema '${schemaName}' does not exist. Use pg_list_objects with type 'table' to see available schemas.`,
+                        };
+                    }
+                }
+                const tableName = sanitizeTableName(table, schemaName);
+                const columnName = sanitizeIdentifier(column);
+                // Count actual rows scanned
+                const countSql = `SELECT COUNT(*) as count FROM (SELECT * FROM ${tableName}${whereClause} LIMIT ${String(sample)}) t`;
+                const countResult = await adapter.executeQuery(countSql);
+                const actualRowsScanned = Number(countResult.rows?.[0]?.["count"] ?? 0);
+                const sensitiveKeysSql = `
                 SELECT key, COUNT(*) as count
                 FROM (SELECT * FROM ${tableName}${whereClause} LIMIT ${String(sample)}) t,
                      jsonb_each_text(${columnName})
-                WHERE lower(key) IN ('password', 'secret', 'token', 'api_key', 'apikey', 
+                WHERE lower(key) IN ('password', 'secret', 'token', 'api_key', 'apikey',
                                      'auth', 'credential', 'ssn', 'credit_card', 'cvv')
                 GROUP BY key
             `;
-            let sensitiveResult;
-            try {
-                sensitiveResult = await adapter.executeQuery(sensitiveKeysSql);
-            }
-            catch (error) {
-                if (error instanceof Error &&
-                    (error.message.includes("function jsonb_each") ||
-                        error.message.includes("cannot call jsonb_each"))) {
-                    throw new Error(`pg_jsonb_security_scan requires JSONB objects. Column '${column}' may contain arrays or non-JSONB data.`);
+                const sensitiveResult = await adapter.executeQuery(sensitiveKeysSql);
+                for (const row of (sensitiveResult.rows ?? [])) {
+                    issues.push({
+                        type: "sensitive_key",
+                        key: row.key,
+                        count: Number(row.count),
+                    });
                 }
-                throw error;
-            }
-            for (const row of (sensitiveResult.rows ?? [])) {
-                issues.push({
-                    type: "sensitive_key",
-                    key: row.key,
-                    count: Number(row.count),
-                });
-            }
-            const injectionSql = `
+                const injectionSql = `
                 SELECT key, COUNT(*) as count
                 FROM (SELECT * FROM ${tableName}${whereClause} LIMIT ${String(sample)}) t,
                      jsonb_each_text(${columnName})
                 WHERE value ~* '(\\bSELECT\\s+.+\\bFROM\\b|\\bINSERT\\s+INTO\\b|\\bUPDATE\\s+.+\\bSET\\b|\\bDELETE\\s+FROM\\b|\\bDROP\\s+(TABLE|DATABASE|INDEX)\\b|\\bUNION\\s+(ALL\\s+)?SELECT\\b|--\\s*$|;\\s*(SELECT|INSERT|UPDATE|DELETE))'
                 GROUP BY key
             `;
-            const injectionResult = await adapter.executeQuery(injectionSql);
-            for (const row of (injectionResult.rows ?? [])) {
-                issues.push({
-                    type: "sql_injection_pattern",
-                    key: row.key,
-                    count: Number(row.count),
-                });
-            }
-            // XSS pattern detection
-            const xssSql = `
+                const injectionResult = await adapter.executeQuery(injectionSql);
+                for (const row of (injectionResult.rows ?? [])) {
+                    issues.push({
+                        type: "sql_injection_pattern",
+                        key: row.key,
+                        count: Number(row.count),
+                    });
+                }
+                // XSS pattern detection
+                const xssSql = `
                 SELECT key, COUNT(*) as count
                 FROM (SELECT * FROM ${tableName}${whereClause} LIMIT ${String(sample)}) t,
                      jsonb_each_text(${columnName})
                 WHERE value ~* '(<script|javascript:|on(click|load|error|mouseover)\\s*=|<iframe|<object|<embed|<svg[^>]+on|<img[^>]+onerror)'
                 GROUP BY key
             `;
-            const xssResult = await adapter.executeQuery(xssSql);
-            for (const row of (xssResult.rows ?? [])) {
-                issues.push({
-                    type: "xss_pattern",
-                    key: row.key,
-                    count: Number(row.count),
-                });
+                const xssResult = await adapter.executeQuery(xssSql);
+                for (const row of (xssResult.rows ?? [])) {
+                    issues.push({
+                        type: "xss_pattern",
+                        key: row.key,
+                        count: Number(row.count),
+                    });
+                }
+                return {
+                    scannedRows: actualRowsScanned,
+                    issues,
+                    riskLevel: issues.length === 0 ? "low" : issues.length < 3 ? "medium" : "high",
+                };
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    (error.message.includes("function jsonb_each") ||
+                        error.message.includes("cannot call jsonb_each"))) {
+                    return {
+                        success: false,
+                        error: `pg_jsonb_security_scan requires JSONB objects. Column may contain arrays or non-JSONB data.`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_jsonb_security_scan",
+                    }),
+                };
             }
-            return {
-                scannedRows: actualRowsScanned,
-                issues,
-                riskLevel: issues.length === 0 ? "low" : issues.length < 3 ? "medium" : "high",
-            };
         },
     };
 }
@@ -595,38 +674,51 @@ export function createJsonbStatsTool(adapter) {
         annotations: readOnly("JSONB Stats"),
         icons: getToolIcons("jsonb", readOnly("JSONB Stats")),
         handler: async (params, _context) => {
-            // Parse with preprocess schema to resolve aliases (tableName→table, col→column, filter→where)
-            const parsed = JsonbStatsSchema.parse(params);
-            const table = parsed.table;
-            const column = parsed.column;
-            if (!table || !column) {
-                throw new Error("table and column are required");
-            }
-            const sample = parsed.sampleSize ?? 1000;
-            const whereClause = parsed.where ? ` WHERE ${parsed.where}` : "";
-            const tableName = sanitizeTableName(table);
-            const columnName = sanitizeIdentifier(column);
-            const basicSql = `
-                SELECT 
+            try {
+                // Parse with preprocess schema to resolve aliases (tableName→table, col→column, filter→where)
+                const parsed = JsonbStatsSchema.parse(params);
+                const table = parsed.table;
+                const column = parsed.column;
+                if (!table || !column) {
+                    return { success: false, error: "table and column are required" };
+                }
+                const sample = parsed.sampleSize ?? 1000;
+                const whereClause = parsed.where
+                    ? ` WHERE ${sanitizeWhereClause(parsed.where)}`
+                    : "";
+                // Validate schema existence for non-public schemas
+                const schemaName = parsed.schema ?? "public";
+                if (schemaName !== "public") {
+                    const schemaResult = await adapter.executeQuery(`SELECT 1 FROM information_schema.schemata WHERE schema_name = $1`, [schemaName]);
+                    if (!schemaResult.rows || schemaResult.rows.length === 0) {
+                        return {
+                            success: false,
+                            error: `Schema '${schemaName}' does not exist. Use pg_list_objects with type 'table' to see available schemas.`,
+                        };
+                    }
+                }
+                const tableName = sanitizeTableName(table, schemaName);
+                const columnName = sanitizeIdentifier(column);
+                const basicSql = `
+                SELECT
                     COUNT(*) as total_rows,
                     COUNT(${columnName}) as non_null_count,
                     AVG(length(${columnName}::text))::int as avg_size_bytes,
                     MAX(length(${columnName}::text)) as max_size_bytes
                 FROM (SELECT * FROM ${tableName}${whereClause} LIMIT ${String(sample)}) t
             `;
-            const basicResult = await adapter.executeQuery(basicSql);
-            // Cast bigint values to numbers (PostgreSQL returns bigint as string)
-            const basics = basicResult.rows?.[0];
-            const basicsNormalized = basics
-                ? {
-                    total_rows: Number(basics["total_rows"]),
-                    non_null_count: Number(basics["non_null_count"]),
-                    avg_size_bytes: Number(basics["avg_size_bytes"]),
-                    max_size_bytes: Number(basics["max_size_bytes"]),
-                }
-                : undefined;
-            const keyLimit = parsed.topKeysLimit ?? 20;
-            const keySql = `
+                const basicResult = await adapter.executeQuery(basicSql);
+                const basics = basicResult.rows?.[0];
+                const basicsNormalized = basics
+                    ? {
+                        total_rows: Number(basics["total_rows"]),
+                        non_null_count: Number(basics["non_null_count"]),
+                        avg_size_bytes: Number(basics["avg_size_bytes"]),
+                        max_size_bytes: Number(basics["max_size_bytes"]),
+                    }
+                    : undefined;
+                const keyLimit = parsed.topKeysLimit ?? 20;
+                const keySql = `
                 SELECT key, COUNT(*) as frequency
                 FROM (SELECT * FROM ${tableName}${whereClause} LIMIT ${String(sample)}) t,
                      jsonb_object_keys(${columnName}) key
@@ -634,57 +726,62 @@ export function createJsonbStatsTool(adapter) {
                 ORDER BY frequency DESC
                 LIMIT ${String(keyLimit)}
             `;
-            let topKeys = [];
-            try {
-                const keyResult = await adapter.executeQuery(keySql);
-                // Cast frequency to number
-                topKeys = (keyResult.rows ?? []).map((row) => ({
-                    key: row["key"],
-                    frequency: Number(row["frequency"]),
-                }));
-            }
-            catch (error) {
-                // Gracefully handle array columns (jsonb_object_keys fails on arrays)
-                if (error instanceof Error &&
-                    error.message.includes("cannot call jsonb_object_keys")) {
-                    // Leave topKeys empty for array columns - this is valid
+                let topKeys = [];
+                try {
+                    const keyResult = await adapter.executeQuery(keySql);
+                    topKeys = (keyResult.rows ?? []).map((row) => ({
+                        key: row["key"],
+                        frequency: Number(row["frequency"]),
+                    }));
                 }
-                else {
-                    throw error;
+                catch (error) {
+                    // Gracefully handle array columns (jsonb_object_keys fails on arrays)
+                    if (error instanceof Error &&
+                        error.message.includes("cannot call jsonb_object_keys")) {
+                        // Leave topKeys empty for array columns - this is valid
+                    }
+                    else {
+                        throw error; // Re-throw to be caught by outer catch
+                    }
                 }
-            }
-            const typeSql = `
+                const typeSql = `
                 SELECT jsonb_typeof(${columnName}) as type, COUNT(*) as count
                 FROM (SELECT * FROM ${tableName}${whereClause} LIMIT ${String(sample)}) t
                 GROUP BY jsonb_typeof(${columnName})
             `;
-            const typeResult = await adapter.executeQuery(typeSql);
-            // Cast count to number
-            const typeDistribution = (typeResult.rows ?? []).map((row) => ({
-                type: row["type"],
-                count: Number(row["count"]),
-            }));
-            // Calculate SQL NULL count for disambiguation
-            const sqlNullCount = typeDistribution.find((t) => t.type === null)?.count ?? 0;
-            const hasNullColumns = sqlNullCount > 0;
-            const isArrayColumn = typeDistribution.some((t) => t.type === "array");
-            // Determine appropriate hint
-            let hint;
-            if (hasNullColumns) {
-                hint =
-                    "typeDistribution null type represents SQL NULL columns, not JSON null values";
+                const typeResult = await adapter.executeQuery(typeSql);
+                const typeDistribution = (typeResult.rows ?? []).map((row) => ({
+                    type: row["type"],
+                    count: Number(row["count"]),
+                }));
+                const sqlNullCount = typeDistribution.find((t) => t.type === null)?.count ?? 0;
+                const hasNullColumns = sqlNullCount > 0;
+                const isArrayColumn = typeDistribution.some((t) => t.type === "array");
+                let hint;
+                if (hasNullColumns) {
+                    hint =
+                        "typeDistribution null type represents SQL NULL columns, not JSON null values";
+                }
+                else if (topKeys.length === 0 && isArrayColumn) {
+                    hint =
+                        'topKeys empty for array columns - use pg_jsonb_normalize mode: "array" to analyze elements';
+                }
+                return {
+                    basics: basicsNormalized,
+                    topKeys,
+                    typeDistribution,
+                    sqlNullCount,
+                    hint,
+                };
             }
-            else if (topKeys.length === 0 && isArrayColumn) {
-                hint =
-                    'topKeys empty for array columns - use pg_jsonb_normalize mode: "array" to analyze elements';
+            catch (error) {
+                return {
+                    success: false,
+                    error: formatPostgresError(error, {
+                        tool: "pg_jsonb_stats",
+                    }),
+                };
             }
-            return {
-                basics: basicsNormalized,
-                topKeys,
-                typeDistribution,
-                sqlNullCount,
-                hint,
-            };
         },
     };
 }