@kaelio/ktx 0.4.0 → 0.5.0

package/dist/connectors/snowflake/sdk-logger.test.js

@@ -0,0 +1,47 @@
+import { mkdtempSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const { configure } = vi.hoisted(() => ({ configure: vi.fn() }));
+vi.mock('snowflake-sdk', () => ({
+    default: { configure },
+}));
+import { configureSnowflakeSdkLogger, resetSnowflakeSdkLoggerConfigurationForTests, } from './sdk-logger.js';
+describe('configureSnowflakeSdkLogger', () => {
+    let projectDir;
+    beforeEach(() => {
+        configure.mockReset();
+        resetSnowflakeSdkLoggerConfigurationForTests();
+        projectDir = mkdtempSync(join(tmpdir(), 'ktx-snowflake-logger-'));
+    });
+    afterEach(() => {
+        rmSync(projectDir, { recursive: true, force: true });
+    });
+    it('routes logs to <projectDir>/.ktx/logs/snowflake.log with console output disabled', () => {
+        const expected = resolve(projectDir, '.ktx', 'logs', 'snowflake.log');
+        const returned = configureSnowflakeSdkLogger(projectDir);
+        expect(returned).toBe(expected);
+        expect(configure).toHaveBeenCalledTimes(1);
+        expect(configure).toHaveBeenCalledWith({
+            logFilePath: expected,
+            additionalLogToConsole: false,
+        });
+        expect(statSync(resolve(projectDir, '.ktx', 'logs')).isDirectory()).toBe(true);
+    });
+    it('is idempotent for the same projectDir', () => {
+        configureSnowflakeSdkLogger(projectDir);
+        configureSnowflakeSdkLogger(projectDir);
+        expect(configure).toHaveBeenCalledTimes(1);
+    });
+    it('reconfigures when projectDir changes', () => {
+        const other = mkdtempSync(join(tmpdir(), 'ktx-snowflake-logger-other-'));
+        try {
+            configureSnowflakeSdkLogger(projectDir);
+            configureSnowflakeSdkLogger(other);
+            expect(configure).toHaveBeenCalledTimes(2);
+        }
+        finally {
+            rmSync(other, { recursive: true, force: true });
+        }
+    });
+});

package/dist/connectors/sqlite/connector.d.ts

@@ -0,0 +1,61 @@
+import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+export interface KtxSqliteConnectionConfig {
+    driver?: string;
+    path?: string;
+    url?: string;
+    [key: string]: unknown;
+}
+/** @internal */
+export interface SqliteDatabasePathInput {
+    connectionId: string;
+    projectDir?: string;
+    connection: KtxSqliteConnectionConfig | undefined;
+}
+export interface KtxSqliteScanConnectorOptions extends SqliteDatabasePathInput {
+    now?: () => Date;
+}
+export interface KtxSqliteReadOnlyQueryInput extends KtxReadOnlyQueryInput {
+    params?: Record<string, unknown> | unknown[];
+}
+export interface KtxSqliteColumnDistinctValuesOptions {
+    maxCardinality: number;
+    limit: number;
+    sampleSize?: number;
+}
+export interface KtxSqliteColumnDistinctValuesResult {
+    values: string[] | null;
+    cardinality: number;
+}
+export declare function isKtxSqliteConnectionConfig(connection: KtxSqliteConnectionConfig | undefined): connection is KtxSqliteConnectionConfig;
+/** @internal */
+export declare function sqliteDatabasePathFromConfig(input: SqliteDatabasePathInput): string;
+export declare class KtxSqliteScanConnector implements KtxScanConnector {
+    readonly id: string;
+    readonly driver: "sqlite";
+    readonly capabilities: import("../../context/scan/types.js").KtxConnectorCapabilities;
+    private readonly connectionId;
+    private readonly dbPath;
+    private readonly now;
+    private readonly dialect;
+    private db;
+    constructor(options: KtxSqliteScanConnectorOptions);
+    testConnection(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
+    sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxTableSampleResult>;
+    sampleColumn(input: KtxColumnSampleInput, _ctx: KtxScanContext): Promise<KtxColumnSampleResult>;
+    columnStats(_input: KtxColumnStatsInput, _ctx: KtxScanContext): Promise<KtxColumnStatsResult | null>;
+    executeReadOnly(input: KtxSqliteReadOnlyQueryInput, _ctx: KtxScanContext): Promise<KtxQueryResult>;
+    getColumnDistinctValues(table: KtxTableRef, columnName: string, options: KtxSqliteColumnDistinctValuesOptions): Promise<KtxSqliteColumnDistinctValuesResult | null>;
+    getTableRowCount(tableName: string): Promise<number>;
+    qTableName(table: Pick<KtxTableRef, 'name'>): string;
+    quoteIdentifier(identifier: string): string;
+    cleanup(): Promise<void>;
+    private database;
+    private query;
+    private readTable;
+    private mapForeignKeys;
+    private assertConnection;
+}

package/dist/connectors/sqlite/connector.js

@@ -0,0 +1,260 @@
+import Database from 'better-sqlite3';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
+import { normalizeQueryRows } from '../../context/connections/query-executor.js';
+import { createKtxConnectorCapabilities } from '../../context/scan/types.js';
+import { scopedTableNames } from '../../context/scan/table-ref.js';
+import { KtxSqliteDialect } from './dialect.js';
+function stringConfigValue(connection, key) {
+    const value = connection?.[key];
+    return typeof value === 'string' && value.trim().length > 0 ? resolveStringReference(key, value.trim()) : undefined;
+}
+function resolveStringReference(key, value) {
+    if (value.startsWith('env:')) {
+        return process.env[value.slice('env:'.length)] ?? '';
+    }
+    // `file:` on the `url` key is SQLite's native URI form (e.g. `file:///db.sqlite`), not a
+    // file-contents reference — skip the read so the URI passes through verbatim.
+    if (key !== 'url' && value.startsWith('file:')) {
+        const rawPath = value.slice('file:'.length);
+        const path = rawPath.startsWith('~') ? resolve(homedir(), rawPath.slice(1)) : rawPath;
+        return readFileSync(path, 'utf-8').trim();
+    }
+    return value;
+}
+function sqlitePathFromUrl(url) {
+    if (url.startsWith('file:')) {
+        return fileURLToPath(url);
+    }
+    if (url.startsWith('sqlite:')) {
+        const parsed = new URL(url);
+        return decodeURIComponent(parsed.pathname);
+    }
+    return url;
+}
+function stripLeadingSqlComments(sql) {
+    let index = 0;
+    while (index < sql.length) {
+        while (/\s/.test(sql[index] ?? '')) {
+            index += 1;
+        }
+        if (sql.startsWith('--', index)) {
+            const end = sql.indexOf('\n', index + 2);
+            index = end === -1 ? sql.length : end + 1;
+            continue;
+        }
+        if (sql.startsWith('/*', index)) {
+            const end = sql.indexOf('*/', index + 2);
+            if (end === -1) {
+                return sql.slice(index);
+            }
+            index = end + 2;
+            continue;
+        }
+        break;
+    }
+    return sql.slice(index);
+}
+export function isKtxSqliteConnectionConfig(connection) {
+    const driver = String(connection?.driver ?? '').toLowerCase();
+    return driver === 'sqlite' || driver === 'sqlite3';
+}
+/** @internal */
+export function sqliteDatabasePathFromConfig(input) {
+    const inputDriver = input.connection?.driver ?? 'unknown';
+    if (!isKtxSqliteConnectionConfig(input.connection)) {
+        throw new Error(`Native SQLite connector cannot run driver "${inputDriver}"`);
+    }
+    const configuredPath = stringConfigValue(input.connection, 'path') ?? sqlitePathFromUrl(stringConfigValue(input.connection, 'url') ?? '');
+    if (!configuredPath) {
+        throw new Error(`Native SQLite connector requires connections.${input.connectionId}.path or url`);
+    }
+    return isAbsolute(configuredPath) ? configuredPath : resolve(input.projectDir ?? process.cwd(), configuredPath);
+}
+export class KtxSqliteScanConnector {
+    id;
+    driver = 'sqlite';
+    capabilities = createKtxConnectorCapabilities({
+        tableSampling: true,
+        columnSampling: true,
+        columnStats: false,
+        readOnlySql: true,
+        nestedAnalysis: false,
+        formalForeignKeys: true,
+        estimatedRowCounts: true,
+    });
+    connectionId;
+    dbPath;
+    now;
+    dialect = new KtxSqliteDialect();
+    db = null;
+    constructor(options) {
+        this.connectionId = options.connectionId;
+        this.dbPath = sqliteDatabasePathFromConfig(options);
+        this.now = options.now ?? (() => new Date());
+        this.id = `sqlite:${options.connectionId}`;
+    }
+    async testConnection() {
+        try {
+            if (!existsSync(this.dbPath) || !statSync(this.dbPath).isFile()) {
+                return { success: false, error: `File not found: ${this.dbPath}` };
+            }
+            this.database().prepare('SELECT 1').get();
+            return { success: true };
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    async introspect(input, _ctx) {
+        this.assertConnection(input.connectionId);
+        const database = this.database();
+        const scopedNames = input.tableScope ? scopedTableNames(input.tableScope, { catalog: null, db: null }) : null;
+        const scopeClause = scopedNames ? `AND name IN (${scopedNames.map(() => '?').join(', ')})` : '';
+        const rawTables = scopedNames && scopedNames.length === 0
+            ? []
+            : database
+                .prepare(`SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%' ${scopeClause} ORDER BY name`)
+                .all(...(scopedNames ?? []));
+        const tables = rawTables.map((table) => this.readTable(database, table));
+        const fileStats = existsSync(this.dbPath) ? statSync(this.dbPath) : null;
+        return {
+            connectionId: this.connectionId,
+            driver: 'sqlite',
+            extractedAt: this.now().toISOString(),
+            scope: {},
+            metadata: {
+                file_path: this.dbPath,
+                file_size: fileStats ? fileStats.size : 0,
+                table_count: tables.length,
+                total_columns: tables.reduce((sum, table) => sum + table.columns.length, 0),
+            },
+            tables,
+        };
+    }
+    async sampleTable(input, _ctx) {
+        this.assertConnection(input.connectionId);
+        const result = this.query(this.dialect.generateSampleQuery(this.qTableName(input.table), input.limit, input.columns));
+        return { headers: result.headers, rows: result.rows, totalRows: result.totalRows };
+    }
+    async sampleColumn(input, _ctx) {
+        this.assertConnection(input.connectionId);
+        const result = this.query(this.dialect.generateColumnSampleQuery(this.qTableName(input.table), input.column, input.limit));
+        const values = result.rows.filter((row) => row.length > 0 && row[0] !== null).map((row) => row[0]);
+        return { values, nullCount: null, distinctCount: null };
+    }
+    async columnStats(_input, _ctx) {
+        return null;
+    }
+    async executeReadOnly(input, _ctx) {
+        this.assertConnection(input.connectionId);
+        const result = this.query(limitSqlForExecution(stripLeadingSqlComments(input.sql), input.maxRows), input.params);
+        return { ...result, rowCount: result.rows.length };
+    }
+    async getColumnDistinctValues(table, columnName, options) {
+        const sampleSize = options.sampleSize ?? 10000;
+        const tableName = this.qTableName(table);
+        const quotedColumn = this.dialect.quoteIdentifier(columnName);
+        const cardinalityResult = this.query(this.dialect.generateCardinalitySampleQuery(tableName, quotedColumn, sampleSize));
+        if (cardinalityResult.rows.length === 0) {
+            return null;
+        }
+        const cardinality = Number(cardinalityResult.rows[0][0]);
+        if (Number.isNaN(cardinality)) {
+            return null;
+        }
+        if (cardinality === 0) {
+            return { values: [], cardinality: 0 };
+        }
+        if (cardinality > options.maxCardinality) {
+            return { values: null, cardinality };
+        }
+        const valuesResult = this.query(this.dialect.generateDistinctValuesQuery(tableName, quotedColumn, options.limit));
+        return {
+            values: valuesResult.rows.filter((row) => row.length > 0 && row[0] !== null).map((row) => String(row[0])),
+            cardinality,
+        };
+    }
+    async getTableRowCount(tableName) {
+        const result = this.query(`SELECT COUNT(*) AS count FROM ${this.dialect.quoteIdentifier(tableName)}`);
+        return Number(result.rows[0]?.[0] ?? 0);
+    }
+    qTableName(table) {
+        return this.dialect.formatTableName(table);
+    }
+    quoteIdentifier(identifier) {
+        return this.dialect.quoteIdentifier(identifier);
+    }
+    async cleanup() {
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+    }
+    database() {
+        if (!this.db) {
+            this.db = new Database(this.dbPath, { readonly: true, fileMustExist: true });
+        }
+        return this.db;
+    }
+    query(sql, params) {
+        const statement = this.database().prepare(assertReadOnlySql(sql));
+        const rows = (params ? statement.all(params) : statement.all());
+        return {
+            headers: statement.columns().map((column) => column.name),
+            rows: normalizeQueryRows(rows),
+            totalRows: rows.length,
+        };
+    }
+    readTable(database, table) {
+        const columns = database
+            .prepare(`PRAGMA table_info(${this.dialect.quoteIdentifier(table.name)})`)
+            .all();
+        const foreignKeys = database
+            .prepare(`PRAGMA foreign_key_list(${this.dialect.quoteIdentifier(table.name)})`)
+            .all();
+        const estimatedRows = table.type === 'table'
+            ? Number(database
+                .prepare(`SELECT COUNT(*) AS count FROM ${this.dialect.quoteIdentifier(table.name)}`)
+                .get().count)
+            : null;
+        return {
+            catalog: null,
+            db: null,
+            name: table.name,
+            kind: table.type,
+            comment: null,
+            estimatedRows,
+            columns: columns.map((column) => ({
+                name: column.name,
+                nativeType: column.type,
+                normalizedType: this.dialect.mapDataType(column.type),
+                dimensionType: this.dialect.mapToDimensionType(column.type),
+                nullable: column.notnull === 0 && column.pk === 0,
+                primaryKey: column.pk > 0,
+                comment: null,
+            })),
+            foreignKeys: this.mapForeignKeys(foreignKeys),
+        };
+    }
+    mapForeignKeys(rows) {
+        return rows
+            .sort((a, b) => a.id - b.id || a.seq - b.seq)
+            .map((row) => ({
+            fromColumn: row.from,
+            toCatalog: null,
+            toDb: null,
+            toTable: row.table,
+            toColumn: row.to,
+            constraintName: null,
+        }));
+    }
+    assertConnection(connectionId) {
+        if (connectionId !== this.connectionId) {
+            throw new Error(`KTX SQLite connector ${this.id} cannot serve connection ${connectionId}`);
+        }
+    }
+}

package/dist/connectors/sqlite/connector.test.js

@@ -0,0 +1,207 @@
+import Database from 'better-sqlite3';
+import { writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createSqliteLiveDatabaseIntrospection } from '../../connectors/sqlite/live-database-introspection.js';
+import { isKtxSqliteConnectionConfig, KtxSqliteScanConnector, sqliteDatabasePathFromConfig } from '../../connectors/sqlite/connector.js';
+import { tableRefSet } from '../../context/scan/table-ref.js';
+describe('KtxSqliteScanConnector', () => {
+    let tempDir;
+    let dbPath;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-connector-sqlite-'));
+        dbPath = join(tempDir, 'warehouse.db');
+        const db = new Database(dbPath);
+        db.exec(`
+      PRAGMA foreign_keys = ON;
+      CREATE TABLE customers (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        tier TEXT
+      );
+      CREATE TABLE orders (
+        id INTEGER PRIMARY KEY,
+        customer_id INTEGER NOT NULL,
+        status TEXT,
+        total NUMERIC,
+        created_at TEXT,
+        FOREIGN KEY(customer_id) REFERENCES customers(id)
+      );
+      CREATE VIEW recent_orders AS SELECT id, customer_id, status FROM orders;
+      INSERT INTO customers (id, name, tier) VALUES (1, 'Ada', 'enterprise'), (2, 'Grace', 'growth');
+      INSERT INTO orders (id, customer_id, status, total, created_at)
+        VALUES (10, 1, 'paid', 42.5, '2026-04-28'), (11, 2, 'open', 9.5, '2026-04-29');
+    `);
+        db.close();
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('resolves SQLite path configuration safely', () => {
+        const originalDatabaseUrl = process.env.KTX_SQLITE_TEST_URL;
+        const pointerPath = join(tempDir, 'sqlite-path.txt');
+        process.env.KTX_SQLITE_TEST_URL = `sqlite:${dbPath}`;
+        writeFileSync(pointerPath, dbPath, 'utf-8');
+        try {
+            expect(isKtxSqliteConnectionConfig({ driver: 'sqlite', path: 'warehouse.db' })).toBe(true);
+            expect(isKtxSqliteConnectionConfig({ driver: 'postgres', url: 'env:DATABASE_URL' })).toBe(false);
+            expect(sqliteDatabasePathFromConfig({
+                connectionId: 'warehouse',
+                projectDir: tempDir,
+                connection: { driver: 'sqlite', path: 'warehouse.db' },
+            })).toBe(dbPath);
+            expect(sqliteDatabasePathFromConfig({
+                connectionId: 'warehouse',
+                projectDir: tempDir,
+                connection: { driver: 'sqlite', url: 'env:KTX_SQLITE_TEST_URL' },
+            })).toBe(dbPath);
+            expect(sqliteDatabasePathFromConfig({
+                connectionId: 'warehouse',
+                projectDir: tempDir,
+                connection: { driver: 'sqlite', url: `file://${dbPath}` },
+            })).toBe(dbPath);
+            expect(sqliteDatabasePathFromConfig({
+                connectionId: 'warehouse',
+                projectDir: tempDir,
+                connection: { driver: 'sqlite', path: `file:${pointerPath}` },
+            })).toBe(dbPath);
+            expect(sqliteDatabasePathFromConfig({
+                connectionId: 'warehouse',
+                projectDir: tempDir,
+                connection: { driver: 'sqlite', path: 'warehouse.db' },
+            })).toBe(dbPath);
+            expect(() => sqliteDatabasePathFromConfig({
+                connectionId: 'warehouse',
+                projectDir: tempDir,
+                connection: { driver: 'sqlite', file_path: 'warehouse.db' },
+            })).toThrow('Native SQLite connector requires connections.warehouse.path or url');
+        }
+        finally {
+            if (originalDatabaseUrl === undefined) {
+                delete process.env.KTX_SQLITE_TEST_URL;
+            }
+            else {
+                process.env.KTX_SQLITE_TEST_URL = originalDatabaseUrl;
+            }
+        }
+    });
+    it('introspects schema, primary keys, row counts, views, and foreign keys', async () => {
+        const connector = new KtxSqliteScanConnector({
+            connectionId: 'warehouse',
+            connection: { driver: 'sqlite', path: dbPath },
+            now: () => new Date('2026-04-29T10:00:00.000Z'),
+        });
+        const snapshot = await connector.introspect({ connectionId: 'warehouse', driver: 'sqlite' }, { runId: 'scan-run-1' });
+        expect(snapshot).toMatchObject({
+            connectionId: 'warehouse',
+            driver: 'sqlite',
+            extractedAt: '2026-04-29T10:00:00.000Z',
+            metadata: {
+                file_path: dbPath,
+                table_count: 3,
+                total_columns: 11,
+            },
+        });
+        expect(snapshot.tables.map((table) => [table.name, table.kind, table.estimatedRows])).toEqual([
+            ['customers', 'table', 2],
+            ['orders', 'table', 2],
+            ['recent_orders', 'view', null],
+        ]);
+        expect(snapshot.tables.find((table) => table.name === 'customers')?.columns[0]).toMatchObject({
+            name: 'id',
+            nativeType: 'INTEGER',
+            normalizedType: 'INTEGER',
+            dimensionType: 'number',
+            nullable: false,
+            primaryKey: true,
+        });
+        expect(snapshot.tables.find((table) => table.name === 'orders')?.foreignKeys).toEqual([
+            {
+                fromColumn: 'customer_id',
+                toCatalog: null,
+                toDb: null,
+                toTable: 'customers',
+                toColumn: 'id',
+                constraintName: null,
+            },
+        ]);
+    });
+    it('runs samples, distinct values, statistics, and read-only SQL', async () => {
+        const connector = new KtxSqliteScanConnector({
+            connectionId: 'warehouse',
+            connection: { driver: 'sqlite', path: dbPath },
+        });
+        await expect(connector.sampleTable({ connectionId: 'warehouse', table: { catalog: null, db: null, name: 'orders' }, columns: ['id'], limit: 1 }, { runId: 'scan-run-1' })).resolves.toEqual({ headers: ['id'], rows: [[10]], totalRows: 1 });
+        await expect(connector.sampleColumn({ connectionId: 'warehouse', table: { catalog: null, db: null, name: 'orders' }, column: 'status', limit: 5 }, { runId: 'scan-run-1' })).resolves.toMatchObject({ values: ['paid', 'open'], nullCount: null, distinctCount: null });
+        await expect(connector.getColumnDistinctValues({ catalog: null, db: null, name: 'orders' }, 'status', { maxCardinality: 5, limit: 10, sampleSize: 100 })).resolves.toEqual({ values: ['open', 'paid'], cardinality: 2 });
+        await expect(connector.executeReadOnly({ connectionId: 'warehouse', sql: 'select id, status from orders order by id', maxRows: 1 }, { runId: 'scan-run-1' })).resolves.toEqual({ headers: ['id', 'status'], rows: [[10, 'paid']], totalRows: 1, rowCount: 1 });
+        await expect(connector.executeReadOnly({ connectionId: 'warehouse', sql: 'delete from orders' }, { runId: 'scan-run-1' })).rejects.toThrow('Only read-only SELECT/WITH queries can be executed locally');
+        await expect(connector.columnStats({ connectionId: 'warehouse', table: { catalog: null, db: null, name: 'orders' }, column: 'status' }, { runId: 'scan-run-1' })).resolves.toBeNull();
+    });
+    it('limits introspection to tables in tableScope', async () => {
+        const connector = new KtxSqliteScanConnector({
+            connectionId: 'warehouse',
+            connection: { driver: 'sqlite', path: dbPath },
+        });
+        const scope = tableRefSet([{ catalog: null, db: null, name: 'orders' }]);
+        const snapshot = await connector.introspect({ connectionId: 'warehouse', driver: 'sqlite', tableScope: scope }, { runId: 'scope-test' });
+        expect(snapshot.tables.map((table) => table.name)).toEqual(['orders']);
+    });
+    it('adapts native SQLite snapshots to live-database introspection for local ingest', async () => {
+        const introspection = createSqliteLiveDatabaseIntrospection({
+            projectDir: tempDir,
+            connections: {
+                warehouse: { driver: 'sqlite', path: 'warehouse.db' },
+            },
+            now: () => new Date('2026-04-29T10:00:00.000Z'),
+        });
+        const snapshot = await introspection.extractSchema('warehouse');
+        expect(snapshot).toMatchObject({
+            connectionId: 'warehouse',
+            extractedAt: '2026-04-29T10:00:00.000Z',
+        });
+        expect(snapshot.tables.find((table) => table.name === 'customers')).toMatchObject({
+            name: 'customers',
+            catalog: null,
+            db: null,
+            columns: [
+                {
+                    name: 'id',
+                    nativeType: 'INTEGER',
+                    normalizedType: 'INTEGER',
+                    dimensionType: 'number',
+                    nullable: false,
+                    primaryKey: true,
+                    comment: null,
+                },
+                {
+                    name: 'name',
+                    nativeType: 'TEXT',
+                    normalizedType: 'TEXT',
+                    dimensionType: 'string',
+                    nullable: false,
+                    primaryKey: false,
+                    comment: null,
+                },
+                {
+                    name: 'tier',
+                    nativeType: 'TEXT',
+                    normalizedType: 'TEXT',
+                    dimensionType: 'string',
+                    nullable: true,
+                    primaryKey: false,
+                    comment: null,
+                },
+            ],
+            foreignKeys: [],
+        });
+        expect(snapshot.tables.find((table) => table.name === 'orders')).toMatchObject({
+            name: 'orders',
+            catalog: null,
+            db: null,
+            foreignKeys: [{ fromColumn: 'customer_id', toTable: 'customers', toColumn: 'id' }],
+        });
+    });
+});

package/dist/connectors/sqlite/dialect.d.ts

@@ -0,0 +1,29 @@
+import type { KtxSchemaDimensionType, KtxTableRef } from '../../context/scan/types.js';
+type SqliteTableNameRef = Pick<KtxTableRef, 'name'> & Partial<Pick<KtxTableRef, 'catalog' | 'db'>>;
+export declare class KtxSqliteDialect {
+    readonly type = "sqlite";
+    private readonly typeMappings;
+    quoteIdentifier(identifier: string): string;
+    formatTableName(table: SqliteTableNameRef): string;
+    mapDataType(nativeType: string): string;
+    mapToDimensionType(nativeType: string): KtxSchemaDimensionType;
+    generateSampleQuery(tableName: string, limit: number, columns?: string[]): string;
+    generateColumnSampleQuery(tableName: string, columnName: string, limit: number): string;
+    prepareQuery(sql: string, params?: Record<string, unknown>): {
+        sql: string;
+        params?: unknown;
+    };
+    getRandomSampleFilter(samplePct: number): string;
+    getTableSampleClause(_samplePct: number): string;
+    getLimitOffsetClause(limit: number, offset?: number): string;
+    getNullCountExpression(column: string): string;
+    getDistinctCountExpression(column: string): string;
+    generateCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
+    generateDistinctValuesQuery(tableName: string, columnName: string, limit: number): string;
+    generateColumnStatisticsQuery(_schemaName: string, _tableName: string): string | null;
+    generateRandomizedCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
+    getTimeTruncExpression(column: string, granularity: 'day' | 'week' | 'month' | 'quarter' | 'year', _timezone?: string): string;
+    getCustomTimeTruncExpression(column: string, interval: string, origin?: string, _timezone?: string): string;
+    parseIntervalToSql(interval: string): string;
+}
+export {};

package/dist/connectors/sqlite/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 CreateSqliteLiveDatabaseIntrospectionOptions {
+    projectDir?: string;
+    connections: Record<string, KtxProjectConnectionConfig>;
+    now?: () => Date;
+}
+export declare function createSqliteLiveDatabaseIntrospection(options: CreateSqliteLiveDatabaseIntrospectionOptions): LiveDatabaseIntrospectionPort;

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

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