@kaelio/ktx 0.14.0 → 0.16.0

package/dist/connectors/duckdb/dialect.js

@@ -0,0 +1,155 @@
+import { columnDisplayPartCount, formatDialectDisplayRef, formatDialectTableName, limitOffsetClause, parseDialectDisplayRef, } from '../../context/connections/dialect-helpers.js';
+/** @internal */
+export class KtxDuckDbDialect {
+    type = 'duckdb';
+    typeMappings = {
+        TIMESTAMP: 'time',
+        'TIMESTAMP WITH TIME ZONE': 'time',
+        TIMESTAMPTZ: 'time',
+        DATE: 'time',
+        TIME: 'time',
+        BIGINT: 'number',
+        INTEGER: 'number',
+        SMALLINT: 'number',
+        TINYINT: 'number',
+        HUGEINT: 'number',
+        UBIGINT: 'number',
+        UINTEGER: 'number',
+        DECIMAL: 'number',
+        NUMERIC: 'number',
+        REAL: 'number',
+        FLOAT: 'number',
+        DOUBLE: 'number',
+        VARCHAR: 'string',
+        CHAR: 'string',
+        TEXT: 'string',
+        BLOB: 'string',
+        UUID: 'string',
+        BOOLEAN: 'boolean',
+        BOOL: 'boolean',
+    };
+    quoteIdentifier(identifier) {
+        return `"${identifier.replace(/"/g, '""')}"`;
+    }
+    // v1 introspects the `main` schema only and sets db=null on every table, so
+    // refs are single-namespace like SQLite — use the matching display shape.
+    formatTableName(table) {
+        return formatDialectTableName(table, this.quoteIdentifier.bind(this), 'sqlite');
+    }
+    formatDisplayRef(table) {
+        return formatDialectDisplayRef(table, 'sqlite');
+    }
+    parseDisplayRef(display) {
+        return parseDialectDisplayRef(display, 'sqlite');
+    }
+    columnDisplayTablePartCount() {
+        return columnDisplayPartCount('sqlite');
+    }
+    mapDataType(nativeType) {
+        return nativeType;
+    }
+    mapToDimensionType(nativeType) {
+        if (!nativeType) {
+            return 'string';
+        }
+        let normalized = nativeType.toUpperCase().trim();
+        if (normalized.includes('(')) {
+            normalized = normalized.split('(')[0].trim();
+        }
+        if (this.typeMappings[normalized]) {
+            return this.typeMappings[normalized];
+        }
+        if (normalized.includes('TIME') || normalized.includes('DATE')) {
+            return 'time';
+        }
+        if (normalized.includes('INT') ||
+            normalized.includes('DEC') ||
+            normalized.includes('NUM') ||
+            normalized.includes('REAL') ||
+            normalized.includes('FLOAT') ||
+            normalized.includes('DOUBLE')) {
+            return 'number';
+        }
+        if (normalized.includes('BOOL')) {
+            return 'boolean';
+        }
+        return 'string';
+    }
+    generateSampleQuery(tableName, limit, columns) {
+        const columnList = columns && columns.length > 0 ? columns.map((column) => this.quoteIdentifier(column)).join(', ') : '*';
+        return `SELECT ${columnList} FROM ${tableName} LIMIT ${limit}`;
+    }
+    generateColumnSampleQuery(tableName, columnName, limit) {
+        const quoted = this.quoteIdentifier(columnName);
+        return `SELECT ${quoted} FROM ${tableName} WHERE ${quoted} IS NOT NULL AND TRIM(CAST(${quoted} AS VARCHAR)) != '' LIMIT ${limit}`;
+    }
+    getRandomSampleFilter(samplePct) {
+        if (samplePct <= 0 || samplePct >= 1) {
+            return '';
+        }
+        return `RANDOM() < ${samplePct}`;
+    }
+    getTableSampleClause(samplePct) {
+        if (samplePct <= 0 || samplePct >= 1) {
+            return '';
+        }
+        return `USING SAMPLE ${Math.round(samplePct * 100)} PERCENT (bernoulli)`;
+    }
+    getLimitOffsetClause(limit, offset) {
+        return limitOffsetClause(limit, offset);
+    }
+    getTopClause(_limit) {
+        return '';
+    }
+    getNullCountExpression(column) {
+        return `SUM(CASE WHEN ${column} IS NULL THEN 1 ELSE 0 END)`;
+    }
+    getDistinctCountExpression(column) {
+        return `COUNT(DISTINCT ${column})`;
+    }
+    textLengthExpression(columnSql) {
+        return `LENGTH(CAST(${columnSql} AS VARCHAR))`;
+    }
+    castToText(columnSql) {
+        return `CAST(${columnSql} AS VARCHAR)`;
+    }
+    getSampleValueAggregation(innerSql) {
+        return `(SELECT STRING_AGG(CAST(value AS VARCHAR), chr(31)) FROM (${innerSql}) AS relationship_profile_values)`;
+    }
+    generateCardinalitySampleQuery(tableName, columnName, sampleSize) {
+        return `
+      WITH sampled AS (
+        SELECT ${columnName} AS val
+        FROM ${tableName}
+        WHERE ${columnName} IS NOT NULL
+        LIMIT ${sampleSize}
+      )
+      SELECT COUNT(DISTINCT val) AS cardinality
+      FROM sampled
+    `;
+    }
+    generateDistinctValuesQuery(tableName, columnName, limit) {
+        return `
+      SELECT DISTINCT CAST(${columnName} AS VARCHAR) AS val
+      FROM ${tableName}
+      WHERE ${columnName} IS NOT NULL
+      ORDER BY val
+      LIMIT ${limit}
+    `;
+    }
+    generateColumnStatisticsQuery(_schemaName, _tableName) {
+        return null;
+    }
+    generateRandomizedCardinalitySampleQuery(tableName, columnName, sampleSize) {
+        return `
+      WITH sampled AS (
+        SELECT ${columnName} AS val
+        FROM ${tableName}
+        WHERE ${columnName} IS NOT NULL
+        USING SAMPLE ${sampleSize} ROWS
+      )
+      SELECT COUNT(DISTINCT val) AS cardinality
+      FROM sampled
+    `;
+    }
+}

