postgres-scout-mcp 1.0.0

package/dist/tools/monitoring.js

@@ -0,0 +1,286 @@
+import { z } from 'zod';
+import { executeInternalQuery } from '../utils/database.js';
+const GetCurrentActivitySchema = z.object({
+    includeIdle: z.boolean().optional().default(false),
+    minDurationMs: z.number().optional().default(0)
+});
+const AnalyzeLocksSchema = z.object({
+    includeWaiting: z.boolean().optional().default(true)
+});
+const GetIndexUsageSchema = z.object({
+    schema: z.string().optional().default('public'),
+    minSizeMB: z.number().optional().default(0),
+    includeUnused: z.boolean().optional().default(true)
+});
+export async function getCurrentActivity(connection, logger, args) {
+    const { includeIdle, minDurationMs } = args;
+    logger.info('getCurrentActivity', 'Getting current database activity');
+    if (!Number.isFinite(minDurationMs)) {
+        throw new Error('minDurationMs must be a finite number');
+    }
+    const stateFilter = includeIdle ? '' : "AND state != 'idle'";
+    const durationFilter = minDurationMs > 0
+        ? `AND EXTRACT(EPOCH FROM (NOW() - query_start)) * 1000 >= ${Number(minDurationMs)}`
+        : '';
+    const query = `
+    SELECT
+      pid,
+      usename as user,
+      datname as database,
+      state,
+      query,
+      EXTRACT(EPOCH FROM (NOW() - query_start)) * 1000 as duration_ms,
+      wait_event_type,
+      wait_event,
+      backend_type
+    FROM pg_stat_activity
+    WHERE pid != pg_backend_pid()
+      ${stateFilter}
+      ${durationFilter}
+    ORDER BY query_start DESC
+    LIMIT 100
+  `;
+    const statsQuery = `
+    SELECT
+      COUNT(*) as total_connections,
+      COUNT(*) FILTER (WHERE state = 'active') as active_queries,
+      COUNT(*) FILTER (WHERE state = 'idle') as idle_connections,
+      COUNT(*) FILTER (WHERE state = 'idle in transaction') as idle_in_transaction
+    FROM pg_stat_activity
+    WHERE pid != pg_backend_pid()
+  `;
+    const [result, statsResult] = await Promise.all([
+        executeInternalQuery(connection, logger, { query }),
+        executeInternalQuery(connection, logger, { query: statsQuery })
+    ]);
+    const stats = statsResult.rows[0];
+    const queries = result.rows.map(row => {
+        const durationMs = parseFloat(row.duration_ms || '0');
+        const warnings = [];
+        if (row.state === 'idle in transaction' && durationMs > 30000) {
+            warnings.push('⚠ Long idle transaction - potential lock holder');
+        }
+        if (row.state === 'active' && durationMs > 30000) {
+            warnings.push('⚠ Long running query - monitor for timeout');
+        }
+        return {
+            pid: parseInt(row.pid, 10),
+            user: row.user,
+            database: row.database,
+            state: row.state,
+            query: row.query?.substring(0, 500),
+            durationMs: Math.round(durationMs),
+            waitEventType: row.wait_event_type,
+            waitEvent: row.wait_event,
+            backendType: row.backend_type,
+            ...(warnings.length > 0 && { warnings })
+        };
+    });
+    const recommendations = [];
+    const idleInTransaction = parseInt(stats.idle_in_transaction || '0', 10);
+    if (idleInTransaction > 0) {
+        recommendations.push(`${idleInTransaction} idle transactions - check application connection handling`);
+    }
+    const longRunning = queries.filter(q => q.durationMs > 5000).length;
+    if (longRunning > 0) {
+        recommendations.push(`${longRunning} queries running for >5s - monitor for timeouts`);
+    }
+    return {
+        totalConnections: parseInt(stats.total_connections || '0', 10),
+        activeQueries: parseInt(stats.active_queries || '0', 10),
+        idleConnections: parseInt(stats.idle_connections || '0', 10),
+        idleInTransaction,
+        queries,
+        recommendations
+    };
+}
+export async function analyzeLocks(connection, logger, args) {
+    const { includeWaiting } = args;
+    logger.info('analyzeLocks', 'Analyzing database locks');
+    const query = `
+    SELECT
+      l.locktype,
+      l.database,
+      l.relation::regclass::text as relation,
+      l.mode,
+      l.granted,
+      l.pid,
+      a.query,
+      EXTRACT(EPOCH FROM (NOW() - a.query_start)) * 1000 as duration_ms,
+      (SELECT pid FROM pg_locks WHERE NOT granted AND relation = l.relation AND pid != l.pid LIMIT 1) as blocked_pid
+    FROM pg_locks l
+    LEFT JOIN pg_stat_activity a ON a.pid = l.pid
+    WHERE l.relation IS NOT NULL
+      ${includeWaiting ? '' : 'AND l.granted = true'}
+    ORDER BY l.granted, duration_ms DESC
+    LIMIT 100
+  `;
+    const blockingQuery = `
+    SELECT
+      blocking.pid as blocking_pid,
+      blocked.pid as blocked_pid,
+      blocking_activity.query as blocking_query,
+      blocked_activity.query as blocked_query,
+      EXTRACT(EPOCH FROM (NOW() - blocked_activity.query_start)) * 1000 as wait_time_ms
+    FROM pg_locks blocked
+    JOIN pg_stat_activity blocked_activity ON blocked_activity.pid = blocked.pid
+    JOIN pg_locks blocking ON blocking.relation = blocked.relation
+      AND blocking.granted = true
+      AND blocking.pid != blocked.pid
+    JOIN pg_stat_activity blocking_activity ON blocking_activity.pid = blocking.pid
+    WHERE NOT blocked.granted
+      AND blocked_activity.state = 'active'
+    LIMIT 50
+  `;
+    const [result, blockingResult] = await Promise.all([
+        executeInternalQuery(connection, logger, { query }),
+        executeInternalQuery(connection, logger, { query: blockingQuery })
+    ]);
+    const locks = result.rows.map(row => ({
+        lockType: row.locktype,
+        database: row.database,
+        relation: row.relation,
+        mode: row.mode,
+        granted: row.granted,
+        pid: parseInt(row.pid, 10),
+        query: row.query?.substring(0, 200),
+        durationMs: Math.round(parseFloat(row.duration_ms || '0')),
+        ...(row.blocked_pid && { blockedPid: parseInt(row.blocked_pid, 10) })
+    }));
+    const blockingInfo = blockingResult.rows.map(row => ({
+        blockingPid: parseInt(row.blocking_pid, 10),
+        blockedPid: parseInt(row.blocked_pid, 10),
+        blockingQuery: row.blocking_query?.substring(0, 200),
+        blockedQuery: row.blocked_query?.substring(0, 200),
+        waitTimeMs: Math.round(parseFloat(row.wait_time_ms || '0'))
+    }));
+    const recommendations = [];
+    if (blockingInfo.length > 0) {
+        recommendations.push(`⚠ ${blockingInfo.length} blocking queries detected`);
+        blockingInfo.forEach(b => {
+            recommendations.push(`PID ${b.blockingPid} is blocking PID ${b.blockedPid} (waiting ${Math.round(b.waitTimeMs / 1000)}s)`);
+        });
+        recommendations.push('Consider shorter transactions to reduce lock contention');
+    }
+    else {
+        recommendations.push('✓ No blocking queries detected');
+    }
+    return {
+        activeLocks: locks.length,
+        blockingQueries: blockingInfo.length,
+        locks,
+        blockingInfo,
+        recommendations
+    };
+}
+export async function getIndexUsage(connection, logger, args) {
+    const { schema, minSizeMB, includeUnused } = args;
+    logger.info('getIndexUsage', 'Analyzing index usage', { schema });
+    if (!Number.isFinite(minSizeMB)) {
+        throw new Error('minSizeMB must be a finite number');
+    }
+    const sizeFilter = minSizeMB > 0 ? `AND pg_relation_size(i.indexrelid) >= ${Number(minSizeMB) * 1024 * 1024}` : '';
+    const usageFilter = includeUnused ? '' : 'AND (s.idx_scan IS NULL OR s.idx_scan > 0)';
+    const query = `
+    SELECT
+      n.nspname as schema,
+      t.relname as table,
+      i.relname as index,
+      pg_size_pretty(pg_relation_size(i.oid)) as size,
+      pg_relation_size(i.oid) as size_bytes,
+      COALESCE(s.idx_scan, 0) as scans,
+      COALESCE(s.idx_tup_read, 0) as tuples_read,
+      COALESCE(s.idx_tup_fetch, 0) as tuples_fetched,
+      ix.indisunique as unique,
+      ix.indisprimary as primary
+    FROM pg_class i
+    JOIN pg_index ix ON ix.indexrelid = i.oid
+    JOIN pg_class t ON t.oid = ix.indrelid
+    JOIN pg_namespace n ON n.oid = i.relnamespace
+    LEFT JOIN pg_stat_user_indexes s ON s.indexrelid = i.oid
+    WHERE n.nspname = $1
+      AND i.relkind = 'i'
+      ${sizeFilter}
+      ${usageFilter}
+    ORDER BY pg_relation_size(i.oid) DESC
+    LIMIT 100
+  `;
+    const result = await executeInternalQuery(connection, logger, {
+        query,
+        params: [schema]
+    });
+    const indexes = result.rows.map(row => {
+        const scans = parseInt(row.scans || '0', 10);
+        const sizeBytes = parseInt(row.size_bytes, 10);
+        const sizeMB = (sizeBytes / 1024 / 1024).toFixed(2);
+        let usage = 'unknown';
+        let recommendation = '';
+        if (scans === 0) {
+            usage = 'unused';
+            recommendation = `⚠ Never used - consider dropping to save ${sizeMB} MB`;
+        }
+        else if (scans < 100) {
+            usage = 'rarely used';
+            recommendation = 'Rarely used - evaluate if necessary';
+        }
+        else if (scans < 1000) {
+            usage = 'occasionally used';
+            recommendation = 'Occasionally used';
+        }
+        else {
+            usage = 'frequently used';
+            recommendation = '✓ Frequently used - keep';
+        }
+        return {
+            schema: row.schema,
+            table: row.table,
+            index: row.index,
+            size: row.size,
+            sizeMB: parseFloat(sizeMB),
+            scans,
+            tuplesRead: parseInt(row.tuples_read || '0', 10),
+            tuplesFetched: parseInt(row.tuples_fetched || '0', 10),
+            unique: row.unique,
+            primary: row.primary,
+            usage,
+            recommendation,
+            ...(scans === 0 && !row.primary && { dropCommand: `DROP INDEX CONCURRENTLY ${row.schema}.${row.index};` })
+        };
+    });
+    const unusedIndexes = indexes.filter(idx => idx.usage === 'unused' && !idx.primary);
+    const unusedSizeMB = unusedIndexes.reduce((sum, idx) => sum + idx.sizeMB, 0);
+    const recommendations = [];
+    if (unusedIndexes.length > 0) {
+        recommendations.push(`${unusedIndexes.length} unused indexes consuming ${unusedSizeMB.toFixed(2)} MB`);
+        recommendations.push('Drop unused indexes to reduce write overhead and save space');
+        unusedIndexes.slice(0, 5).forEach(idx => {
+            recommendations.push(`Consider: DROP INDEX CONCURRENTLY ${idx.schema}.${idx.index};`);
+        });
+    }
+    else {
+        recommendations.push('✓ All indexes are being used');
+    }
+    return {
+        schema,
+        totalIndexes: indexes.length,
+        totalSizeMB: indexes.reduce((sum, idx) => sum + idx.sizeMB, 0).toFixed(2),
+        unusedCount: unusedIndexes.length,
+        indexes,
+        recommendations
+    };
+}
+export const monitoringTools = {
+    getCurrentActivity: {
+        schema: GetCurrentActivitySchema,
+        handler: getCurrentActivity
+    },
+    analyzeLocks: {
+        schema: AnalyzeLocksSchema,
+        handler: analyzeLocks
+    },
+    getIndexUsage: {
+        schema: GetIndexUsageSchema,
+        handler: getIndexUsage
+    }
+};
+//# sourceMappingURL=monitoring.js.map

