@kaelio/ktx 0.15.0 → 0.16.0

package/dist/context/project/driver-schemas.js

@@ -6,8 +6,10 @@ const warehouseDrivers = [
     'snowflake',
     'bigquery',
     'sqlite',
+    'duckdb',
     'clickhouse',
     'sqlserver',
+    'athena',
 ];
 function warehouseConnectionSchema(driver) {
     return z
@@ -28,6 +30,10 @@ function warehouseConnectionSchema(driver) {
             .positive()
             .optional()
             .describe('Maximum execution time for a single read-only query, in milliseconds (default 30000). Enforced as a server-side statement timeout for remote engines and by SIGKILL-ing a forked query subprocess for in-process SQLite. A query exceeding it is cancelled and returns a "query exceeded Ns" error so the agent can revise.'),
+        query_policy: z
+            .enum(['read-only-sql', 'semantic-layer-only'])
+            .optional()
+            .describe('Agent-facing query authorship policy (default "read-only-sql"). "read-only-sql" allows parser-validated read-only SQL plus semantic-layer queries. "semantic-layer-only" rejects raw SQL on this connection (`ktx sql`, the sql_execution tool, and federated queries that include it) and restricts semantic-layer queries to measures predefined in the semantic-layer sources. ktx-internal scan and ingest queries are unaffected.'),
     })
         .describe(`${driver} warehouse connection. Additional driver-tunable fields (e.g. context.queryHistory) are accepted and passed through.`);
 }
