@lumifai/harness-tool-pack-postgres 0.0.1

package/dist/query-executor.js

@@ -0,0 +1,223 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeReadQuery = executeReadQuery;
+exports.withReadOnlyTransaction = withReadOnlyTransaction;
+exports.mapExecutionError = mapExecutionError;
+const pg_cursor_1 = __importDefault(require("pg-cursor"));
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+async function executeReadQuery(client, compiled, fetchLimit, options = {}, audit) {
+    const started = Date.now();
+    await beginReadOnlyTransaction(client, options);
+    try {
+        if (options.enableExplainCostGate ?? true) {
+            await assertExplainCostWithinLimit(client, compiled, options.explainCostLimit);
+        }
+        // Stream through a cursor so oversized result sets are abandoned as soon
+        // as a limit trips, instead of being fully buffered in memory.
+        const maxCellBytes = Math.max(options.maxCellBytes ?? constants_1.DEFAULT_MAX_CELL_BYTES, 1);
+        const maxResultBytes = options.maxResultBytes ?? constants_1.DEFAULT_MAX_RESULT_BYTES;
+        const cursor = client.query(new pg_cursor_1.default(compiled.text, compiled.values, { rowMode: 'array' }));
+        const rows = [];
+        let fields = [];
+        let truncatedRows = false;
+        let truncatedBytes = false;
+        let truncatedCells = false;
+        let totalBytes = 0;
+        try {
+            reading: while (rows.length <= fetchLimit) {
+                // Fetch up to fetchLimit + 1 rows so a full page still lets us detect
+                // that more rows exist, batching cursor reads instead of one per row.
+                const remaining = fetchLimit + 1 - rows.length;
+                const batchSize = Math.min(constants_1.CURSOR_BATCH_SIZE, remaining);
+                const batch = fields.length === 0
+                    ? await readCursorBatch(cursor, batchSize, (result) => {
+                        fields = result.fields;
+                    })
+                    : await cursor.read(batchSize);
+                if (batch.length === 0) {
+                    break;
+                }
+                for (const raw of batch) {
+                    const normalized = normalizeRow(raw, maxCellBytes);
+                    if (normalized.truncatedCells) {
+                        truncatedCells = true;
+                    }
+                    const rowBytes = estimateRowBytes(normalized.values);
+                    if (totalBytes + rowBytes > maxResultBytes) {
+                        truncatedBytes = true;
+                        break reading;
+                    }
+                    if (rows.length >= fetchLimit) {
+                        truncatedRows = true;
+                        break reading;
+                    }
+                    totalBytes += rowBytes;
+                    rows.push(normalized.values);
+                }
+            }
+        }
+        finally {
+            await cursor.close().catch(() => undefined);
+        }
+        const hasMore = truncatedRows || truncatedBytes;
+        const queryResult = {
+            columns: fields.map((field) => ({
+                name: field.name,
+                type: String(field.dataTypeID),
+            })),
+            rows,
+            returned_count: rows.length,
+            has_more: hasMore,
+            limit: fetchLimit,
+            truncation: {
+                rows: truncatedRows,
+                bytes: truncatedBytes,
+                cells: truncatedCells,
+            },
+        };
+        audit?.({
+            fingerprint: compiled.fingerprint,
+            referencedRelations: compiled.referencedRelations,
+            durationMs: Date.now() - started,
+            returnedCount: queryResult.returned_count,
+            hasMore: queryResult.has_more,
+            truncation: queryResult.truncation,
+        });
+        return queryResult;
+    }
+    finally {
+        await client.query('ROLLBACK').catch(() => undefined);
+    }
+}
+async function beginReadOnlyTransaction(client, options) {
+    const statementTimeout = options.statementTimeoutMs ?? constants_1.DEFAULT_STATEMENT_TIMEOUT_MS;
+    const lockTimeout = options.lockTimeoutMs ?? constants_1.DEFAULT_LOCK_TIMEOUT_MS;
+    const idleTimeout = options.idleInTransactionTimeoutMs ?? constants_1.DEFAULT_IDLE_IN_TRANSACTION_TIMEOUT_MS;
+    await client.query('BEGIN TRANSACTION READ ONLY');
+    await client.query(`SET LOCAL statement_timeout = ${statementTimeout}`);
+    await client.query(`SET LOCAL lock_timeout = ${lockTimeout}`);
+    await client.query(`SET LOCAL idle_in_transaction_session_timeout = ${idleTimeout}`);
+    const tempFileLimitKb = Math.min(Math.max(options.tempFileLimitKb ?? constants_1.DEFAULT_TEMP_FILE_LIMIT_KB, 1), constants_1.MAX_TEMP_FILE_LIMIT_KB);
+    await client.query(`SET LOCAL temp_file_limit = '${tempFileLimitKb}kB'`);
+    if (options.searchPath && options.searchPath.length > 0) {
+        const path = options.searchPath.map((entry) => `"${entry.replace(/"/g, '""')}"`).join(', ');
+        await client.query(`SET LOCAL search_path = ${path}`);
+    }
+}
+async function withReadOnlyTransaction(client, options, run) {
+    await beginReadOnlyTransaction(client, options);
+    try {
+        return await run();
+    }
+    finally {
+        await client.query('ROLLBACK').catch(() => undefined);
+    }
+}
+async function assertExplainCostWithinLimit(client, compiled, limit = 50_000) {
+    // EXPLAIN plans only; it does not execute the query. The cursor below is the
+    // sole data-fetch execution path.
+    const explain = await client.query(`EXPLAIN (FORMAT JSON) ${compiled.text}`, compiled.values);
+    const plan = explain.rows[0]?.['QUERY PLAN']?.[0]?.Plan?.['Total Cost'];
+    if (typeof plan === 'number' && plan > limit) {
+        throw new errors_1.PostgresToolError('COST_EXCEEDED', `Estimated query cost ${plan} exceeds limit ${limit}.`, { hint: 'Narrow filters, reduce joins, or add indexes before retrying.' });
+    }
+}
+function readCursorBatch(cursor, batchSize, onResult) {
+    return new Promise((resolve, reject) => {
+        cursor.read(batchSize, (error, rows, result) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            if (result) {
+                onResult(result);
+            }
+            resolve(rows);
+        });
+    });
+}
+function normalizeRow(row, maxCellBytes) {
+    let truncatedCells = false;
+    const values = row.map((value) => {
+        const normalized = normalizeCellValue(value, maxCellBytes);
+        if (normalized.truncated) {
+            truncatedCells = true;
+        }
+        return normalized.value;
+    });
+    return { values, truncatedCells };
+}
+/** Truncate a string to at most `maxBytes` UTF-8 bytes, appending an ellipsis. */
+function truncateUtf8(value, maxBytes) {
+    if (Buffer.byteLength(value, 'utf8') <= maxBytes) {
+        return value;
+    }
+    let end = Math.min(value.length, maxBytes);
+    let truncated = value.slice(0, end);
+    while (end > 0 && Buffer.byteLength(truncated, 'utf8') > maxBytes) {
+        end -= 1;
+        truncated = value.slice(0, end);
+    }
+    return `${truncated}…`;
+}
+function utf8ByteLength(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+function normalizeCellValue(value, maxCellBytes) {
+    if (value === null || value === undefined) {
+        return { value: null, truncated: false };
+    }
+    if (value instanceof Date) {
+        return { value: value.toISOString(), truncated: false };
+    }
+    if (Buffer.isBuffer(value)) {
+        const encoded = value.toString('base64');
+        if (utf8ByteLength(encoded) > maxCellBytes) {
+            return {
+                value: `<base64:${truncateUtf8(encoded, Math.max(maxCellBytes - 10, 1))}>`,
+                truncated: true,
+            };
+        }
+        return { value: `<base64:${encoded}>`, truncated: false };
+    }
+    if (typeof value === 'object') {
+        const serialized = JSON.stringify(value);
+        if (utf8ByteLength(serialized) > maxCellBytes) {
+            return {
+                value: truncateUtf8(serialized, maxCellBytes),
+                truncated: true,
+            };
+        }
+        return { value, truncated: false };
+    }
+    const asString = String(value);
+    if (utf8ByteLength(asString) > maxCellBytes) {
+        return {
+            value: truncateUtf8(asString, maxCellBytes),
+            truncated: true,
+        };
+    }
+    return { value, truncated: false };
+}
+function estimateRowBytes(row) {
+    return row.reduce((total, cell) => {
+        return total + utf8ByteLength(JSON.stringify(cell));
+    }, 0);
+}
+function mapExecutionError(error) {
+    if (error instanceof errors_1.PostgresToolError) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (/statement timeout|canceling statement/i.test(message)) {
+        return new errors_1.PostgresToolError('TIMEOUT', 'Query exceeded the statement timeout.', {
+            cause: error,
+        });
+    }
+    return new errors_1.PostgresToolError('EXECUTION_ERROR', message, { cause: error });
+}
+//# sourceMappingURL=query-executor.js.map

package/dist/query-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-executor.js","sourceRoot":"","sources":["../src/query-executor.ts"],"names":[],"mappings":"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"}

package/dist/query-language.d.ts

@@ -0,0 +1,208 @@
+import { z } from 'zod';
+import { AGGREGATE_FUNCTIONS, COMPARISON_OPERATORS, JOIN_TYPES, QUERY_PLAN_VERSION, SET_OPERATIONS, WINDOW_FUNCTIONS } from './constants';
+declare const literalValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+export type LiteralValue = z.infer<typeof literalValueSchema>;
+export type ComparisonOp = (typeof COMPARISON_OPERATORS)[number];
+export type AggregateFn = (typeof AGGREGATE_FUNCTIONS)[number];
+export type JoinType = (typeof JOIN_TYPES)[number];
+export type SetOperation = (typeof SET_OPERATIONS)[number];
+export type WindowFn = (typeof WINDOW_FUNCTIONS)[number];
+/** `count(*)` / `count(t.*)` argument; only valid for the `count` aggregate. */
+export type AggregateStarArg = {
+    kind: 'star';
+    table?: string;
+};
+export type Expr = {
+    kind: 'literal';
+    value: LiteralValue;
+} | {
+    kind: 'column';
+    table?: string;
+    column: string;
+} | {
+    kind: 'comparison';
+    op: ComparisonOp;
+    left: Expr;
+    right: Expr;
+} | {
+    kind: 'logical';
+    op: 'and' | 'or';
+    terms: Expr[];
+} | {
+    kind: 'not';
+    term: Expr;
+} | {
+    kind: 'is_null';
+    expr: Expr;
+    negated?: boolean;
+} | {
+    kind: 'between';
+    expr: Expr;
+    lower: Expr;
+    upper: Expr;
+    negated?: boolean;
+} | {
+    kind: 'in_list';
+    expr: Expr;
+    values: LiteralValue[];
+    negated?: boolean;
+} | {
+    kind: 'in_subquery';
+    expr: Expr;
+    query: SelectBody;
+    negated?: boolean;
+} | {
+    kind: 'exists';
+    query: SelectBody;
+    negated?: boolean;
+} | {
+    kind: 'function';
+    name: string;
+    args: Expr[];
+} | {
+    kind: 'aggregate';
+    fn: AggregateFn;
+    arg?: Expr | AggregateStarArg;
+    distinct?: boolean;
+} | {
+    kind: 'case';
+    clauses: {
+        when: Expr;
+        then: Expr;
+    }[];
+    else?: Expr;
+} | {
+    kind: 'cast';
+    expr: Expr;
+    to: string;
+} | {
+    kind: 'scalar_subquery';
+    query: SelectBody;
+} | {
+    kind: 'window';
+    fn: WindowFn;
+    arg?: Expr;
+    partition_by?: Expr[];
+    order_by?: OrderByItem[];
+};
+export type OrderByItem = {
+    expr: Expr;
+    direction?: 'asc' | 'desc';
+    nulls?: 'first' | 'last';
+};
+export type SelectItem = {
+    kind: 'column';
+    expr: Expr;
+    alias?: string;
+} | {
+    kind: 'star';
+    table?: string;
+} | {
+    kind: 'expression';
+    expr: Expr;
+    alias?: string;
+};
+export type RelationRef = {
+    /** Omit schema to reference a CTE defined in the enclosing query. */
+    schema?: string;
+    name: string;
+    alias?: string;
+};
+export type JoinDef = {
+    type: JoinType;
+    relation: RelationRef;
+    on: Expr;
+};
+export type CteDef = {
+    name: string;
+    query: SelectBody;
+};
+export type SelectBody = {
+    with?: CteDef[];
+    distinct?: boolean;
+    select: SelectItem[];
+    from: RelationRef;
+    joins?: JoinDef[];
+    where?: Expr;
+    group_by?: Expr[];
+    having?: Expr;
+    order_by?: OrderByItem[];
+};
+export type SetOpBody = {
+    kind: 'set';
+    op: SetOperation;
+    left: SelectBody;
+    right: SelectBody;
+};
+export type QueryBody = SelectBody | SetOpBody;
+export type QueryPlan = {
+    version: typeof QUERY_PLAN_VERSION;
+    query: QueryBody;
+    limit?: number;
+    offset?: number;
+};
+export declare function isSetOpBody(body: QueryBody): body is SetOpBody;
+export declare function isAggregateStarArg(arg: Expr | AggregateStarArg | undefined): arg is AggregateStarArg | undefined;
+/**
+ * LLMs routinely emit `null` for omitted optional properties. Drop them so
+ * `.optional()` fields accept the input. The only property where `null` is
+ * meaningful is a literal expression's `value`, which is preserved.
+ */
+export declare function stripNullProperties(input: unknown): unknown;
+export declare const queryPlanSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    query: z.ZodType<QueryBody, unknown, z.core.$ZodTypeInternals<QueryBody, unknown>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const previewInputSchema: z.ZodObject<{
+    schema: z.ZodString;
+    relation: z.ZodString;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    where: z.ZodOptional<z.ZodType<Expr, unknown, z.core.$ZodTypeInternals<Expr, unknown>>>;
+    order_by: z.ZodOptional<z.ZodArray<z.ZodType<OrderByItem, unknown, z.core.$ZodTypeInternals<OrderByItem, unknown>>>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const schemaDetailsInputSchema: z.ZodObject<{
+    schemas: z.ZodArray<z.ZodString>;
+    include_indexes: z.ZodOptional<z.ZodBoolean>;
+    cursor: z.ZodOptional<z.ZodString>;
+    page_size: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type PreviewInput = z.infer<typeof previewInputSchema>;
+export type SchemaDetailsInput = z.infer<typeof schemaDetailsInputSchema>;
+export declare function parseQueryPlan(input: unknown): QueryPlan;
+export declare function assertInputShapeComplexity(input: unknown): void;
+export declare function countExprNodes(expr: Expr, depth?: number): {
+    nodes: number;
+    depth: number;
+};
+export declare function countSelectBodyNodes(body: SelectBody): {
+    nodes: number;
+    depth: number;
+};
+export declare function countQueryPlanNodes(plan: QueryPlan): {
+    nodes: number;
+    depth: number;
+};
+export declare function assertQueryPlanComplexity(plan: QueryPlan, limits?: {
+    maxDepth?: number;
+    maxNodes?: number;
+}): void;
+export declare const queryResultSchema: z.ZodObject<{
+    columns: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    rows: z.ZodArray<z.ZodArray<z.ZodUnknown>>;
+    returned_count: z.ZodNumber;
+    has_more: z.ZodBoolean;
+    limit: z.ZodNumber;
+    truncation: z.ZodObject<{
+        rows: z.ZodBoolean;
+        bytes: z.ZodBoolean;
+        cells: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type QueryResult = z.infer<typeof queryResultSchema>;
+export {};