package/dist/tools/mutations.js

@@ -0,0 +1,410 @@
+import { z } from 'zod';
+import { executeInternalQuery } from '../utils/database.js';
+import { sanitizeIdentifier, escapeIdentifier, parseIntSafe } from '../utils/sanitize.js';
+import { buildWhereClause, WhereConditionSchema } from '../utils/query-builder.js';
+function clampMaxRows(clientMaxRows) {
+    const serverMax = parseIntSafe(process.env.MAX_MUTATION_ROWS || '10000', 10000);
+    return Math.min(clientMaxRows, serverMax);
+}
+export const PreviewUpdateSchema = z.object({
+    table: z.string(),
+    schema: z.string().optional().default('public'),
+    where: z.array(WhereConditionSchema),
+    limit: z.number().optional().default(5)
+});
+export const PreviewDeleteSchema = z.object({
+    table: z.string(),
+    schema: z.string().optional().default('public'),
+    where: z.array(WhereConditionSchema),
+    limit: z.number().optional().default(5)
+});
+export const SafeUpdateSchema = z.object({
+    table: z.string(),
+    schema: z.string().optional().default('public'),
+    set: z.record(z.any()).refine(obj => Object.keys(obj).length > 0, { message: 'SET must have at least one column' }),
+    where: z.array(WhereConditionSchema),
+    dryRun: z.boolean().optional().default(false),
+    maxRows: z.number().optional().default(1000),
+    allowEmptyWhere: z.boolean().optional().default(false)
+});
+const SafeInsertSchema = z.object({
+    table: z.string(),
+    schema: z.string().optional().default('public'),
+    columns: z.array(z.string()),
+    rows: z.array(z.string()),
+    dryRun: z.boolean().optional().default(false),
+    maxRows: z.number().optional().default(1000),
+    onConflict: z.enum(['error', 'skip']).optional().default('error'),
+});
+export const SafeDeleteSchema = z.object({
+    table: z.string(),
+    schema: z.string().optional().default('public'),
+    where: z.array(WhereConditionSchema),
+    dryRun: z.boolean().optional().default(false),
+    maxRows: z.number().optional().default(1000),
+    allowEmptyWhere: z.boolean().optional().default(false)
+});
+function validateWhereClause(where, allowEmpty, context = 'mutate') {
+    if (where.length === 0) {
+        if (!allowEmpty) {
+            const hint = context === 'preview'
+                ? 'Provide at least one WHERE condition.'
+                : 'Set allowEmptyWhere=true to proceed.';
+            return {
+                valid: false,
+                warning: `No WHERE conditions provided. This would affect ALL rows. ${hint}`
+            };
+        }
+        return {
+            valid: true,
+            warning: 'WARNING: This will affect ALL rows in the table.'
+        };
+    }
+    return { valid: true };
+}
+function getOperationWarning(count, operation) {
+    if (count > 10000) {
+        return `CRITICAL: This ${operation} will affect ${count.toLocaleString()} rows. Consider using smaller batches.`;
+    }
+    if (count > 1000) {
+        return `WARNING: This ${operation} will affect ${count.toLocaleString()} rows.`;
+    }
+    if (count > 100) {
+        return `Note: This ${operation} will affect ${count.toLocaleString()} rows.`;
+    }
+    return undefined;
+}
+export async function previewUpdate(connection, logger, args) {
+    const { table, schema, where, limit } = args;
+    logger.info('previewUpdate', 'Previewing UPDATE operation', { schema, table });
+    const sanitizedSchema = sanitizeIdentifier(schema);
+    const sanitizedTable = sanitizeIdentifier(table);
+    const validation = validateWhereClause(where, false, 'preview');
+    if (!validation.valid) {
+        return {
+            blocked: true,
+            reason: validation.warning
+        };
+    }
+    const whereResult = buildWhereClause(where);
+    const countQuery = `
+    SELECT COUNT(*) as count
+    FROM ${sanitizedSchema}.${sanitizedTable}
+    ${whereResult.clause ? `WHERE ${whereResult.clause}` : ''}
+  `;
+    const sampleQuery = `
+    SELECT *
+    FROM ${sanitizedSchema}.${sanitizedTable}
+    ${whereResult.clause ? `WHERE ${whereResult.clause}` : ''}
+    LIMIT ${limit}
+  `;
+    const [countResult, sampleResult] = await Promise.all([
+        executeInternalQuery(connection, logger, { query: countQuery, params: whereResult.params }),
+        executeInternalQuery(connection, logger, { query: sampleQuery, params: whereResult.params })
+    ]);
+    const affectedCount = parseInt(countResult.rows[0]?.count || '0', 10);
+    const warning = getOperationWarning(affectedCount, 'UPDATE');
+    return {
+        willAffect: affectedCount,
+        sampleDocuments: sampleResult.rows,
+        samplesShown: sampleResult.rows.length,
+        message: warning || (affectedCount <= 10
+            ? `Will update ${affectedCount} row${affectedCount !== 1 ? 's' : ''}`
+            : undefined),
+        filterWarning: validation.warning
+    };
+}
+export async function previewDelete(connection, logger, args) {
+    const { table, schema, where, limit } = args;
+    logger.info('previewDelete', 'Previewing DELETE operation', { schema, table });
+    const sanitizedSchema = sanitizeIdentifier(schema);
+    const sanitizedTable = sanitizeIdentifier(table);
+    const validation = validateWhereClause(where, false, 'preview');
+    if (!validation.valid) {
+        return {
+            blocked: true,
+            reason: validation.warning
+        };
+    }
+    const whereResult = buildWhereClause(where);
+    const countQuery = `
+    SELECT COUNT(*) as count
+    FROM ${sanitizedSchema}.${sanitizedTable}
+    ${whereResult.clause ? `WHERE ${whereResult.clause}` : ''}
+  `;
+    const sampleQuery = `
+    SELECT *
+    FROM ${sanitizedSchema}.${sanitizedTable}
+    ${whereResult.clause ? `WHERE ${whereResult.clause}` : ''}
+    LIMIT ${limit}
+  `;
+    const [countResult, sampleResult] = await Promise.all([
+        executeInternalQuery(connection, logger, { query: countQuery, params: whereResult.params }),
+        executeInternalQuery(connection, logger, { query: sampleQuery, params: whereResult.params })
+    ]);
+    const deleteCount = parseInt(countResult.rows[0]?.count || '0', 10);
+    const warning = getOperationWarning(deleteCount, 'DELETE');
+    return {
+        willDelete: deleteCount,
+        sampleDocuments: sampleResult.rows,
+        samplesShown: sampleResult.rows.length,
+        message: warning || (deleteCount <= 10
+            ? `Will delete ${deleteCount} row${deleteCount !== 1 ? 's' : ''}`
+            : undefined),
+        filterWarning: validation.warning
+    };
+}
+export async function safeUpdate(connection, logger, args) {
+    const { table, schema, set, where, dryRun, maxRows: clientMaxRows, allowEmptyWhere } = args;
+    const maxRows = clampMaxRows(clientMaxRows);
+    logger.info('safeUpdate', 'Executing safe UPDATE', { schema, table, dryRun });
+    const sanitizedSchema = sanitizeIdentifier(schema);
+    const sanitizedTable = sanitizeIdentifier(table);
+    const validation = validateWhereClause(where, allowEmptyWhere);
+    if (!validation.valid) {
+        return {
+            blocked: true,
+            reason: validation.warning
+        };
+    }
+    // Build WHERE once for count/sample queries (startParam=1, no SET params)
+    const previewWhereResult = buildWhereClause(where);
+    const countQuery = `
+    SELECT COUNT(*) as count
+    FROM ${sanitizedSchema}.${sanitizedTable}
+    ${previewWhereResult.clause ? `WHERE ${previewWhereResult.clause}` : ''}
+  `;
+    const countResult = await executeInternalQuery(connection, logger, { query: countQuery, params: previewWhereResult.params });
+    const affectedCount = parseInt(countResult.rows[0]?.count || '0', 10);
+    if (affectedCount > maxRows) {
+        return {
+            blocked: true,
+            reason: `Operation blocked: Would affect ${affectedCount.toLocaleString()} rows, exceeds maxRows limit of ${maxRows.toLocaleString()}.`,
+            suggestion: 'Use previewUpdate() to see affected rows, or increase maxRows limit.'
+        };
+    }
+    if (dryRun) {
+        const sampleQuery = `
+      SELECT *
+      FROM ${sanitizedSchema}.${sanitizedTable}
+      ${previewWhereResult.clause ? `WHERE ${previewWhereResult.clause}` : ''}
+      LIMIT 5
+    `;
+        const sampleResult = await executeInternalQuery(connection, logger, { query: sampleQuery, params: previewWhereResult.params });
+        return {
+            dryRun: true,
+            operation: 'UPDATE',
+            table: `${schema}.${table}`,
+            wouldAffect: affectedCount,
+            sampleRows: sampleResult.rows,
+            setClause: set,
+            message: getOperationWarning(affectedCount, 'UPDATE'),
+            whereWarning: validation.warning
+        };
+    }
+    // Build SET clause with parameterized values
+    const setClauses = [];
+    const setParams = [];
+    let paramIndex = 1;
+    for (const [column, value] of Object.entries(set)) {
+        setClauses.push(`${escapeIdentifier(sanitizeIdentifier(column))} = $${paramIndex}`);
+        setParams.push(value);
+        paramIndex++;
+    }
+    const setClause = setClauses.join(', ');
+    // Build WHERE with offset after SET params
+    const whereResult = buildWhereClause(where, paramIndex);
+    const allParams = [...setParams, ...whereResult.params];
+    const updateQuery = `
+    UPDATE ${sanitizedSchema}.${sanitizedTable}
+    SET ${setClause}
+    ${whereResult.clause ? `WHERE ${whereResult.clause}` : ''}
+  `;
+    const result = await executeInternalQuery(connection, logger, { query: updateQuery, params: allParams });
+    return {
+        success: true,
+        operation: 'UPDATE',
+        table: `${schema}.${table}`,
+        rowsAffected: result.rowCount,
+        message: getOperationWarning(result.rowCount || 0, 'UPDATE'),
+        whereWarning: validation.warning
+    };
+}
+export async function safeDelete(connection, logger, args) {
+    const { table, schema, where, dryRun, maxRows: clientMaxRows, allowEmptyWhere } = args;
+    const maxRows = clampMaxRows(clientMaxRows);
+    logger.info('safeDelete', 'Executing safe DELETE', { schema, table, dryRun });
+    const sanitizedSchema = sanitizeIdentifier(schema);
+    const sanitizedTable = sanitizeIdentifier(table);
+    const validation = validateWhereClause(where, allowEmptyWhere);
+    if (!validation.valid) {
+        return {
+            blocked: true,
+            reason: validation.warning
+        };
+    }
+    const whereResult = buildWhereClause(where);
+    const countQuery = `
+    SELECT COUNT(*) as count
+    FROM ${sanitizedSchema}.${sanitizedTable}
+    ${whereResult.clause ? `WHERE ${whereResult.clause}` : ''}
+  `;
+    const countResult = await executeInternalQuery(connection, logger, { query: countQuery, params: whereResult.params });
+    const deleteCount = parseInt(countResult.rows[0]?.count || '0', 10);
+    if (deleteCount > maxRows) {
+        return {
+            blocked: true,
+            reason: `Operation blocked: Would delete ${deleteCount.toLocaleString()} rows, exceeds maxRows limit of ${maxRows.toLocaleString()}.`,
+            suggestion: 'Use previewDelete() to see affected rows, or increase maxRows limit.'
+        };
+    }
+    if (dryRun) {
+        const sampleQuery = `
+      SELECT *
+      FROM ${sanitizedSchema}.${sanitizedTable}
+      ${whereResult.clause ? `WHERE ${whereResult.clause}` : ''}
+      LIMIT 5
+    `;
+        const sampleResult = await executeInternalQuery(connection, logger, { query: sampleQuery, params: whereResult.params });
+        return {
+            dryRun: true,
+            operation: 'DELETE',
+            table: `${schema}.${table}`,
+            wouldDelete: deleteCount,
+            sampleRows: sampleResult.rows,
+            message: getOperationWarning(deleteCount, 'DELETE'),
+            whereWarning: validation.warning
+        };
+    }
+    const deleteQuery = `
+    DELETE FROM ${sanitizedSchema}.${sanitizedTable}
+    ${whereResult.clause ? `WHERE ${whereResult.clause}` : ''}
+  `;
+    const result = await executeInternalQuery(connection, logger, { query: deleteQuery, params: whereResult.params });
+    return {
+        success: true,
+        operation: 'DELETE',
+        table: `${schema}.${table}`,
+        rowsDeleted: result.rowCount,
+        message: getOperationWarning(result.rowCount || 0, 'DELETE'),
+        whereWarning: validation.warning
+    };
+}
+const INSERT_BATCH_SIZE = 500;
+export async function safeInsert(connection, logger, args) {
+    const { table, schema, columns, rows, dryRun, maxRows: clientMaxRows, onConflict } = args;
+    const maxRows = clampMaxRows(clientMaxRows);
+    logger.info('safeInsert', 'Executing safe INSERT', { schema, table, dryRun });
+    // Validation guards
+    if (!columns.length) {
+        return { blocked: true, reason: 'No columns specified.' };
+    }
+    if (!rows.length) {
+        return { blocked: true, reason: 'No rows provided.' };
+    }
+    if (rows.length > maxRows) {
+        return {
+            blocked: true,
+            reason: `Row count (${rows.length}) exceeds maxRows limit (${maxRows}).`,
+        };
+    }
+    // Parse and validate each row
+    const parsedRows = [];
+    for (let i = 0; i < rows.length; i++) {
+        let parsed;
+        try {
+            parsed = JSON.parse(rows[i]);
+        }
+        catch {
+            return { blocked: true, reason: `Invalid row JSON at index ${i}: ${rows[i]}` };
+        }
+        if (!Array.isArray(parsed)) {
+            return { blocked: true, reason: `Invalid row JSON at index ${i}: expected array` };
+        }
+        if (parsed.length !== columns.length) {
+            return {
+                blocked: true,
+                reason: `Row ${i} has ${parsed.length} values but ${columns.length} columns expected.`,
+            };
+        }
+        parsedRows.push(parsed);
+    }
+    const sanitizedSchema = sanitizeIdentifier(schema);
+    const sanitizedTable = sanitizeIdentifier(table);
+    const sanitizedColumns = columns.map(c => sanitizeIdentifier(c));
+    if (dryRun) {
+        return {
+            dryRun: true,
+            operation: 'INSERT',
+            table: `${schema}.${table}`,
+            wouldInsert: parsedRows.length,
+            columns,
+            sampleRows: parsedRows.slice(0, 5),
+        };
+    }
+    // Execute in batches
+    let totalInserted = 0;
+    const allReturnedRows = [];
+    for (let batchStart = 0; batchStart < parsedRows.length; batchStart += INSERT_BATCH_SIZE) {
+        const batch = parsedRows.slice(batchStart, batchStart + INSERT_BATCH_SIZE);
+        const valuePlaceholders = [];
+        const params = [];
+        let paramIndex = 1;
+        for (const row of batch) {
+            const rowPlaceholders = [];
+            for (const value of row) {
+                rowPlaceholders.push(`$${paramIndex}`);
+                params.push(value);
+                paramIndex++;
+            }
+            valuePlaceholders.push(`(${rowPlaceholders.join(', ')})`);
+        }
+        let query = `INSERT INTO ${sanitizedSchema}.${sanitizedTable} (${sanitizedColumns.join(', ')}) VALUES ${valuePlaceholders.join(', ')}`;
+        if (onConflict === 'skip') {
+            query += ' ON CONFLICT DO NOTHING';
+        }
+        query += ' RETURNING *';
+        const result = await executeInternalQuery(connection, logger, { query, params });
+        totalInserted += result.rowCount || 0;
+        allReturnedRows.push(...result.rows);
+    }
+    return {
+        success: true,
+        operation: 'INSERT',
+        table: `${schema}.${table}`,
+        rowsInserted: totalInserted,
+        rows: allReturnedRows,
+    };
+}
+/** @internal Exposed for testing only */
+export function _testNormalizeWhereForSafety(where) {
+    const validation = validateWhereClause(where, false);
+    return !validation.valid;
+}
+/** @internal Exposed for testing only */
+export function _testClampMaxRows(maxRows) {
+    return clampMaxRows(maxRows);
+}
+export const mutationTools = {
+    previewUpdate: {
+        schema: PreviewUpdateSchema,
+        handler: previewUpdate
+    },
+    previewDelete: {
+        schema: PreviewDeleteSchema,
+        handler: previewDelete
+    },
+    safeUpdate: {
+        schema: SafeUpdateSchema,
+        handler: safeUpdate
+    },
+    safeDelete: {
+        schema: SafeDeleteSchema,
+        handler: safeDelete
+    },
+    safeInsert: {
+        schema: SafeInsertSchema,
+        handler: safeInsert
+    }
+};
+//# sourceMappingURL=mutations.js.map