package/dist/connectors/duckdb/federated-attach.js

@@ -1,6 +1,7 @@
 import { sqliteDatabasePathFromConfig } from '../sqlite/connector.js';
 import { postgresPoolConfigFromConfig } from '../postgres/connector.js';
 import { mysqlConnectionPoolConfigFromConfig, } from '../mysql/connector.js';
+import { duckDbDatabasePathFromConfig } from '../../connectors/duckdb/connector.js';
 function kvKeyword(value) {
     // libpq/DuckDB key-value values quote with single quotes and backslash-escape.
     return /[\s'\\]/.test(value) ? `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'` : value;
@@ -70,6 +71,12 @@ function mysqlAttachString(member, env) {
  */
 export function federatedAttachTarget(member, env) {
     switch (member.driver.toLowerCase()) {
+        case 'duckdb':
+            return duckDbDatabasePathFromConfig({
+                connectionId: member.connectionId,
+                projectDir: member.projectDir,
+                connection: member.connection,
+            });
         case 'sqlite':
             return sqliteDatabasePathFromConfig({
                 connectionId: member.connectionId,

package/dist/connectors/duckdb/federated-executor.js

@@ -3,20 +3,10 @@ import { federatedAttachTarget } from './federated-attach.js';
 import { normalizeQueryRows } from '../../context/connections/query-executor.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { attachTypeForDriver } from '../../context/connections/federation.js';
+import { toJsonSafeRows } from '../shared/duckdb-json-safe.js';
 function quoteDuckdbIdentifier(id) {
     return `"${id.replaceAll('"', '""')}"`;
 }
-const MIN_SAFE_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
-const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
-// DuckDB returns integer columns as JS bigint (unserializable by JSON). Values
-// in Number's safe range become Number; larger magnitudes become strings so a
-// BIGINT beyond 2^53 keeps its exact value instead of silently rounding.
-function jsonSafeBigint(value) {
-    return value >= MIN_SAFE_BIGINT && value <= MAX_SAFE_BIGINT ? Number(value) : value.toString();
-}
-function toJsonSafeRows(rows) {
-    return rows.map((row) => row.map((cell) => (typeof cell === 'bigint' ? jsonSafeBigint(cell) : cell)));
-}
 /** @internal */
 export function buildAttachStatements(members, env) {
     const attachments = members.map((member) => ({
@@ -24,8 +14,12 @@ export function buildAttachStatements(members, env) {
         url: federatedAttachTarget(member, env),
         alias: member.connectionId,
     }));
-    const loadStatements = [...new Set(attachments.map((a) => a.type))].map((type) => `INSTALL ${type}; LOAD ${type};`);
-    const attachStatements = attachments.map(({ type, url, alias }) => `ATTACH '${url.replaceAll("'", "''")}' AS ${quoteDuckdbIdentifier(alias)} (TYPE ${type}, READ_ONLY);`);
+    const loadTypes = [...new Set(attachments.map((a) => a.type).filter((type) => type !== null))];
+    const loadStatements = loadTypes.map((type) => `INSTALL ${type}; LOAD ${type};`);
+    const attachStatements = attachments.map(({ type, url, alias }) => {
+        const options = type === null ? 'READ_ONLY' : `TYPE ${type}, READ_ONLY`;
+        return `ATTACH '${url.replaceAll("'", "''")}' AS ${quoteDuckdbIdentifier(alias)} (${options});`;
+    });
     return [...loadStatements, ...attachStatements];
 }
 export async function executeFederatedQuery(members, input, env = process.env) {

package/dist/connectors/duckdb/live-database-introspection.d.ts

@@ -0,0 +1,8 @@
+import type { LiveDatabaseIntrospectionPort } from '../../context/ingest/adapters/live-database/types.js';
+import type { KtxProjectConnectionConfig } from '../../context/project/config.js';
+export interface CreateDuckDbLiveDatabaseIntrospectionOptions {
+    projectDir?: string;
+    connections: Record<string, KtxProjectConnectionConfig>;
+    now?: () => Date;
+}
+export declare function createDuckDbLiveDatabaseIntrospection(options: CreateDuckDbLiveDatabaseIntrospectionOptions): LiveDatabaseIntrospectionPort;

package/dist/connectors/duckdb/live-database-introspection.js

@@ -0,0 +1,24 @@
+import { KtxDuckDbScanConnector } from './connector.js';
+export function createDuckDbLiveDatabaseIntrospection(options) {
+    return {
+        async extractSchema(connectionId, introspectionOptions) {
+            const connection = options.connections[connectionId];
+            const connector = new KtxDuckDbScanConnector({
+                connectionId,
+                connection,
+                projectDir: options.projectDir,
+                now: options.now,
+            });
+            try {
+                return await connector.introspect({
+                    connectionId,
+                    driver: 'duckdb',
+                    ...(introspectionOptions?.tableScope ? { tableScope: introspectionOptions.tableScope } : {}),
+                }, { runId: `duckdb-${connectionId}` });
+            }
+            finally {
+                await connector.cleanup();
+            }
+        },
+    };
+}

package/dist/connectors/shared/duckdb-json-safe.d.ts

@@ -0,0 +1,3 @@
+/** @internal */
+export declare function jsonSafeBigint(value: bigint): number | string;
+export declare function toJsonSafeRows(rows: unknown[][]): unknown[][];

package/dist/connectors/shared/duckdb-json-safe.js

@@ -0,0 +1,12 @@
+const MIN_SAFE_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+// DuckDB returns integer columns as JS bigint (unserializable by JSON). Values
+// in Number's safe range become Number; larger magnitudes become strings so a
+// BIGINT beyond 2^53 keeps its exact value instead of silently rounding.
+/** @internal */
+export function jsonSafeBigint(value) {
+    return value >= MIN_SAFE_BIGINT && value <= MAX_SAFE_BIGINT ? Number(value) : value.toString();
+}
+export function toJsonSafeRows(rows) {
+    return rows.map((row) => row.map((cell) => (typeof cell === 'bigint' ? jsonSafeBigint(cell) : cell)));
+}

package/dist/context/connections/connection-type-dialect.d.ts

@@ -0,0 +1,2 @@
+export declare function dialectForConnectionType(connectionType: string): string;
+export declare function warehouseTargetDialect(connectionType: string): string | null;

package/dist/context/connections/connection-type-dialect.js

@@ -0,0 +1,20 @@
+const CONNECTION_TYPE_TO_SQLGLOT = {
+    POSTGRESQL: 'postgres',
+    SQLITE: 'sqlite',
+    DUCKDB: 'duckdb',
+    SQLSERVER: 'tsql',
+    BIGQUERY: 'bigquery',
+    SNOWFLAKE: 'snowflake',
+    MYSQL: 'mysql',
+    CLICKHOUSE: 'clickhouse',
+    ATHENA: 'athena',
+    METABASE: null,
+    LOOKER: null,
+    NOTION: null,
+};
+export function dialectForConnectionType(connectionType) {
+    return CONNECTION_TYPE_TO_SQLGLOT[connectionType.toUpperCase()] ?? 'postgres';
+}
+export function warehouseTargetDialect(connectionType) {
+    return CONNECTION_TYPE_TO_SQLGLOT[connectionType.toUpperCase()] ?? null;
+}

package/dist/context/connections/connection-type.d.ts

@@ -1,25 +1,16 @@
 import { z } from 'zod';
 export declare const connectionTypeSchema: z.ZodEnum<{
-    PLAIN: "PLAIN";
+    POSTGRESQL: "POSTGRESQL";
+    SQLITE: "SQLITE";
+    DUCKDB: "DUCKDB";
+    SQLSERVER: "SQLSERVER";
     BIGQUERY: "BIGQUERY";
     SNOWFLAKE: "SNOWFLAKE";
-    MYSQL: "MYSQL";
-    SQLSERVER: "SQLSERVER";
-    SQLITE: "SQLITE";
-    CLICKHOUSE: "CLICKHOUSE";
-    POSTGRESQL: "POSTGRESQL";
-    CENTRALREACH: "CENTRALREACH";
-    EPIC: "EPIC";
-    CERNER: "CERNER";
     ATHENA: "ATHENA";
-    QUICKBOOKS: "QUICKBOOKS";
-    WORKDAY: "WORKDAY";
-    REST: "REST";
-    S3: "S3";
-    SLACK: "SLACK";
     METABASE: "METABASE";
     LOOKER: "LOOKER";
     NOTION: "NOTION";
-    BETTERSTACK: "BETTERSTACK";
+    MYSQL: "MYSQL";
+    CLICKHOUSE: "CLICKHOUSE";
 }>;
 export type ConnectionType = z.infer<typeof connectionTypeSchema>;

package/dist/context/connections/connection-type.js

@@ -2,23 +2,14 @@ import { z } from 'zod';
 export const connectionTypeSchema = z.enum([
     'POSTGRESQL',
     'SQLITE',
+    'DUCKDB',
     'SQLSERVER',
     'BIGQUERY',
     'SNOWFLAKE',
-    'CENTRALREACH',
-    'EPIC',
-    'CERNER',
     'ATHENA',
-    'QUICKBOOKS',
-    'WORKDAY',
-    'REST',
-    'S3',
-    'SLACK',
     'METABASE',
     'LOOKER',
     'NOTION',
     'MYSQL',
     'CLICKHOUSE',
-    'PLAIN',
-    'BETTERSTACK',
 ]);

package/dist/context/connections/dialects.js

@@ -1,5 +1,7 @@
+import { KtxAthenaDialect } from '../../connectors/athena/dialect.js';
 import { KtxBigQueryDialect } from '../../connectors/bigquery/dialect.js';
 import { KtxClickHouseDialect } from '../../connectors/clickhouse/dialect.js';
+import { KtxDuckDbDialect } from '../../connectors/duckdb/dialect.js';
 import { KtxMongoDbDialect } from '../../connectors/mongodb/dialect.js';
 import { KtxMysqlDialect } from '../../connectors/mysql/dialect.js';
 import { KtxPostgresDialect } from '../../connectors/postgres/dialect.js';
@@ -8,8 +10,10 @@ import { KtxSnowflakeDialect } from '../../connectors/snowflake/dialect.js';
 import { KtxSqlServerDialect } from '../../connectors/sqlserver/dialect.js';
 import { KtxExpectedError } from '../../errors.js';
 const sqlDialectFactories = {
+    athena: () => new KtxAthenaDialect(),
     bigquery: () => new KtxBigQueryDialect(),
     clickhouse: () => new KtxClickHouseDialect(),
+    duckdb: () => new KtxDuckDbDialect(),
     mysql: () => new KtxMysqlDialect(),
     postgres: () => new KtxPostgresDialect(),
     sqlite: () => new KtxSqliteDialect(),

package/dist/context/connections/drivers.js

@@ -3,6 +3,23 @@ function invalidConnectionConfig(driver) {
 }
 /** @internal */
 export const driverRegistrations = {
+    athena: {
+        driver: 'athena',
+        scopeConfigKey: 'databases',
+        hasHistoricSqlReader: false,
+        load: async () => {
+            const m = await import('../../connectors/athena/connector.js');
+            return {
+                isConnectionConfig: (connection) => m.isKtxAthenaConnectionConfig(connection),
+                createScanConnector: ({ connectionId, connection }) => {
+                    if (!m.isKtxAthenaConnectionConfig(connection)) {
+                        throw invalidConnectionConfig('athena');
+                    }
+                    return new m.KtxAthenaScanConnector({ connectionId, connection });
+                },
+            };
+        },
+    },
     bigquery: {
         driver: 'bigquery',
         scopeConfigKey: 'dataset_ids',
@@ -45,6 +62,27 @@ export const driverRegistrations = {
             };
         },
     },
+    duckdb: {
+        driver: 'duckdb',
+        scopeConfigKey: null,
+        hasHistoricSqlReader: false,
+        load: async () => {
+            const m = await import('../../connectors/duckdb/connector.js');
+            return {
+                isConnectionConfig: (connection) => {
+                    const typedConnection = connection;
+                    return m.isKtxDuckDbConnectionConfig(typedConnection);
+                },
+                createScanConnector: ({ connectionId, connection, projectDir }) => {
+                    const typedConnection = connection;
+                    if (!m.isKtxDuckDbConnectionConfig(typedConnection)) {
+                        throw invalidConnectionConfig('duckdb');
+                    }
+                    return new m.KtxDuckDbScanConnector({ connectionId, connection: typedConnection, projectDir });
+                },
+            };
+        },
+    },
     mongodb: {
         driver: 'mongodb',
         scopeConfigKey: 'databases',

package/dist/context/connections/federation.d.ts

@@ -1,7 +1,7 @@
 import type { KtxProjectConnectionConfig } from '../project/config.js';
 /** Stable id for the runtime-derived federated connection. Never written to ktx.yaml. */
 export declare const FEDERATED_CONNECTION_ID = "_ktx_federated";
-export declare function attachTypeForDriver(driver: string): string;
+export declare function attachTypeForDriver(driver: string): string | null;
 export interface FederatedMember {
     connectionId: string;
     driver: string;

package/dist/context/connections/federation.js

@@ -1,17 +1,18 @@
 /** Stable id for the runtime-derived federated connection. Never written to ktx.yaml. */
 export const FEDERATED_CONNECTION_ID = '_ktx_federated';
 /**
- * Drivers DuckDB can ATTACH for federation. The driver name doubles as the
- * DuckDB extension/TYPE name, so this set is the single source of truth for
- * both membership (a driver participates iff it appears here) and attach type.
+ * Drivers DuckDB can ATTACH for federation. Membership is governed by this set;
+ * the attach TYPE is governed by attachTypeForDriver, which returns the driver
+ * name for extension-backed engines and null for a native DuckDB file (attached
+ * with no INSTALL/LOAD and no TYPE).
  */
-const ATTACH_COMPATIBLE_DRIVERS = new Set(['postgres', 'mysql', 'sqlite']);
+const ATTACH_COMPATIBLE_DRIVERS = new Set(['postgres', 'mysql', 'sqlite', 'duckdb']);
 export function attachTypeForDriver(driver) {
     const normalized = driver.toLowerCase();
     if (!ATTACH_COMPATIBLE_DRIVERS.has(normalized)) {
         throw new Error(`Driver "${driver}" cannot be attached by DuckDB federation.`);
     }
-    return normalized;
+    return normalized === 'duckdb' ? null : normalized;
 }
 /**
  * Derives a virtual federated connection when a project declares 2+

package/dist/context/connections/local-warehouse-descriptor.d.ts

@@ -16,6 +16,7 @@ export interface LocalConnectionInfo {
     connectionType: string;
     members?: string[];
     hint?: string;
+    queryPolicy?: 'semantic-layer-only';
 }
 export declare function localConnectionToWarehouseDescriptor(id: string, connection: KtxProjectConnectionConfig | undefined): LocalWarehouseDescriptor | null;
 export declare function localConnectionTypeForConfig(id: string, connection: KtxProjectConnectionConfig | undefined): string;

package/dist/context/connections/local-warehouse-descriptor.js

@@ -1,11 +1,14 @@
+import { connectionQueryPolicy } from './query-policy.js';
 const DRIVER_TO_CONNECTION_TYPE = {
     postgres: 'POSTGRESQL',
     sqlite: 'SQLITE',
+    duckdb: 'DUCKDB',
     sqlserver: 'SQLSERVER',
     mysql: 'MYSQL',
     clickhouse: 'CLICKHOUSE',
     snowflake: 'SNOWFLAKE',
     bigquery: 'BIGQUERY',
+    athena: 'ATHENA',
 };
 export function localConnectionToWarehouseDescriptor(id, connection) {
     if (!connection) {
@@ -59,10 +62,17 @@ export function localConnectionInfoFromConfig(id, connection) {
     if (!connection) {
         return null;
     }
+    const restricted = connectionQueryPolicy(connection) === 'semantic-layer-only';
     return {
         id,
         name: id,
         connectionType: localConnectionTypeForConfig(id, connection),
+        ...(restricted
+            ? {
+                queryPolicy: 'semantic-layer-only',
+                hint: 'Raw SQL is disabled on this connection; query it with sl_query using predefined measures.',
+            }
+            : {}),
     };
 }
 function stringField(value) {

package/dist/context/connections/project-sql-executor.d.ts

@@ -1,4 +1,5 @@
 import { executeFederatedQuery } from '../../connectors/duckdb/federated-executor.js';
+import type { SqlAnalysisPort } from '../sql-analysis/ports.js';
 import type { KtxLocalProject } from '../project/project.js';
 import type { KtxScanConnector } from '../scan/types.js';
 import type { KtxSqlQueryExecutionInput, KtxSqlQueryExecutionResult } from './query-executor.js';
@@ -16,3 +17,26 @@ export interface ExecuteProjectReadOnlySqlDeps {
  * scan connector.
  */
 export declare function executeProjectReadOnlySql(deps: ExecuteProjectReadOnlySqlDeps): Promise<KtxSqlQueryExecutionResult>;
+type RawSqlProgressCallback = (event: {
+    progress: number;
+    message: string;
+}) => void | Promise<void>;
+export interface ExecuteProjectRawSqlDeps {
+    project: KtxLocalProject;
+    connectionId: string;
+    sql: string;
+    maxRows: number;
+    sqlAnalysis: SqlAnalysisPort;
+    createConnector: (connectionId: string) => Promise<KtxScanConnector> | KtxScanConnector;
+    executeFederated?: typeof executeFederatedQuery;
+    runId: string;
+    onProgress?: RawSqlProgressCallback;
+}
+/**
+ * Single guarded path for user-authored (raw) SQL — `ktx sql` and the MCP
+ * sql_execution tool. Enforces the connection's query_policy and the parser
+ * read-only guard before executing; ktx-internal SQL (semantic-layer, ingest)
+ * calls executeProjectReadOnlySql directly and is not subject to query_policy.
+ */
+export declare function executeProjectRawSql(deps: ExecuteProjectRawSqlDeps): Promise<KtxSqlQueryExecutionResult>;
+export {};

package/dist/context/connections/project-sql-executor.js

@@ -1,5 +1,11 @@
 import { executeFederatedQuery } from '../../connectors/duckdb/federated-executor.js';
+import { KtxExpectedError, KtxQueryError, isNativeProgrammingFault } from '../../errors.js';
+import { sqlAnalysisDialectForDriver } from '../sql-analysis/dialect.js';
+import { assertSafeConnectionId } from '../sl/source-files.js';
+import { assertSqlQueryableConnection } from './dialects.js';
 import { deriveFederatedConnection, FEDERATED_CONNECTION_ID } from './federation.js';
+import { assertRawSqlAllowed } from './query-policy.js';
+import { resolveConfiguredConnection } from './resolve-connection.js';
 /**
  * Single resolve-and-execute path for project read-only SQL. The federated
  * connection is derived from declared state here so every executor entry point
@@ -37,3 +43,53 @@ export async function executeProjectReadOnlySql(deps) {
         await connector?.cleanup?.();
     }
 }
+/**
+ * Single guarded path for user-authored (raw) SQL — `ktx sql` and the MCP
+ * sql_execution tool. Enforces the connection's query_policy and the parser
+ * read-only guard before executing; ktx-internal SQL (semantic-layer, ingest)
+ * calls executeProjectReadOnlySql directly and is not subject to query_policy.
+ */
+export async function executeProjectRawSql(deps) {
+    const { project } = deps;
+    await deps.onProgress?.({ progress: 0, message: 'Validating SQL' });
+    const isFederated = deps.connectionId === FEDERATED_CONNECTION_ID;
+    const connectionId = isFederated ? deps.connectionId : assertSafeConnectionId(deps.connectionId);
+    const connection = isFederated ? undefined : resolveConfiguredConnection(project.config, connectionId);
+    if (!isFederated) {
+        assertSqlQueryableConnection(connectionId, connection.driver);
+    }
+    assertRawSqlAllowed(project.config, project.projectDir, connectionId);
+    const dialect = sqlAnalysisDialectForDriver(isFederated ? 'duckdb' : connection.driver);
+    const validation = await deps.sqlAnalysis.validateReadOnly(deps.sql, dialect);
+    if (!validation.ok) {
+        // A read-only guard rejecting the caller's SQL is an expected outcome, not a
+        // ktx fault: classify it so reportException keeps it out of Error Tracking.
+        throw new KtxQueryError(validation.error ?? 'SQL is not read-only.');
+    }
+    await deps.onProgress?.({ progress: 0.3, message: 'Executing' });
+    const result = await executeProjectReadOnlySql({
+        project,
+        input: {
+            connectionId,
+            projectDir: project.projectDir,
+            connection,
+            sql: deps.sql,
+            maxRows: deps.maxRows,
+        },
+        createConnector: deps.createConnector,
+        executeFederated: deps.executeFederated,
+        runId: deps.runId,
+    }).catch((error) => {
+        // A warehouse/driver rejection (e.g. the caller's SQL failed to compile) is a
+        // surfaced operational outcome, not a ktx fault: mark it expected while
+        // preserving the warehouse's own diagnostics. A native JS error (TypeError,
+        // etc.) signals a bug in connector code — let it propagate unchanged so Error
+        // Tracking still sees it.
+        if (isNativeProgrammingFault(error) || error instanceof KtxExpectedError) {
+            throw error;
+        }
+        throw new KtxQueryError(error instanceof Error ? error.message : String(error), { cause: error });
+    });
+    await deps.onProgress?.({ progress: 1, message: `Fetched ${result.rowCount ?? result.rows.length} rows` });
+    return result;
+}

package/dist/context/connections/query-policy.d.ts

@@ -0,0 +1,12 @@
+import type { KtxProjectConfig, KtxProjectConnectionConfig } from '../project/config.js';
+export type KtxConnectionQueryPolicy = 'read-only-sql' | 'semantic-layer-only';
+export declare function connectionQueryPolicy(connection: KtxProjectConnectionConfig | undefined): KtxConnectionQueryPolicy;
+/** Member ids whose policy blocks raw SQL through the federated connection. */
+export declare function restrictedFederatedMemberIds(config: KtxProjectConfig, projectDir: string): string[];
+export declare function assertRawSqlAllowed(config: KtxProjectConfig, projectDir: string, connectionId: string): void;
+/**
+ * False only when the project has SQL-queryable connections and every one of
+ * them is restricted — then no raw-SQL surface can succeed and the
+ * sql_execution tool should not be offered at all.
+ */
+export declare function projectAllowsRawSql(config: KtxProjectConfig): boolean;

package/dist/context/connections/query-policy.js

@@ -0,0 +1,46 @@
+import { KtxQueryError } from '../../errors.js';
+import { deriveFederatedConnection, FEDERATED_CONNECTION_ID } from './federation.js';
+import { isSqlQueryableDriver } from './dialects.js';
+export function connectionQueryPolicy(connection) {
+    return connection !== undefined && connection.query_policy === 'semantic-layer-only'
+        ? 'semantic-layer-only'
+        : 'read-only-sql';
+}
+/** Member ids whose policy blocks raw SQL through the federated connection. */
+export function restrictedFederatedMemberIds(config, projectDir) {
+    const descriptor = deriveFederatedConnection(config.connections, projectDir);
+    if (!descriptor) {
+        return [];
+    }
+    return descriptor.members
+        .filter((member) => connectionQueryPolicy(member.connection) === 'semantic-layer-only')
+        .map((member) => member.connectionId);
+}
+export function assertRawSqlAllowed(config, projectDir, connectionId) {
+    if (connectionId === FEDERATED_CONNECTION_ID) {
+        const restricted = restrictedFederatedMemberIds(config, projectDir);
+        if (restricted.length > 0) {
+            throw new KtxQueryError(`Federated SQL execution is disabled: member connection(s) ${restricted
+                .map((id) => `"${id}"`)
+                .join(', ')} are restricted to semantic-layer queries (query_policy: semantic-layer-only in ktx.yaml).`);
+        }
+        return;
+    }
+    if (connectionQueryPolicy(config.connections[connectionId]) === 'semantic-layer-only') {
+        throw new KtxQueryError(`Connection "${connectionId}" is restricted to semantic-layer queries (query_policy: semantic-layer-only in ktx.yaml); ` +
+            'raw SQL execution is disabled. Query it through the semantic layer with predefined measures instead ' +
+            '(the sl_query tool or `ktx sl query`).');
+    }
+}
+/**
+ * False only when the project has SQL-queryable connections and every one of
+ * them is restricted — then no raw-SQL surface can succeed and the
+ * sql_execution tool should not be offered at all.
+ */
+export function projectAllowsRawSql(config) {
+    const sqlConnections = Object.values(config.connections).filter((connection) => isSqlQueryableDriver(connection.driver));
+    if (sqlConnections.length === 0) {
+        return true;
+    }
+    return sqlConnections.some((connection) => connectionQueryPolicy(connection) === 'read-only-sql');
+}