@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/node_modules/@ktx/connector-mysql/dist/connector.js

@@ -0,0 +1,369 @@
+import mysql from 'mysql2/promise';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { assertReadOnlySql, limitSqlForExecution } from '@ktx/context/connections';
+import { createKtxConnectorCapabilities, } from '@ktx/context/scan';
+import { KtxMysqlDialect } from './dialect.js';
+class DefaultMysqlPoolFactory {
+    createPool(config) {
+        return mysql.createPool(config);
+    }
+}
+function stringConfigValue(connection, key, env) {
+    const value = connection?.[key];
+    return typeof value === 'string' && value.trim().length > 0 ? resolveStringReference(value.trim(), env) : undefined;
+}
+function resolveStringReference(value, env) {
+    if (value.startsWith('env:')) {
+        const envName = value.slice('env:'.length);
+        return env[envName] ?? '';
+    }
+    if (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 maybeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function parseMysqlUrl(url) {
+    const parsed = new URL(url);
+    const sslParam = parsed.searchParams.get('ssl') ?? parsed.searchParams.get('sslmode');
+    return {
+        host: parsed.hostname,
+        port: parsed.port ? Number(parsed.port) : undefined,
+        database: parsed.pathname.replace(/^\/+/, '') || undefined,
+        username: parsed.username ? decodeURIComponent(parsed.username) : undefined,
+        password: parsed.password ? decodeURIComponent(parsed.password) : undefined,
+        ssl: sslParam === 'true' || sslParam === 'required',
+    };
+}
+function cleanMySqlTableComment(comment) {
+    if (!comment) {
+        return null;
+    }
+    if (comment.startsWith('InnoDB free:')) {
+        const semiIndex = comment.indexOf(';');
+        if (semiIndex === -1) {
+            return null;
+        }
+        const userComment = comment.slice(semiIndex + 1).trim();
+        return userComment || null;
+    }
+    return comment;
+}
+function groupByTable(rows) {
+    const grouped = new Map();
+    for (const row of rows) {
+        const tableRows = grouped.get(row.TABLE_NAME) ?? [];
+        tableRows.push(row);
+        grouped.set(row.TABLE_NAME, tableRows);
+    }
+    return grouped;
+}
+function primaryKeyMap(rows) {
+    const grouped = new Map();
+    for (const row of rows) {
+        const columns = grouped.get(row.TABLE_NAME) ?? new Set();
+        columns.add(row.COLUMN_NAME);
+        grouped.set(row.TABLE_NAME, columns);
+    }
+    return grouped;
+}
+function queryParams(params) {
+    if (!params) {
+        return undefined;
+    }
+    return Array.isArray(params) ? params : Object.values(params);
+}
+export function isKtxMysqlConnectionConfig(connection) {
+    return String(connection?.driver ?? '').toLowerCase() === 'mysql';
+}
+export function mysqlConnectionPoolConfigFromConfig(input) {
+    if (!isKtxMysqlConnectionConfig(input.connection)) {
+        throw new Error(`Native MySQL connector cannot run driver "${input.connection?.driver ?? 'unknown'}"`);
+    }
+    if (input.connection?.readonly !== true) {
+        throw new Error(`Native MySQL connector requires connections.${input.connectionId}.readonly: true`);
+    }
+    const env = input.env ?? process.env;
+    const referencedUrl = stringConfigValue(input.connection, 'url', env);
+    const urlConfig = referencedUrl ? parseMysqlUrl(referencedUrl) : {};
+    const merged = { ...urlConfig, ...input.connection };
+    const host = stringConfigValue(merged, 'host', env);
+    const database = stringConfigValue(merged, 'database', env);
+    const user = stringConfigValue(merged, 'username', env) ?? stringConfigValue(merged, 'user', env);
+    if (!host) {
+        throw new Error(`Native MySQL connector requires connections.${input.connectionId}.host or url`);
+    }
+    if (!database) {
+        throw new Error(`Native MySQL connector requires connections.${input.connectionId}.database or url`);
+    }
+    if (!user) {
+        throw new Error(`Native MySQL connector requires connections.${input.connectionId}.username, user, or url`);
+    }
+    const ssl = merged.ssl === true ? { rejectUnauthorized: false } : typeof merged.ssl === 'object' ? merged.ssl : undefined;
+    return {
+        host,
+        port: maybeNumber(merged.port) ?? 3306,
+        database,
+        user,
+        password: stringConfigValue(merged, 'password', env),
+        connectionLimit: 10,
+        waitForConnections: true,
+        ...(ssl ? { ssl: { rejectUnauthorized: ssl.rejectUnauthorized ?? false } } : {}),
+    };
+}
+export class KtxMysqlScanConnector {
+    id;
+    driver = 'mysql';
+    capabilities = createKtxConnectorCapabilities({
+        tableSampling: true,
+        columnSampling: true,
+        columnStats: false,
+        readOnlySql: true,
+        nestedAnalysis: true,
+        formalForeignKeys: true,
+        estimatedRowCounts: true,
+    });
+    connectionId;
+    connection;
+    poolConfig;
+    poolFactory;
+    endpointResolver;
+    now;
+    dialect = new KtxMysqlDialect();
+    pool = null;
+    resolvedEndpoint = null;
+    constructor(options) {
+        this.connectionId = options.connectionId;
+        this.connection = options.connection ?? {};
+        this.poolConfig = mysqlConnectionPoolConfigFromConfig({
+            connectionId: options.connectionId,
+            connection: options.connection,
+            env: options.env,
+        });
+        this.poolFactory = options.poolFactory ?? new DefaultMysqlPoolFactory();
+        this.endpointResolver = options.endpointResolver;
+        this.now = options.now ?? (() => new Date());
+        this.id = `mysql:${options.connectionId}`;
+    }
+    async testConnection() {
+        try {
+            await this.query('SELECT 1');
+            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.poolConfig.database;
+        const tables = await this.queryRaw(`
+      SELECT TABLE_NAME, TABLE_TYPE, TABLE_COMMENT, TABLE_ROWS
+      FROM INFORMATION_SCHEMA.TABLES
+      WHERE TABLE_SCHEMA = ? AND TABLE_TYPE IN ('BASE TABLE', 'VIEW')
+      ORDER BY TABLE_NAME
+      `, [database]);
+        const columns = await this.queryRaw(`
+      SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_COMMENT
+      FROM INFORMATION_SCHEMA.COLUMNS
+      WHERE TABLE_SCHEMA = ?
+      ORDER BY TABLE_NAME, ORDINAL_POSITION
+      `, [database]);
+        const primaryKeys = await this.queryRaw(`
+      SELECT TABLE_NAME, COLUMN_NAME
+      FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
+      WHERE TABLE_SCHEMA = ?
+        AND CONSTRAINT_NAME = 'PRIMARY'
+      ORDER BY TABLE_NAME, ORDINAL_POSITION
+      `, [database]);
+        const foreignKeys = await this.queryRaw(`
+      SELECT TABLE_NAME, COLUMN_NAME, REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME, CONSTRAINT_NAME
+      FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
+      WHERE TABLE_SCHEMA = ?
+        AND REFERENCED_TABLE_NAME IS NOT NULL
+      ORDER BY TABLE_NAME, COLUMN_NAME
+      `, [database]);
+        const columnsByTable = groupByTable(columns);
+        const primaryKeysByTable = primaryKeyMap(primaryKeys);
+        const foreignKeysByTable = groupByTable(foreignKeys);
+        const schemaTables = tables.map((table) => this.toSchemaTable(table, columnsByTable.get(table.TABLE_NAME) ?? [], primaryKeysByTable, foreignKeysByTable));
+        return {
+            connectionId: this.connectionId,
+            driver: 'mysql',
+            extractedAt: this.now().toISOString(),
+            scope: { schemas: [database] },
+            metadata: {
+                database,
+                host: this.poolConfig.host,
+                table_count: schemaTables.length,
+                total_columns: schemaTables.reduce((sum, table) => sum + table.columns.length, 0),
+            },
+            tables: schemaTables,
+        };
+    }
+    async sampleTable(input, _ctx) {
+        this.assertConnection(input.connectionId);
+        const result = await 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 = await 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 limitedSql = limitSqlForExecution(assertReadOnlySql(input.sql), input.maxRows);
+        const prepared = Array.isArray(input.params)
+            ? { sql: limitedSql, params: input.params }
+            : this.dialect.prepareQuery(limitedSql, input.params);
+        const result = await this.query(prepared.sql, prepared.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 cardinalityRows = await this.queryRaw(this.dialect.generateCardinalitySampleQuery(tableName, quotedColumn, sampleSize));
+        const cardinality = Number(cardinalityRows[0]?.cardinality);
+        if (Number.isNaN(cardinality)) {
+            return null;
+        }
+        if (cardinality === 0) {
+            return { values: [], cardinality: 0 };
+        }
+        if (cardinality > options.maxCardinality) {
+            return { values: null, cardinality };
+        }
+        const valuesRows = await this.queryRaw(this.dialect.generateDistinctValuesQuery(tableName, quotedColumn, options.limit));
+        return {
+            values: valuesRows.filter((row) => row.val !== null).map((row) => String(row.val)),
+            cardinality,
+        };
+    }
+    async getTableRowCount(tableName) {
+        const rows = await this.queryRaw(`SELECT COUNT(*) AS count FROM ${this.dialect.quoteIdentifier(tableName)}`);
+        return Number(rows[0]?.count ?? 0);
+    }
+    qTableName(table) {
+        return this.dialect.formatTableName(table);
+    }
+    quoteIdentifier(identifier) {
+        return this.dialect.quoteIdentifier(identifier);
+    }
+    async listSchemas() {
+        const rows = await this.queryRaw(`
+      SELECT SCHEMA_NAME
+      FROM INFORMATION_SCHEMA.SCHEMATA
+      WHERE SCHEMA_NAME NOT IN ('information_schema', 'mysql', 'performance_schema', 'sys')
+      ORDER BY SCHEMA_NAME
+    `);
+        return rows.map((row) => row.SCHEMA_NAME);
+    }
+    async cleanup() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+        }
+        if (this.resolvedEndpoint?.close) {
+            await this.resolvedEndpoint.close();
+            this.resolvedEndpoint = null;
+        }
+    }
+    toSchemaTable(table, columns, primaryKeysByTable, foreignKeysByTable) {
+        const tableName = table.TABLE_NAME;
+        const kind = table.TABLE_TYPE === 'VIEW' ? 'view' : 'table';
+        const estimatedRows = kind === 'view' ? null : Number(table.TABLE_ROWS ?? 0);
+        return {
+            catalog: null,
+            db: this.poolConfig.database,
+            name: tableName,
+            kind,
+            comment: cleanMySqlTableComment(table.TABLE_COMMENT),
+            estimatedRows: Number.isFinite(estimatedRows) ? estimatedRows : null,
+            columns: columns.map((column) => this.toSchemaColumn(column, primaryKeysByTable.get(tableName) ?? new Set())),
+            foreignKeys: (foreignKeysByTable.get(tableName) ?? []).map((row) => this.toSchemaForeignKey(row)),
+        };
+    }
+    toSchemaColumn(column, primaryKeys) {
+        return {
+            name: column.COLUMN_NAME,
+            nativeType: column.DATA_TYPE,
+            normalizedType: this.dialect.mapDataType(column.DATA_TYPE),
+            dimensionType: this.dialect.mapToDimensionType(column.DATA_TYPE),
+            nullable: column.IS_NULLABLE === 'YES',
+            primaryKey: primaryKeys.has(column.COLUMN_NAME),
+            comment: column.COLUMN_COMMENT || null,
+        };
+    }
+    toSchemaForeignKey(row) {
+        return {
+            fromColumn: row.COLUMN_NAME,
+            toCatalog: null,
+            toDb: this.poolConfig.database,
+            toTable: row.REFERENCED_TABLE_NAME,
+            toColumn: row.REFERENCED_COLUMN_NAME,
+            constraintName: row.CONSTRAINT_NAME || null,
+        };
+    }
+    async poolForQuery() {
+        if (!this.pool) {
+            const config = { ...this.poolConfig };
+            if (this.endpointResolver) {
+                this.resolvedEndpoint = await this.endpointResolver.resolve({
+                    host: config.host,
+                    port: config.port,
+                    connection: this.connection,
+                });
+                config.host = this.resolvedEndpoint.host;
+                config.port = this.resolvedEndpoint.port;
+            }
+            this.pool = this.poolFactory.createPool(config);
+        }
+        return this.pool;
+    }
+    async queryRaw(sql, params) {
+        const pool = await this.poolForQuery();
+        const connection = await pool.getConnection();
+        try {
+            const [rows] = await connection.query(sql, params);
+            return rows;
+        }
+        finally {
+            connection.release();
+        }
+    }
+    async query(sql, params) {
+        const pool = await this.poolForQuery();
+        const connection = await pool.getConnection();
+        try {
+            const [rows, fields] = await connection.query(assertReadOnlySql(sql), queryParams(params));
+            const headers = fields.map((field) => field.name);
+            const headerTypes = fields.map((field) => String(field.type ?? 'unknown'));
+            return {
+                headers,
+                headerTypes,
+                rows: rows.map((row) => headers.map((header) => row[header])),
+                totalRows: rows.length,
+            };
+        }
+        finally {
+            connection.release();
+        }
+    }
+    assertConnection(connectionId) {
+        if (connectionId !== this.connectionId) {
+            throw new Error(`KTX MySQL connector ${this.id} cannot serve connection ${connectionId}`);
+        }
+    }
+}

package/node_modules/@ktx/connector-mysql/dist/connector.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/connector-mysql/dist/connector.test.js

@@ -0,0 +1,226 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createMysqlLiveDatabaseIntrospection, isKtxMysqlConnectionConfig, KtxMysqlScanConnector, mysqlConnectionPoolConfigFromConfig, } from './index.js';
+function mysqlResult(rows, fields) {
+    return [rows, fields];
+}
+function fakePoolFactory() {
+    const query = vi.fn(async (sql, params) => {
+        if (sql.includes('INFORMATION_SCHEMA.TABLES')) {
+            return mysqlResult([
+                { TABLE_NAME: 'customers', TABLE_TYPE: 'BASE TABLE', TABLE_COMMENT: 'Customer table', TABLE_ROWS: 2 },
+                { TABLE_NAME: 'orders', TABLE_TYPE: 'BASE TABLE', TABLE_COMMENT: 'InnoDB free: 1 kB; Order table', TABLE_ROWS: 2 },
+                { TABLE_NAME: 'order_summary', TABLE_TYPE: 'VIEW', TABLE_COMMENT: '', TABLE_ROWS: null },
+            ], [{ name: 'TABLE_NAME' }, { name: 'TABLE_TYPE' }, { name: 'TABLE_COMMENT' }, { name: 'TABLE_ROWS' }]);
+        }
+        if (sql.includes('INFORMATION_SCHEMA.COLUMNS')) {
+            return mysqlResult([
+                { TABLE_NAME: 'customers', COLUMN_NAME: 'id', DATA_TYPE: 'int', IS_NULLABLE: 'NO', COLUMN_COMMENT: 'PK' },
+                { TABLE_NAME: 'customers', COLUMN_NAME: 'name', DATA_TYPE: 'varchar', IS_NULLABLE: 'NO', COLUMN_COMMENT: '' },
+                { TABLE_NAME: 'orders', COLUMN_NAME: 'id', DATA_TYPE: 'int', IS_NULLABLE: 'NO', COLUMN_COMMENT: '' },
+                { TABLE_NAME: 'orders', COLUMN_NAME: 'customer_id', DATA_TYPE: 'int', IS_NULLABLE: 'NO', COLUMN_COMMENT: '' },
+                { TABLE_NAME: 'orders', COLUMN_NAME: 'status', DATA_TYPE: 'varchar', IS_NULLABLE: 'YES', COLUMN_COMMENT: '' },
+                { TABLE_NAME: 'order_summary', COLUMN_NAME: 'status', DATA_TYPE: 'varchar', IS_NULLABLE: 'YES', COLUMN_COMMENT: '' },
+            ], [{ name: 'TABLE_NAME' }, { name: 'COLUMN_NAME' }, { name: 'DATA_TYPE' }, { name: 'IS_NULLABLE' }]);
+        }
+        if (sql.includes('INFORMATION_SCHEMA.KEY_COLUMN_USAGE') && sql.includes("CONSTRAINT_NAME = 'PRIMARY'")) {
+            return mysqlResult([{ TABLE_NAME: 'customers', COLUMN_NAME: 'id' }, { TABLE_NAME: 'orders', COLUMN_NAME: 'id' }], []);
+        }
+        if (sql.includes('INFORMATION_SCHEMA.KEY_COLUMN_USAGE') && sql.includes('REFERENCED_TABLE_NAME IS NOT NULL')) {
+            return mysqlResult([
+                {
+                    TABLE_NAME: 'orders',
+                    COLUMN_NAME: 'customer_id',
+                    REFERENCED_TABLE_NAME: 'customers',
+                    REFERENCED_COLUMN_NAME: 'id',
+                    CONSTRAINT_NAME: 'orders_customer_id_fk',
+                },
+            ], []);
+        }
+        if (sql.includes('SELECT `id`, `status` FROM `analytics`.`orders` LIMIT 1')) {
+            return mysqlResult([{ id: 10, status: 'paid' }], [{ name: 'id', type: 3 }, { name: 'status', type: 253 }]);
+        }
+        if (sql.includes('select * from (select id, status from analytics.orders) as ktx_query_result limit 1')) {
+            return mysqlResult([{ id: 10, status: 'paid' }], [{ name: 'id', type: 3 }, { name: 'status', type: 253 }]);
+        }
+        if (sql.includes('SELECT `status` FROM `analytics`.`orders`')) {
+            return mysqlResult([{ status: 'paid' }, { status: 'open' }], [{ name: 'status', type: 253 }]);
+        }
+        if (sql.includes('COUNT(DISTINCT val)')) {
+            return mysqlResult([{ cardinality: 2 }], [{ name: 'cardinality', type: 8 }]);
+        }
+        if (sql.includes('SELECT DISTINCT CAST(`status` AS CHAR) AS val')) {
+            return mysqlResult([{ val: 'open' }, { val: 'paid' }], [{ name: 'val', type: 253 }]);
+        }
+        if (sql.includes('COUNT(*) AS count')) {
+            return mysqlResult([{ count: 2 }], [{ name: 'count', type: 8 }]);
+        }
+        if (sql.includes('INFORMATION_SCHEMA.SCHEMATA')) {
+            return mysqlResult([{ SCHEMA_NAME: 'analytics' }, { SCHEMA_NAME: 'warehouse' }], [{ name: 'SCHEMA_NAME' }]);
+        }
+        if (sql.trim() === 'SELECT 1') {
+            return mysqlResult([{ '1': 1 }], [{ name: '1', type: 8 }]);
+        }
+        throw new Error(`Unexpected SQL: ${sql} params=${JSON.stringify(params)}`);
+    });
+    const release = vi.fn();
+    const end = vi.fn(async () => undefined);
+    return {
+        createPool: vi.fn(() => ({
+            getConnection: vi.fn(async () => ({ query, release })),
+            end,
+        })),
+    };
+}
+describe('KtxMysqlScanConnector', () => {
+    it('resolves MySQL connection configuration safely', () => {
+        expect(isKtxMysqlConnectionConfig({ driver: 'mysql', host: 'localhost', database: 'analytics', readonly: true })).toBe(true);
+        expect(isKtxMysqlConnectionConfig({ driver: 'postgres', host: 'localhost', database: 'analytics' })).toBe(false);
+        expect(mysqlConnectionPoolConfigFromConfig({
+            connectionId: 'warehouse',
+            connection: {
+                driver: 'mysql',
+                host: 'db.example.test',
+                port: 3307,
+                database: 'analytics',
+                username: 'reader',
+                password: 'secret', // pragma: allowlist secret
+                ssl: true,
+                readonly: true,
+            },
+        })).toMatchObject({
+            host: 'db.example.test',
+            port: 3307,
+            database: 'analytics',
+            user: 'reader',
+            password: 'secret', // pragma: allowlist secret
+            ssl: { rejectUnauthorized: false },
+        });
+        expect(() => mysqlConnectionPoolConfigFromConfig({
+            connectionId: 'warehouse',
+            connection: { driver: 'mysql', host: 'db.example.test', database: 'analytics', readonly: false },
+        })).toThrow('Native MySQL connector requires connections.warehouse.readonly: true');
+    });
+    it('introspects schema, primary keys, comments, row counts, views, and foreign keys', async () => {
+        const connector = new KtxMysqlScanConnector({
+            connectionId: 'warehouse',
+            connection: {
+                driver: 'mysql',
+                host: 'db.example.test',
+                database: 'analytics',
+                username: 'reader',
+                password: 'secret', // pragma: allowlist secret
+                readonly: true,
+            },
+            poolFactory: fakePoolFactory(),
+            now: () => new Date('2026-04-29T12:00:00.000Z'),
+        });
+        const snapshot = await connector.introspect({ connectionId: 'warehouse', driver: 'mysql' }, { runId: 'scan-run-1' });
+        expect(snapshot).toMatchObject({
+            connectionId: 'warehouse',
+            driver: 'mysql',
+            extractedAt: '2026-04-29T12:00:00.000Z',
+            scope: { schemas: ['analytics'] },
+            metadata: {
+                database: 'analytics',
+                host: 'db.example.test',
+                table_count: 3,
+                total_columns: 6,
+            },
+        });
+        expect(snapshot.tables.map((table) => [table.name, table.kind, table.estimatedRows, table.comment])).toEqual([
+            ['customers', 'table', 2, 'Customer table'],
+            ['orders', 'table', 2, 'Order table'],
+            ['order_summary', 'view', null, null],
+        ]);
+        expect(snapshot.tables.find((table) => table.name === 'customers')?.columns[0]).toMatchObject({
+            name: 'id',
+            nativeType: 'int',
+            normalizedType: 'int',
+            dimensionType: 'number',
+            nullable: false,
+            primaryKey: true,
+            comment: 'PK',
+        });
+        expect(snapshot.tables.find((table) => table.name === 'orders')?.foreignKeys).toEqual([
+            {
+                fromColumn: 'customer_id',
+                toCatalog: null,
+                toDb: 'analytics',
+                toTable: 'customers',
+                toColumn: 'id',
+                constraintName: 'orders_customer_id_fk',
+            },
+        ]);
+    });
+    it('runs samples, distinct values, read-only SQL, row count, schema list, and cleanup', async () => {
+        const poolFactory = fakePoolFactory();
+        const connector = new KtxMysqlScanConnector({
+            connectionId: 'warehouse',
+            connection: {
+                driver: 'mysql',
+                host: 'db.example.test',
+                database: 'analytics',
+                username: 'reader',
+                password: 'secret', // pragma: allowlist secret
+                readonly: true,
+            },
+            poolFactory,
+        });
+        await expect(connector.sampleTable({ connectionId: 'warehouse', table: { catalog: null, db: 'analytics', name: 'orders' }, columns: ['id', 'status'], limit: 1 }, { runId: 'scan-run-1' })).resolves.toEqual({ headers: ['id', 'status'], rows: [[10, 'paid']], totalRows: 1 });
+        await expect(connector.sampleColumn({ connectionId: 'warehouse', table: { catalog: null, db: 'analytics', 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: 'analytics', 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 analytics.orders', maxRows: 1 }, { runId: 'scan-run-1' })).resolves.toMatchObject({ 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.getTableRowCount('orders')).resolves.toBe(2);
+        await expect(connector.listSchemas()).resolves.toEqual(['analytics', 'warehouse']);
+        await expect(connector.columnStats({ connectionId: 'warehouse', table: { catalog: null, db: 'analytics', name: 'orders' }, column: 'status' }, { runId: 'scan-run-1' })).resolves.toBeNull();
+        await connector.cleanup();
+    });
+    it('adapts native MySQL snapshots to live-database introspection for local ingest', async () => {
+        const introspection = createMysqlLiveDatabaseIntrospection({
+            connections: {
+                warehouse: {
+                    driver: 'mysql',
+                    host: 'db.example.test',
+                    database: 'analytics',
+                    username: 'reader',
+                    password: 'secret', // pragma: allowlist secret
+                    readonly: true,
+                },
+            },
+            poolFactory: fakePoolFactory(),
+            now: () => new Date('2026-04-29T12:00:00.000Z'),
+        });
+        const snapshot = await introspection.extractSchema('warehouse');
+        expect(snapshot).toMatchObject({
+            connectionId: 'warehouse',
+            extractedAt: '2026-04-29T12:00:00.000Z',
+        });
+        expect(snapshot.tables.find((table) => table.name === 'customers')).toMatchObject({
+            name: 'customers',
+            catalog: null,
+            db: 'analytics',
+            columns: [
+                {
+                    name: 'id',
+                    nativeType: 'int',
+                    normalizedType: 'int',
+                    dimensionType: 'number',
+                    nullable: false,
+                    primaryKey: true,
+                    comment: 'PK',
+                },
+                {
+                    name: 'name',
+                    nativeType: 'varchar',
+                    normalizedType: 'varchar',
+                    dimensionType: 'string',
+                    nullable: false,
+                    primaryKey: false,
+                    comment: null,
+                },
+            ],
+            foreignKeys: [],
+        });
+    });
+});

package/node_modules/@ktx/connector-mysql/dist/dialect.d.ts

@@ -0,0 +1,29 @@
+import type { KtxSchemaDimensionType, KtxTableRef } from '@ktx/context/scan';
+type MysqlTableNameRef = Pick<KtxTableRef, 'name'> & Partial<Pick<KtxTableRef, 'catalog' | 'db'>>;
+export declare class KtxMysqlDialect {
+    readonly type = "mysql";
+    private readonly typeMappings;
+    quoteIdentifier(identifier: string): string;
+    formatTableName(table: MysqlTableNameRef): 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 {};