@@ -37,8 +43,10 @@ const warehouseConnectionSchemas = [
     warehouseConnectionSchema('snowflake'),
     warehouseConnectionSchema('bigquery'),
     warehouseConnectionSchema('sqlite'),
+    warehouseConnectionSchema('duckdb'),
     warehouseConnectionSchema('clickhouse'),
     warehouseConnectionSchema('sqlserver'),
+    warehouseConnectionSchema('athena'),
 ];
 const mongodbConnectionSchema = z
     .looseObject({

package/dist/context/scan/local-scan.js

@@ -43,15 +43,17 @@ function normalizeDriver(driver) {
     const normalized = (driver ?? '').toLowerCase();
     if (normalized === 'postgres' ||
         normalized === 'sqlite' ||
+        normalized === 'duckdb' ||
         normalized === 'mysql' ||
         normalized === 'clickhouse' ||
         normalized === 'sqlserver' ||
         normalized === 'bigquery' ||
         normalized === 'snowflake' ||
+        normalized === 'athena' ||
         normalized === 'mongodb') {
         return normalized;
     }
-    throw new Error(`Standalone ktx scan supports postgres/sqlite/mysql/clickhouse/sqlserver/bigquery/snowflake/mongodb in this phase, received "${driver ?? 'unknown'}"`);
+    throw new Error(`Standalone ktx scan supports postgres/sqlite/duckdb/mysql/clickhouse/sqlserver/bigquery/snowflake/athena/mongodb in this phase, received "${driver ?? 'unknown'}"`);
 }
 function tablePathCount(paths) {
     return paths.filter((path) => path.startsWith('tables/') && path.endsWith('.json')).length;

package/dist/context/scan/types.d.ts

@@ -1,5 +1,5 @@
 import type { KtxTableRefKey } from './table-ref.js';
-export type KtxConnectionDriver = 'sqlite' | 'postgres' | 'sqlserver' | 'bigquery' | 'snowflake' | 'mysql' | 'clickhouse' | 'mongodb';
+export type KtxConnectionDriver = 'sqlite' | 'duckdb' | 'postgres' | 'sqlserver' | 'bigquery' | 'snowflake' | 'mysql' | 'clickhouse' | 'athena' | 'mongodb';
 /** Canonical scan-mode registry. Runtime validation derives its allowlist here. */
 export declare const KTX_SCAN_MODES: readonly ["structural", "relationships", "enriched"];
 export type KtxScanMode = (typeof KTX_SCAN_MODES)[number];

package/dist/context/sl/local-query.js

@@ -1,15 +1,31 @@
 import { isSqlQueryableDriver } from '../connections/dialects.js';
 import { FEDERATED_CONNECTION_ID } from '../connections/federation.js';
+import { connectionQueryPolicy, restrictedFederatedMemberIds } from '../connections/query-policy.js';
 import { resolveRequiredConnectionId } from '../connections/resolve-connection.js';
 import { sqlAnalysisDialectForDriver } from '../sql-analysis/dialect.js';
 import { loadLocalSlSourceRecords } from './local-sl.js';
 import { toResolvedWire } from './semantic-layer.service.js';
 import { assertSafeConnectionId } from './source-files.js';
 const COMPILE_ONLY_REASON = 'Local semantic-layer query compiled SQL but no data-source execution adapter is configured.';
-const FEDERATED_SL_QUERY_UNSUPPORTED = `Semantic-layer queries are per-connection and cannot target the federated connection '${FEDERATED_CONNECTION_ID}'. ` +
-    `Run a cross-database query as read-only SQL instead — ktx sql -c ${FEDERATED_CONNECTION_ID} "SELECT ..." or the sql_execution tool — ` +
-    'using catalog-qualified table names (connectionId.schema.table, or connectionId.table for sqlite; ' +
-    'double-quote ids that are not bare identifiers, e.g. "books-db".public.books).';
+const FEDERATED_SL_QUERY_PREFIX = `Semantic-layer queries are per-connection and cannot target the federated connection '${FEDERATED_CONNECTION_ID}'. `;
+// The raw-SQL fallback is only valid when federated raw SQL is allowed; when a
+// member is restricted (query_policy: semantic-layer-only), assertRawSqlAllowed
+// rejects the same path, so directing the agent there would burn a guaranteed
+// failure. Derive the message from the restricted-member set instead.
+function federatedSlQueryUnsupportedMessage(project) {
+    const restricted = restrictedFederatedMemberIds(project.config, project.projectDir);
+    if (restricted.length > 0) {
+        return (FEDERATED_SL_QUERY_PREFIX +
+            `Cross-database SQL through '${FEDERATED_CONNECTION_ID}' is also disabled because member connection(s) ` +
+            `${restricted.map((id) => `'${id}'`).join(', ')} are restricted to semantic-layer queries ` +
+            '(query_policy: semantic-layer-only). Query each connection on its own through the semantic layer ' +
+            '(the sl_query tool or `ktx sl query` with its connection id).');
+    }
+    return (FEDERATED_SL_QUERY_PREFIX +
+        `Run a cross-database query as read-only SQL instead — ktx sql -c ${FEDERATED_CONNECTION_ID} "SELECT ..." or the sql_execution tool — ` +
+        'using catalog-qualified table names (connectionId.schema.table, or connectionId.table for sqlite; ' +
+        'double-quote ids that are not bare identifiers, e.g. "books-db".public.books).');
+}
 function resolveLocalConnectionId(project, requested) {
     return assertSafeConnectionId(resolveRequiredConnectionId(project.config, requested));
 }
@@ -39,7 +55,7 @@ function headersFromColumns(columns) {
 }
 export async function compileLocalSlQuery(project, options) {
     if (options.connectionId === FEDERATED_CONNECTION_ID) {
-        throw new Error(FEDERATED_SL_QUERY_UNSUPPORTED);
+        throw new Error(federatedSlQueryUnsupportedMessage(project));
     }
     await options.onProgress?.({ progress: 0, message: 'Compiling query' });
     const connectionId = resolveLocalConnectionId(project, options.connectionId);
@@ -50,11 +66,12 @@ export async function compileLocalSlQuery(project, options) {
     }
     const dialect = sqlAnalysisDialectForDriver(driver);
     const sources = await loadComputableSources(project, connectionId);
+    const predefinedMeasuresOnly = connectionQueryPolicy(project.config.connections[connectionId]) === 'semantic-layer-only';
     await options.onProgress?.({ progress: 0.3, message: 'Generating SQL' });
     const response = await options.compute.query({
         sources,
         dialect,
-        query: options.query,
+        query: { ...options.query, predefined_measures_only: predefinedMeasuresOnly },
     });
     if (!options.execute) {
         await options.onProgress?.({ progress: 1, message: 'Fetched 0 rows' });

package/dist/context/sl/semantic-layer.service.d.ts

@@ -147,10 +147,6 @@ export declare class SemanticLayerService {
             descriptions: Record<string, string>;
         }>;
     }>;
-    /**
-     * All callers should use this instead of maintaining their own dialect maps.
-     */
-    static mapDialect(connectionType: string): string;
     /**
      * Execute a semantic layer query: load composed sources, generate SQL via
      * the python SL engine, and execute the generated SQL against the data source.

package/dist/context/sl/semantic-layer.service.js

@@ -1,5 +1,6 @@
 import YAML from 'yaml';
 import { noopLogger } from '../../context/core/config.js';
+import { dialectForConnectionType } from '../connections/connection-type-dialect.js';
 import { normalizeSemanticLayerDescriptions } from './description-normalization.js';
 import { isOverlaySource, resolvedSourceSchema, sourceDefinitionSchema, sourceOverlaySchema } from './schemas.js';
 import { isSlYamlPath, resolveSlSourceFile, slDeclaredSourceName, slSourceFilePath } from './source-files.js';
@@ -572,7 +573,7 @@ export class SemanticLayerService {
         if (!connection) {
             throw new Error(`Data source not found: ${connectionId}`);
         }
-        return SemanticLayerService.mapDialect(connection.connectionType);
+        return dialectForConnectionType(connection.connectionType);
     }
     async listFilesForConnection(connectionId) {
         const dir = `${SL_DIR_PREFIX}/${connectionId}`;
@@ -937,24 +938,6 @@ export class SemanticLayerService {
         }
         return { columns, tables };
     }
-    /**
-     * All callers should use this instead of maintaining their own dialect maps.
-     */
-    static mapDialect(connectionType) {
-        const normalized = connectionType.toUpperCase();
-        const map = {
-            POSTGRES: 'postgres',
-            BIGQUERY: 'bigquery',
-            SNOWFLAKE: 'snowflake',
-            MYSQL: 'mysql',
-            SQLSERVER: 'tsql',
-            SQLITE: 'sqlite',
-            DUCKDB: 'duckdb',
-            CLICKHOUSE: 'clickhouse',
-            DATABRICKS: 'databricks',
-        };
-        return map[normalized] ?? 'postgres';
-    }
     /**
      * Execute a semantic layer query: load composed sources, generate SQL via
      * the python SL engine, and execute the generated SQL against the data source.
@@ -980,7 +963,7 @@ export class SemanticLayerService {
         if (!connection) {
             throw new Error(`Data source not found: ${connectionId}`);
         }
-        const dialect = SemanticLayerService.mapDialect(connection.connectionType);
+        const dialect = dialectForConnectionType(connection.connectionType);
         // 3. Generate SQL via python SL engine
         const { data: slResult, error: slError } = await this.python.query({
             sources: sources.map(toResolvedWire),

package/dist/context/sl/tools/sl-warehouse-validation.d.ts

@@ -1,7 +1,7 @@
 import type { GitService } from '../../../context/core/git.service.js';
 import type { KtxFileStorePort } from '../../../context/core/file-store.js';
 import type { SlConnectionCatalogPort, SlSourcesIndexPort } from '../ports.js';
-import { SemanticLayerService } from '../semantic-layer.service.js';
+import type { SemanticLayerService } from '../semantic-layer.service.js';
 export interface SlValidationDeps {
     semanticLayerService: SemanticLayerService;
     connections: SlConnectionCatalogPort;

package/dist/context/sl/tools/sl-warehouse-validation.js

@@ -1,14 +1,14 @@
 import YAML from 'yaml';
 import { SYSTEM_GIT_AUTHOR } from '../../../context/tools/authors.js';
+import { dialectForConnectionType } from '../../connections/connection-type-dialect.js';
 import { sourceOverlaySchema } from '../schemas.js';
-import { SemanticLayerService } from '../semantic-layer.service.js';
 import { resolveSlSourceFile, slSourceFilePath } from '../source-files.js';
 import { sourceDefinitionSchema } from './base-semantic-layer.tool.js';
 function resolveDialect(warehouse) {
     if (!warehouse) {
         return null;
     }
-    return SemanticLayerService.mapDialect(warehouse);
+    return dialectForConnectionType(warehouse);
 }
 function wrapWithZeroRowQuery(sql, dialect) {
     if (dialect === 'tsql') {

package/dist/context/sl/types.d.ts

@@ -115,6 +115,7 @@ export interface SemanticLayerQueryInput {
     }>;
     limit?: number;
     include_empty?: boolean;
+    predefined_measures_only?: boolean;
 }
 export interface SemanticLayerQueryExecutionResult {
     sql: string;

package/dist/context/sql-analysis/dialect-notes.d.ts

@@ -1,6 +1,6 @@
 import type { SqlAnalysisDialect } from './ports.js';
 /** @internal Dialects with an authored ./dialects/<dialect>.md file. */
-export declare const DIALECTS_WITH_NOTES: readonly ["postgres", "mysql", "snowflake", "bigquery", "sqlite", "clickhouse", "tsql"];
+export declare const DIALECTS_WITH_NOTES: readonly ["postgres", "mysql", "snowflake", "bigquery", "sqlite", "duckdb", "clickhouse", "tsql", "athena"];
 /**
  * SQL syntax notes for a resolved dialect. Falls back to `postgres` — the
  * resolver's own default for unrecognized drivers — so any SQL connection yields

package/dist/context/sql-analysis/dialect-notes.js

@@ -4,8 +4,7 @@ import { fileURLToPath } from 'node:url';
 // dialect), served by the sql_dialect_notes MCP tool. They are package-internal:
 // copy-runtime-assets.mjs ships them to dist, and they are never installed onto an
 // agent target. The set covers every dialect reachable from a configured warehouse
-// driver; duckdb/databricks are intentionally absent because no connector produces
-// them.
+// driver; databricks is intentionally absent because no connector produces it.
 /** @internal Dialects with an authored ./dialects/<dialect>.md file. */
 export const DIALECTS_WITH_NOTES = [
     'postgres',
@@ -13,8 +12,10 @@ export const DIALECTS_WITH_NOTES = [
     'snowflake',
     'bigquery',
     'sqlite',
+    'duckdb',
     'clickhouse',
     'tsql',
+    'athena',
 ];
 const notesCache = new Map();
 function readDialectNotes(dialect) {

package/dist/context/sql-analysis/dialect.js

@@ -14,6 +14,7 @@ const SQLGLOT_DIALECTS = {
     duckdb: 'duckdb',
     clickhouse: 'clickhouse',
     databricks: 'databricks',
+    athena: 'athena',
 };
 export function sqlAnalysisDialectForDriver(driver) {
     return SQLGLOT_DIALECTS[(driver ?? '').toLowerCase()] ?? 'postgres';

package/dist/context/sql-analysis/dialects/athena.md

@@ -0,0 +1,12 @@
+**athena** SQL conventions (Trino engine over the Glue Data Catalog):
+- **FQTN:** `database.table` (e.g. `analytics.orders`); a bare `table` resolves against the query's default database. Cross-catalog is `catalog.database.table` (e.g. `awsdatacatalog.analytics.orders`).
+- **Identifiers:** case-insensitive and folded to lowercase; double-quote (`"Name"`) to keep case, spaces, or a reserved word. String literals use single quotes only.
+- **Date/time:** native `DATE`/`TIMESTAMP`. Bucket with `date_trunc('month', ts)`, pull parts with `EXTRACT(YEAR FROM ts)`, shift with `date_add('day', -30, current_date)`, difference with `date_diff('day', a, b)`, and format with `date_format(ts, '%Y-%m')`. Parse text with `date_parse(str, '%Y-%m-%d')` or `from_iso8601_timestamp(str)`; `current_date` / `now()` are available.
+- **Top-N / windows:** Athena has no `QUALIFY` — wrap the window in a subquery and filter it: `SELECT * FROM (SELECT ..., ROW_NUMBER() OVER (PARTITION BY key ORDER BY x DESC) AS rn FROM t) WHERE rn = 1` returns one row per key. Use `ORDER BY ... LIMIT n` for a global top-N, and paginate with `OFFSET m LIMIT n` (offset first — `LIMIT n OFFSET m` is a syntax error).
+- **Series:** `CROSS JOIN UNNEST(sequence(DATE '2023-01-01', DATE '2023-12-01', INTERVAL '1' MONTH)) AS s(d)` expands a generated array into a date spine (use `sequence(1, 12)` for integers), then `LEFT JOIN` the aggregated facts onto it so empty periods still appear.
+- **Rolling window over time:** a native `RANGE` frame spans real dates and tolerates gaps — `AVG(amount) OVER (ORDER BY day RANGE BETWEEN INTERVAL '29' DAY PRECEDING AND CURRENT ROW)` is a trailing 30-day average without a spine; guard minimum periods with `COUNT(*) OVER (<same frame>)`.
+- **Approximate aggregates:** `approx_distinct(x)` for cardinality and `approx_percentile(x, 0.5)` for quantiles are far cheaper than exact `COUNT(DISTINCT ...)` on large scans.
+- **Arrays & maps:** explode with `CROSS JOIN UNNEST(arr) AS t(x)` (add `WITH ORDINALITY` for an index); build with `array_agg(x)`, join with `array_join(arr, ',')`, index 1-based (`arr[1]`), and read a map with `element_at(m, key)`.
+- **Safe cast:** `TRY_CAST(x AS DOUBLE)` yields `NULL` for a value that does not parse instead of raising, so counting residual `NULL`s catches an encoding the sample missed; `TRY(expr)` swallows other runtime errors.
+- **Integer division:** `/` between integers truncates (`5 / 2` → `2`); cast an operand (`x / CAST(y AS DOUBLE)`) to keep the fraction, and round only in the final projection.
+- **JSON:** `json_extract_scalar(col, '$.a.b')` returns varchar, `json_extract(col, '$.a')` returns json; cast a JSON string with `CAST(json_parse(col) AS ...)`.

package/dist/context/sql-analysis/dialects/duckdb.md

@@ -0,0 +1,10 @@
+**duckdb** SQL conventions:
+- **FQTN:** `schema.table` within one database (e.g. `main.orders`); a bare `table` resolves against `main`. A second, attached database is `db.schema.table` (e.g. `sales.main.orders`).
+- **Identifiers:** case-insensitive; double-quote (`"Name"`) to keep a name with spaces or a reserved word.
+- **Date/time:** native `DATE`/`TIMESTAMP`. Bucket with `date_trunc('month', ts)`, pull parts with `EXTRACT(YEAR FROM ts)`, format with `strftime(ts, '%Y-%m')`, and use `CURRENT_DATE`; cast text with `col::DATE` (or `TRY_CAST(col AS DATE)` to null bad values).
+- **Series:** `FROM generate_series(DATE '2023-01-01', DATE '2023-12-01', INTERVAL 1 MONTH) AS s(d)` builds a date spine (use `range(...)` for integers), then `LEFT JOIN` the aggregated facts onto it so empty periods still appear.
+- **Rolling window over time:** a native calendar-range frame spans real dates and tolerates gaps — `AVG(amount) OVER (ORDER BY day RANGE BETWEEN INTERVAL 29 DAYS PRECEDING AND CURRENT ROW)` is a trailing 30-day average without a spine; guard minimum periods with `COUNT(*) OVER (<same frame>)`.
+- **Integer division:** unlike postgres, `/` is true division (`5 / 2` → `2.5`), so a ratio keeps its fraction; use `//` for floor division (`5 // 2` → `2`) when you want the integer quotient, and round only in the final projection.
+- **Safe cast:** duckdb has `TRY_CAST` — `TRY_CAST(x AS DOUBLE)` yields `NULL` for a value that does not parse instead of raising, so counting residual `NULL`s among non-sentinel rows catches an encoding the sample missed without a regex guard.
+- **Top-N / windows:** filter a window inline with `QUALIFY` — `SELECT ... QUALIFY ROW_NUMBER() OVER (PARTITION BY key ORDER BY x DESC) = 1` returns one row per key without a wrapping CTE; use `ORDER BY ... LIMIT n` for a global top-N.
+- **JSON / semi-structured:** `col->'k'` returns JSON, `col->>'k'` returns text, deep path `json_extract(col, '$.a.b')`; duckdb also has native `STRUCT`, `LIST`, and `MAP` — read a struct field with `col.field` and a list element with `col[1]` (1-indexed).

package/dist/local-adapters.js

@@ -1,3 +1,5 @@
+import { createAthenaLiveDatabaseIntrospection } from './connectors/athena/live-database-introspection.js';
+import { isKtxAthenaConnectionConfig } from './connectors/athena/connector.js';
 import { createBigQueryLiveDatabaseIntrospection } from './connectors/bigquery/live-database-introspection.js';
 import { isKtxBigQueryConnectionConfig, KtxBigQueryScanConnector } from './connectors/bigquery/connector.js';
 import { createClickHouseLiveDatabaseIntrospection } from './connectors/clickhouse/live-database-introspection.js';
@@ -9,6 +11,8 @@ import { isKtxPostgresConnectionConfig } from './connectors/postgres/connector.j
 import { KtxPostgresHistoricSqlQueryClient } from './connectors/postgres/historic-sql-query-client.js';
 import { createSqliteLiveDatabaseIntrospection } from './connectors/sqlite/live-database-introspection.js';
 import { isKtxSqliteConnectionConfig } from './connectors/sqlite/connector.js';
+import { createDuckDbLiveDatabaseIntrospection } from './connectors/duckdb/live-database-introspection.js';
+import { isKtxDuckDbConnectionConfig } from './connectors/duckdb/connector.js';
 import { createSqlServerLiveDatabaseIntrospection } from './connectors/sqlserver/live-database-introspection.js';
 import { isKtxSqlServerConnectionConfig } from './connectors/sqlserver/connector.js';
 import { BigQueryHistoricSqlQueryHistoryReader } from './context/ingest/adapters/historic-sql/bigquery-query-history-reader.js';
@@ -74,6 +78,10 @@ function createKtxCliLiveDatabaseIntrospection(project, options = {}) {
         projectDir: project.projectDir,
         connections: project.config.connections,
     });
+    const duckdb = createDuckDbLiveDatabaseIntrospection({
+        projectDir: project.projectDir,
+        connections: project.config.connections,
+    });
     const mysql = createMysqlLiveDatabaseIntrospection({
         connections: project.config.connections,
     });
@@ -89,6 +97,9 @@ function createKtxCliLiveDatabaseIntrospection(project, options = {}) {
     const bigquery = createBigQueryLiveDatabaseIntrospection({
         connections: project.config.connections,
     });
+    const athena = createAthenaLiveDatabaseIntrospection({
+        connections: project.config.connections,
+    });
     return {
         async extractSchema(connectionId, options) {
             const connection = project.config.connections[connectionId];
@@ -109,6 +120,9 @@ function createKtxCliLiveDatabaseIntrospection(project, options = {}) {
             if (isKtxSqliteConnectionConfig(connection)) {
                 return sqlite.extractSchema(connectionId, options);
             }
+            if (isKtxDuckDbConnectionConfig(connection)) {
+                return duckdb.extractSchema(connectionId, options);
+            }
             if (isKtxMysqlConnectionConfig(connection)) {
                 return mysql.extractSchema(connectionId, options);
             }
@@ -121,6 +135,9 @@ function createKtxCliLiveDatabaseIntrospection(project, options = {}) {
             if (isKtxBigQueryConnectionConfig(connection)) {
                 return bigquery.extractSchema(connectionId, options);
             }
+            if (isKtxAthenaConnectionConfig(connection)) {
+                return athena.extractSchema(connectionId, options);
+            }
             if (hasSnowflakeDriver(connection)) {
                 const { createSnowflakeLiveDatabaseIntrospection } = await import('./connectors/snowflake/live-database-introspection.js');
                 const { isKtxSnowflakeConnectionConfig } = await import('./connectors/snowflake/connector.js');

package/dist/setup-databases.d.ts

@@ -9,7 +9,7 @@ import { type DatabaseScopePickResult, type PickDatabaseScopeArgs } from './data
 import type { KtxManagedPythonInstallPolicy } from './managed-python-command.js';
 import type { ManagedPythonCoreDaemonOptions } from './managed-python-http.js';
 import { type KtxSetupPromptOption } from './setup-prompts.js';
-export type KtxSetupDatabaseDriver = 'sqlite' | 'postgres' | 'mysql' | 'clickhouse' | 'sqlserver' | 'bigquery' | 'snowflake' | 'mongodb';
+export type KtxSetupDatabaseDriver = 'sqlite' | 'duckdb' | 'postgres' | 'mysql' | 'clickhouse' | 'sqlserver' | 'bigquery' | 'snowflake' | 'athena' | 'mongodb';
 export interface KtxSetupDatabasesArgs {
     projectDir: string;
     inputMode: 'auto' | 'disabled';

package/dist/setup-databases.js

@@ -37,8 +37,10 @@ const DRIVER_OPTIONS = [
     { value: 'mysql', label: 'MySQL' },
     { value: 'clickhouse', label: 'ClickHouse' },
     { value: 'sqlserver', label: 'SQL Server' },
+    { value: 'athena', label: 'Amazon Athena' },
     { value: 'mongodb', label: 'MongoDB' },
     { value: 'sqlite', label: 'SQLite' },
+    { value: 'duckdb', label: 'DuckDB' },
 ];
 const DRIVER_LABELS = Object.fromEntries(DRIVER_OPTIONS.map((option) => [option.value, option.label]));
 const HISTORIC_SQL_DIALECT_BY_DRIVER = {
@@ -48,12 +50,14 @@ const HISTORIC_SQL_DIALECT_BY_DRIVER = {
 };
 const DEFAULT_CONNECTION_IDS = {
     sqlite: 'sqlite-local',
+    duckdb: 'duckdb-local',
     postgres: 'postgres-warehouse',
     mysql: 'mysql-warehouse',
     clickhouse: 'clickhouse-warehouse',
     sqlserver: 'sqlserver-warehouse',
     bigquery: 'bigquery-warehouse',
     snowflake: 'snowflake-warehouse',
+    athena: 'athena-warehouse',
     mongodb: 'mongodb-source',
 };
 const SUGGESTED_SCOPE_PATTERN = /^(mart|prod|analytics|core|dim|fact|gold)(_|$)/i;
@@ -118,6 +122,13 @@ const SCOPE_DISCOVERY_SPECS = {
         configSingleField: 'schema_name',
         suggest: defaultSuggest,
     },
+    athena: {
+        noun: 'database',
+        nounPlural: 'databases',
+        promptLabel: 'Glue databases',
+        configArrayField: 'databases',
+        suggest: defaultSuggest,
+    },
 };
 const DRIVER_CONNECTION_DEFAULTS = {
     postgres: { port: '5432' },
@@ -541,6 +552,15 @@ async function buildConnectionConfig(input) {
             return 'back';
         return path ? { driver: 'sqlite', path } : null;
     }
+    if (driver === 'duckdb') {
+        if (args.inputMode === 'disabled' && !args.databaseUrl)
+            return null;
+        const path = args.databaseUrl ??
+            (await promptText(prompts, 'DuckDB database file\nEnter a relative or absolute path, for example ./warehouse.duckdb.', stringConfigField(input.existingConnection, 'path')));
+        if (path === undefined)
+            return 'back';
+        return path ? { driver: 'duckdb', path } : null;
+    }
     if (driver === 'postgres' || driver === 'mysql' || driver === 'clickhouse' || driver === 'sqlserver') {
         return await buildUrlConnectionConfig({
             driver,
@@ -664,6 +684,34 @@ async function buildConnectionConfig(input) {
             ...(role ? { role } : {}),
         };
     }
+    if (driver === 'athena') {
+        if (args.inputMode === 'disabled' && !args.databaseUrl)
+            return null;
+        const region = await promptText(prompts, 'AWS region\nFor example us-east-1.', stringConfigField(input.existingConnection, 'region'));
+        if (region === undefined)
+            return 'back';
+        if (!region)
+            return null;
+        const s3StagingDir = await promptText(prompts, 'S3 staging directory\nAthena writes query results here. For example s3://my-bucket/athena-results/.', stringConfigField(input.existingConnection, 's3_staging_dir'));
+        if (s3StagingDir === undefined)
+            return 'back';
+        if (!s3StagingDir)
+            return null;
+        const workgroup = await promptText(prompts, 'Athena workgroup (optional)\nPress Enter to use the default workgroup "primary".', stringConfigField(input.existingConnection, 'workgroup'));
+        if (workgroup === undefined)
+            return 'back';
+        const catalog = await promptText(prompts, 'Glue Data Catalog name (optional)\nPress Enter to use the default "AwsDataCatalog".', stringConfigField(input.existingConnection, 'catalog'));
+        if (catalog === undefined)
+            return 'back';
+        return {
+            driver: 'athena',
+            region,
+            s3_staging_dir: s3StagingDir,
+            ...(workgroup ? { workgroup } : {}),
+            ...(catalog ? { catalog } : {}),
+            ...scriptedScopeConfigForDriver('athena', args.databaseSchemas),
+        };
+    }
     throw new Error(`Unsupported database driver: ${driver}`);
 }
 async function maybeApplyHistoricSqlConfig(input) {
@@ -1031,9 +1079,11 @@ async function maybeConfigureDatabaseScope(input) {
     const project = await loadKtxProject({ projectDir: input.projectDir });
     const connection = project.config.connections[input.connectionId];
     const driver = normalizeDriver(connection?.driver);
-    if (!driver || driver === 'sqlite')
+    const spec = driver ? SCOPE_DISCOVERY_SPECS[driver] : undefined;
+    // Drivers with no scope spec are single-namespace (sqlite, duckdb): there is no
+    // schema to choose, so skip the scope picker and ingest every table.
+    if (!driver || !spec)
         return okValidateResult();
-    const spec = SCOPE_DISCOVERY_SPECS[driver];
     const existingTables = connection?.enabled_tables;
     const hasExistingTables = Array.isArray(existingTables) && existingTables.length > 0;
     const existingScope = spec ? configuredScopeValues(connection, spec) : [];

package/dist/sql.js

@@ -1,5 +1,5 @@
 import { FEDERATED_CONNECTION_ID } from './context/connections/federation.js';
-import { executeProjectReadOnlySql } from './context/connections/project-sql-executor.js';
+import { executeProjectRawSql } from './context/connections/project-sql-executor.js';
 import { assertSqlQueryableConnection } from './context/connections/dialects.js';
 import { resolveConfiguredConnection } from './context/connections/resolve-connection.js';
 import { loadKtxProject } from './context/project/project.js';
@@ -91,6 +91,8 @@ export async function runKtxSql(args, io = process, deps = {}) {
         const connection = isFederated ? undefined : resolveConfiguredConnection(project.config, args.connectionId);
         driver = isFederated ? 'duckdb' : String(connection?.driver ?? 'unknown').toLowerCase();
         demoConnection = isFederated ? false : isDemoConnection(args.connectionId, connection);
+        // Fail fast before creating the SQL-analysis daemon port; executeProjectRawSql
+        // re-asserts this for every caller.
         if (!isFederated) {
             assertSqlQueryableConnection(args.connectionId, connection?.driver);
         }
@@ -103,25 +105,18 @@ export async function runKtxSql(args, io = process, deps = {}) {
             }));
         const analysisPort = createSqlAnalysis();
         const dialect = isFederated ? 'duckdb' : sqlAnalysisDialectForDriver(connection?.driver);
-        const validation = await analysisPort.validateReadOnly(args.sql, dialect);
-        if (!validation.ok) {
-            throw new Error(validation.error ?? 'SQL is not read-only.');
-        }
-        const referencedTableCount = await safeReferencedTableCount(analysisPort, args.sql, dialect);
         const createScanConnector = deps.createScanConnector ?? createKtxCliScanConnector;
-        const result = await executeProjectReadOnlySql({
+        const result = await executeProjectRawSql({
             project,
-            input: {
-                connectionId: args.connectionId,
-                projectDir: args.projectDir,
-                connection,
-                sql: args.sql,
-                maxRows: args.maxRows,
-            },
+            connectionId: args.connectionId,
+            sql: args.sql,
+            maxRows: args.maxRows,
+            sqlAnalysis: analysisPort,
             createConnector: (connectionId) => createScanConnector(project, connectionId),
             executeFederated: deps.executeFederated,
             runId: 'cli-sql',
         });
+        const referencedTableCount = await safeReferencedTableCount(analysisPort, args.sql, dialect);
         const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
         printSqlResult(resultOutput(args.connectionId, result), mode, io);
         await emitTelemetryEvent({

package/dist/status-project.js

@@ -236,6 +236,7 @@ function buildConnectionStatus(name, conn, env) {
             const hint = envHint(conn.credentials_json);
             return warn(hint ? `credentials missing (env: ${hint})` : 'credentials not set', hint ? `Set ${hint}` : 'Rerun `ktx setup`');
         }
+        case 'duckdb':
         case 'sqlite': {
             const path = conn.path;
             if (typeof path === 'string' && path.length > 0)
@@ -361,7 +362,7 @@ async function buildQueryHistoryStatus(project, options) {
     return statuses;
 }
 const ADAPTER_DRIVER_REQUIREMENT = {
-    'live-database': ['postgres', 'mysql', 'snowflake', 'bigquery', 'clickhouse', 'sqlite', 'sqlserver'],
+    'live-database': ['postgres', 'mysql', 'snowflake', 'bigquery', 'clickhouse', 'sqlite', 'duckdb', 'sqlserver'],
     dbt: ['dbt', 'dbt-core', 'dbt-cloud'],
     notion: ['notion'],
     metabase: ['metabase'],

package/dist/telemetry/events.d.ts

@@ -66,8 +66,8 @@ export declare const telemetryEventSchemas: {
             project: "project";
             models: "models";
             sources: "sources";
-            context: "context";
             runtime: "runtime";
+            context: "context";
             secrets: "secrets";
             agents: "agents";
             "demo-tour": "demo-tour";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaelio/ktx",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Standalone ktx context layer for data agents",
   "author": {
     "name": "Kaelio",
@@ -36,6 +36,8 @@
     "@ai-sdk/devtools": "0.0.18",
     "@ai-sdk/google-vertex": "^4.0.134",
     "@anthropic-ai/claude-agent-sdk": "0.3.146",
+    "@aws-sdk/client-athena": "^3.1068.0",
+    "@aws-sdk/client-glue": "^3.1068.0",
     "@clack/core": "1.3.1",
     "@clack/prompts": "1.4.0",
     "@clickhouse/client": "^1.18.5",