@kaelio/ktx 0.5.0 → 0.6.0

package/dist/setup-databases.js

@@ -3,9 +3,13 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { delimiter, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { getDriverRegistration } from './context/connections/drivers.js';
+import { queryHistoryDialectForConnection } from './context/ingest/adapters/historic-sql/connection-dialect.js';
+import { runHistoricSqlReadinessProbe, } from './context/ingest/historic-sql-probes.js';
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete, setKtxSetupDatabaseConnectionIds } from './context/project/setup-config.js';
+import { errorMessage, flushPrefixedBufferedCommandOutput, writePrefixedLines, } from './clack.js';
 import { runKtxConnection } from './connection.js';
 import { pickDatabaseScope as defaultPickDatabaseScope, } from './database-tree-picker.js';
 import { withMultiselectNavigation, withTextInputNavigation } from './prompt-navigation.js';
@@ -14,17 +18,18 @@ import { applySetupDatabaseContextDepth } from './setup-database-context-depth.j
 import { writeProjectLocalSecretReference } from './setup-secrets.js';
 import { isDemoConnection } from './telemetry/demo-detect.js';
 import { emitTelemetryEvent } from './telemetry/index.js';
-import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
+import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
 const HISTORIC_SQL_WORK_UNIT_MAX_CONCURRENCY = 6;
+const KTX_QUICKSTART_URL = 'https://docs.kaelio.com/ktx/docs/getting-started/quickstart';
 const execFileAsync = promisify(execFileCallback);
 const DRIVER_OPTIONS = [
-    { value: 'sqlite', label: 'SQLite' },
     { value: 'postgres', label: 'PostgreSQL' },
+    { value: 'bigquery', label: 'BigQuery' },
+    { value: 'snowflake', label: 'Snowflake' },
     { value: 'mysql', label: 'MySQL' },
     { value: 'clickhouse', label: 'ClickHouse' },
     { value: 'sqlserver', label: 'SQL Server' },
-    { value: 'bigquery', label: 'BigQuery' },
-    { value: 'snowflake', label: 'Snowflake' },
+    { value: 'sqlite', label: 'SQLite' },
 ];
 const DRIVER_LABELS = Object.fromEntries(DRIVER_OPTIONS.map((option) => [option.value, option.label]));
 const HISTORIC_SQL_DIALECT_BY_DRIVER = {
@@ -151,6 +156,12 @@ function numberConfigField(connection, field) {
     const value = connection?.[field];
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
+function historicSqlConfigRecord(connection) {
+    const historicSql = connection?.historicSql;
+    return historicSql && typeof historicSql === 'object' && !Array.isArray(historicSql)
+        ? historicSql
+        : null;
+}
 function contextRecord(connection) {
     const context = connection?.context;
     return context && typeof context === 'object' && !Array.isArray(context) ? context : {};
@@ -161,205 +172,62 @@ function queryHistoryConfigRecord(connection) {
         ? queryHistory
         : null;
 }
+function stripLegacyHistoricSql(connection) {
+    const { historicSql: _historicSql, ...rest } = connection;
+    return rest;
+}
 function withQueryHistoryConfig(connection, queryHistory) {
     return {
-        ...connection,
+        ...stripLegacyHistoricSql(connection),
         context: {
             ...contextRecord(connection),
             queryHistory,
         },
     };
 }
-function historicSqlProbeFailureLines(error) {
-    if (error instanceof Error && error.name === 'HistoricSqlExtensionMissingError') {
-        return [
-            '  FAIL pg_stat_statements extension is not installed in the connection database',
-            '  Fix: Run (against this database): CREATE EXTENSION pg_stat_statements;',
-            "  Fix: Ensure shared_preload_libraries includes 'pg_stat_statements'.",
-        ];
-    }
-    if (error instanceof Error && error.name === 'HistoricSqlGrantsMissingError') {
-        const dialect = error.dialect;
-        if (dialect === 'snowflake') {
-            return [
-                '  FAIL Snowflake role cannot read SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY',
-                '  Fix: Run (as ACCOUNTADMIN): GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE <connection role>;',
-            ];
-        }
-        return [
-            '  FAIL Postgres connection role lacks pg_read_all_stats',
-            '  Fix: Run: GRANT pg_read_all_stats TO <connection role>;',
-        ];
-    }
-    if (error instanceof Error && error.name === 'HistoricSqlVersionUnsupportedError') {
-        return [`  FAIL ${error.message}`];
-    }
-    return [`  FAIL Query history probe failed: ${error instanceof Error ? error.message : String(error)}`];
-}
-async function defaultHistoricSqlProbe(input) {
-    if (input.dialect === 'postgres') {
-        return probePostgresHistoricSql(input);
-    }
-    if (input.dialect === 'snowflake') {
-        return probeSnowflakeHistoricSql(input);
-    }
-    return { ok: true, lines: [] };
-}
-async function probePostgresHistoricSql(input) {
-    const project = await loadKtxProject({ projectDir: input.projectDir });
-    const connection = project.config.connections[input.connectionId];
-    const [{ PostgresPgssReader }, { KtxPostgresHistoricSqlQueryClient }, { isKtxPostgresConnectionConfig }] = await Promise.all([
-        import('./context/ingest/adapters/historic-sql/postgres-pgss-reader.js'),
-        import('./connectors/postgres/historic-sql-query-client.js'),
-        import('./connectors/postgres/connector.js'),
-    ]);
-    const postgresConnection = connection;
-    if (!isKtxPostgresConnectionConfig(postgresConnection)) {
-        return {
-            ok: false,
-            lines: [`  FAIL Connection ${input.connectionId} is not a native Postgres connection.`],
-        };
-    }
-    const client = new KtxPostgresHistoricSqlQueryClient({
-        connectionId: input.connectionId,
-        connection: postgresConnection,
-    });
-    try {
-        const result = await new PostgresPgssReader().probe(client);
-        return {
-            ok: true,
-            lines: [
-                `  OK pg_stat_statements ready (${result.pgServerVersion})`,
-                ...result.warnings.map((warning) => `  ! ${warning}`),
-            ],
-        };
-    }
-    catch (error) {
-        return { ok: false, lines: historicSqlProbeFailureLines(error) };
-    }
-    finally {
-        await client.cleanup();
+function migrateLegacyHistoricSqlConnection(connection) {
+    const existingQueryHistory = queryHistoryConfigRecord(connection);
+    const legacy = historicSqlConfigRecord(connection);
+    if (existingQueryHistory || !legacy) {
+        return existingQueryHistory ? stripLegacyHistoricSql(connection) : connection;
     }
+    const { dialect: _dialect, ...queryHistory } = legacy;
+    return withQueryHistoryConfig(connection, queryHistory);
 }
-async function probeSnowflakeHistoricSql(input) {
-    const project = await loadKtxProject({ projectDir: input.projectDir });
-    const connection = project.config.connections[input.connectionId];
-    const [{ SnowflakeHistoricSqlQueryHistoryReader }, { KtxSnowflakeHistoricSqlQueryClient }, { isKtxSnowflakeConnectionConfig }] = await Promise.all([
-        import('./context/ingest/adapters/historic-sql/snowflake-query-history-reader.js'),
-        import('./connectors/snowflake/historic-sql-query-client.js'),
-        import('./connectors/snowflake/connector.js'),
-    ]);
-    if (!isKtxSnowflakeConnectionConfig(connection)) {
-        return {
-            ok: false,
-            lines: [`  FAIL Connection ${input.connectionId} is not a native Snowflake connection.`],
-        };
+function setupHistoricSqlProbeResult(outcome) {
+    if (!outcome) {
+        return { ok: true, lines: [] };
     }
-    const client = new KtxSnowflakeHistoricSqlQueryClient({
-        connectionId: input.connectionId,
-        connection,
-        projectDir: input.projectDir,
-    });
-    try {
-        const result = await new SnowflakeHistoricSqlQueryHistoryReader().probe(client);
+    if (outcome.ok) {
+        const { detail, warnings } = outcome.runner.formatSuccessDetail(outcome.result);
         return {
             ok: true,
-            lines: [
-                '  OK SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY accessible',
-                ...result.warnings.map((warning) => `  ! ${warning}`),
-            ],
+            lines: [`  OK ${detail}`, ...warnings.map((warning) => `  ! ${warning}`)],
         };
     }
-    catch (error) {
-        return { ok: false, lines: historicSqlProbeFailureLines(error) };
-    }
-    finally {
-        await client.cleanup();
-    }
+    const advice = outcome.runner.fixAdvice(outcome.error);
+    return {
+        ok: false,
+        lines: [`  FAIL ${advice.failHeadline}`, `  Fix: ${advice.remediation}`],
+    };
 }
 async function defaultListSchemas(projectDir, connectionId) {
     const project = await loadKtxProject({ projectDir });
     const connection = project.config.connections[connectionId];
     const driver = normalizeDriver(connection?.driver);
-    if (driver === 'postgres') {
-        const { KtxPostgresScanConnector, isKtxPostgresConnectionConfig } = await import('./connectors/postgres/connector.js');
-        ;
-        if (!isKtxPostgresConnectionConfig(connection))
-            return [];
-        const connector = new KtxPostgresScanConnector({ connectionId, connection });
-        try {
-            return await connector.listSchemas();
-        }
-        finally {
-            await connector.cleanup();
-        }
-    }
-    if (driver === 'sqlserver') {
-        const { KtxSqlServerScanConnector, isKtxSqlServerConnectionConfig } = await import('./connectors/sqlserver/connector.js');
-        ;
-        if (!isKtxSqlServerConnectionConfig(connection))
-            return [];
-        const connector = new KtxSqlServerScanConnector({ connectionId, connection });
-        try {
-            return await connector.listSchemas();
-        }
-        finally {
-            await connector.cleanup();
-        }
-    }
-    if (driver === 'mysql') {
-        const { KtxMysqlScanConnector, isKtxMysqlConnectionConfig } = await import('./connectors/mysql/connector.js');
-        ;
-        if (!isKtxMysqlConnectionConfig(connection))
-            return [];
-        const connector = new KtxMysqlScanConnector({ connectionId, connection });
-        try {
-            return await connector.listSchemas();
-        }
-        finally {
-            await connector.cleanup();
-        }
-    }
-    if (driver === 'clickhouse') {
-        const { KtxClickHouseScanConnector, isKtxClickHouseConnectionConfig } = await import('./connectors/clickhouse/connector.js');
-        ;
-        if (!isKtxClickHouseConnectionConfig(connection))
-            return [];
-        const connector = new KtxClickHouseScanConnector({ connectionId, connection });
-        try {
-            return await connector.listSchemas();
-        }
-        finally {
-            await connector.cleanup();
-        }
-    }
-    if (driver === 'bigquery') {
-        const { KtxBigQueryScanConnector, isKtxBigQueryConnectionConfig } = await import('./connectors/bigquery/connector.js');
-        ;
-        if (!isKtxBigQueryConnectionConfig(connection))
-            return [];
-        const connector = new KtxBigQueryScanConnector({ connectionId, connection });
-        try {
-            return await connector.listDatasets();
-        }
-        finally {
-            await connector.cleanup();
-        }
+    const registration = driver ? getDriverRegistration(driver) : undefined;
+    if (!registration)
+        return [];
+    const connectorModule = await registration.load();
+    if (!connectorModule.isConnectionConfig(connection))
+        return [];
+    const connector = connectorModule.createScanConnector({ connectionId, connection, projectDir });
+    try {
+        return await connector.listSchemas();
     }
-    if (driver === 'snowflake') {
-        const { KtxSnowflakeScanConnector, isKtxSnowflakeConnectionConfig } = await import('./connectors/snowflake/connector.js');
-        ;
-        if (!isKtxSnowflakeConnectionConfig(connection))
-            return [];
-        const connector = new KtxSnowflakeScanConnector({ connectionId, connection, projectDir });
-        try {
-            return await connector.listSchemas();
-        }
-        finally {
-            await connector.cleanup();
-        }
+    finally {
+        await connector.cleanup?.();
     }
-    return [];
 }
 function configuredSchemas(connection, driver) {
     if (!connection)
@@ -375,85 +243,19 @@ async function defaultListTables(projectDir, connectionId, schemasOverride) {
     const connection = project.config.connections[connectionId];
     const driver = normalizeDriver(connection?.driver);
     const schemas = schemasOverride ?? (driver ? configuredSchemas(connection, driver) : undefined);
-    if (driver === 'postgres') {
-        const { KtxPostgresScanConnector, isKtxPostgresConnectionConfig } = await import('./connectors/postgres/connector.js');
-        ;
-        if (!isKtxPostgresConnectionConfig(connection))
-            return [];
-        const connector = new KtxPostgresScanConnector({ connectionId, connection });
-        try {
-            return await connector.listTables(schemas);
-        }
-        finally {
-            await connector.cleanup();
-        }
-    }
-    if (driver === 'mysql') {
-        const { KtxMysqlScanConnector, isKtxMysqlConnectionConfig } = await import('./connectors/mysql/connector.js');
-        ;
-        if (!isKtxMysqlConnectionConfig(connection))
-            return [];
-        const connector = new KtxMysqlScanConnector({ connectionId, connection });
-        try {
-            return await connector.listTables(schemas);
-        }
-        finally {
-            await connector.cleanup();
-        }
-    }
-    if (driver === 'sqlserver') {
-        const { KtxSqlServerScanConnector, isKtxSqlServerConnectionConfig } = await import('./connectors/sqlserver/connector.js');
-        ;
-        if (!isKtxSqlServerConnectionConfig(connection))
-            return [];
-        const connector = new KtxSqlServerScanConnector({ connectionId, connection });
-        try {
-            return await connector.listTables(schemas);
-        }
-        finally {
-            await connector.cleanup();
-        }
-    }
-    if (driver === 'bigquery') {
-        const { KtxBigQueryScanConnector, isKtxBigQueryConnectionConfig } = await import('./connectors/bigquery/connector.js');
-        ;
-        if (!isKtxBigQueryConnectionConfig(connection))
-            return [];
-        const connector = new KtxBigQueryScanConnector({ connectionId, connection });
-        try {
-            return await connector.listTables(schemas);
-        }
-        finally {
-            await connector.cleanup();
-        }
-    }
-    if (driver === 'snowflake') {
-        const { KtxSnowflakeScanConnector, isKtxSnowflakeConnectionConfig } = await import('./connectors/snowflake/connector.js');
-        ;
-        if (!isKtxSnowflakeConnectionConfig(connection))
-            return [];
-        const connector = new KtxSnowflakeScanConnector({ connectionId, connection, projectDir });
-        try {
-            return await connector.listTables(schemas);
-        }
-        finally {
-            await connector.cleanup();
-        }
+    const registration = driver ? getDriverRegistration(driver) : undefined;
+    if (!registration)
+        return [];
+    const connectorModule = await registration.load();
+    if (!connectorModule.isConnectionConfig(connection))
+        return [];
+    const connector = connectorModule.createScanConnector({ connectionId, connection, projectDir });
+    try {
+        return await connector.listTables(schemas);
     }
-    if (driver === 'clickhouse') {
-        const { KtxClickHouseScanConnector, isKtxClickHouseConnectionConfig } = await import('./connectors/clickhouse/connector.js');
-        ;
-        if (!isKtxClickHouseConnectionConfig(connection))
-            return [];
-        const connector = new KtxClickHouseScanConnector({ connectionId, connection });
-        try {
-            return await connector.listTables(schemas);
-        }
-        finally {
-            await connector.cleanup();
-        }
+    finally {
+        await connector.cleanup?.();
     }
-    return [];
 }
 function existingConnectionIdsByDriver(connections, driver) {
     return Object.entries(connections)
@@ -484,6 +286,7 @@ function configuredPrimarySourcesPrompt(connectionIds) {
         message: `Databases configured: ${connectionIds.join(', ')}\nWhat would you like to do?`,
         options: [
             { value: 'continue', label: 'Continue to context sources' },
+            { value: 'skip-sources', label: 'Skip context sources' },
             { value: 'edit', label: 'Edit an existing database' },
             { value: 'add', label: 'Add another database' },
         ],
@@ -541,11 +344,10 @@ function displayFileReference(value) {
 function scriptedScopeConfigForDriver(driver, databaseSchemas) {
     if (databaseSchemas.length === 0)
         return {};
-    if (driver === 'bigquery')
-        return { dataset_ids: databaseSchemas };
-    if (driver === 'clickhouse')
-        return { databases: databaseSchemas };
-    return { schemas: databaseSchemas };
+    const registration = getDriverRegistration(driver);
+    if (!registration?.scopeConfigKey)
+        return {};
+    return { [registration.scopeConfigKey]: databaseSchemas };
 }
 function databaseNameFromLiteralUrl(url) {
     if (url.startsWith('env:') || url.startsWith('file:')) {
@@ -937,23 +739,6 @@ function createBufferedCommandIo() {
         },
     };
 }
-function flushBufferedCommandOutput(io, bufferedIo) {
-    const stdout = bufferedIo.stdoutText();
-    const stderr = bufferedIo.stderrText();
-    if (stdout.length > 0) {
-        io.stdout.write(stdout);
-    }
-    if (stderr.length > 0) {
-        io.stderr.write(stderr);
-    }
-}
-function writePrefixedLines(write, output) {
-    for (const line of output.split(/\r?\n/)) {
-        if (line.length > 0) {
-            write(`│  ${line}\n`);
-        }
-    }
-}
 function envWithCurrentNodeFirst(env = process.env) {
     return {
         ...env,
@@ -1019,10 +804,6 @@ async function defaultRebuildNativeSqlite(io) {
         return typeof error?.code === 'number' ? error.code : 1;
     }
 }
-function flushPrefixedBufferedCommandOutput(io, bufferedIo) {
-    writePrefixedLines((chunk) => io.stdout.write(chunk), bufferedIo.stdoutText());
-    writePrefixedLines((chunk) => io.stderr.write(chunk), bufferedIo.stderrText());
-}
 function nativeSqliteAbiMismatchDetail(output) {
     const mentionsBetterSqlite = /\bbetter-sqlite3\b|better_sqlite3/i.test(output);
     const mentionsAbiMismatch = /compiled against a different Node\.js version|NODE_MODULE_VERSION/i.test(output);
@@ -1096,6 +877,19 @@ async function writeConnectionConfig(input) {
         await ensureHistoricSqlIngestDefaults(input.projectDir);
     }
 }
+async function disableConnectionQueryHistory(projectDir, connectionId) {
+    const project = await loadKtxProject({ projectDir });
+    const connection = project.config.connections[connectionId];
+    if (!connection) {
+        return;
+    }
+    const existing = queryHistoryConfigRecord(connection) ?? historicSqlConfigRecord(connection) ?? {};
+    await writeConnectionConfig({
+        projectDir,
+        connectionId,
+        connection: withQueryHistoryConfig(connection, { ...existing, enabled: false }),
+    });
+}
 async function createConnectionConfigRollback(projectDir, connectionId) {
     const project = await loadKtxProject({ projectDir });
     const previousConnection = project.config.connections[connectionId];
@@ -1250,8 +1044,7 @@ async function maybeConfigureDatabaseScope(input) {
             listedSchemas = await (input.deps.listSchemas ?? defaultListSchemas)(input.projectDir, input.connectionId);
         }
         catch (error) {
-            const detail = error instanceof Error ? error.message : String(error);
-            input.io.stderr.write(`Could not discover ${spec.promptLabel.toLowerCase()} for ${input.connectionId}; ${detail}\n`);
+            writePrefixedLines((chunk) => input.io.stderr.write(chunk), `Could not discover ${spec.promptLabel.toLowerCase()} for ${input.connectionId}; ${errorMessage(error)}`);
             const typed = await promptCommaSeparatedScope({
                 prompts: input.prompts,
                 connectionId: input.connectionId,
@@ -1297,10 +1090,10 @@ async function maybeConfigureDatabaseScope(input) {
         }, input.io);
     }
     catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        input.io.stderr.write(input.forcePrompt === true
-            ? `Could not discover tables for ${input.connectionId}; edit was not saved. ${detail}\n`
-            : `Could not discover tables for ${input.connectionId}; continuing without table filter. ${detail}\n`);
+        const detail = errorMessage(error);
+        writePrefixedLines((chunk) => input.io.stderr.write(chunk), input.forcePrompt === true
+            ? `Could not discover tables for ${input.connectionId}; edit was not saved. ${detail}`
+            : `Could not discover tables for ${input.connectionId}; continuing without table filter. ${detail}`);
         return input.forcePrompt === true ? 'failed' : 'ready';
     }
     if (pickResult.kind === 'back') {
@@ -1356,35 +1149,45 @@ async function ensureHistoricSqlIngestDefaults(projectDir) {
 }
 async function markDatabasesComplete(projectDir, connectionIds) {
     const project = await loadKtxProject({ projectDir });
-    const config = setKtxSetupDatabaseConnectionIds(project.config, unique(connectionIds));
+    const config = setKtxSetupDatabaseConnectionIds({
+        ...project.config,
+        connections: Object.fromEntries(Object.entries(project.config.connections).map(([connectionId, connection]) => [
+            connectionId,
+            migrateLegacyHistoricSqlConnection(connection),
+        ])),
+    }, unique(connectionIds));
     await writeFile(project.configPath, serializeKtxProjectConfig(config), 'utf-8');
     await markKtxSetupStateStepComplete(projectDir, 'databases');
 }
 async function maybeRunHistoricSqlSetupProbe(input) {
     const project = await loadKtxProject({ projectDir: input.projectDir });
     const connection = project.config.connections[input.connectionId];
-    const queryHistory = queryHistoryConfigRecord(connection);
-    const driver = normalizeDriver(connection?.driver);
+    const queryHistory = queryHistoryConfigRecord(connection) ?? historicSqlConfigRecord(connection);
     if (queryHistory?.enabled !== true) {
-        return;
+        return true;
     }
-    const dialect = driver === 'postgres' ? 'postgres' : driver === 'snowflake' ? 'snowflake' : null;
+    if (!connection) {
+        return true;
+    }
+    const dialect = queryHistoryDialectForConnection(connection);
     if (!dialect) {
-        return;
+        return true;
     }
     input.io.stdout.write('│  Query history probe...\n');
-    const probe = input.deps.historicSqlProbe ?? defaultHistoricSqlProbe;
-    const result = await probe({
+    const probe = input.deps.historicSqlReadinessProbe ?? runHistoricSqlReadinessProbe;
+    const result = setupHistoricSqlProbeResult(await probe({
         projectDir: input.projectDir,
         connectionId: input.connectionId,
-        dialect,
-    });
+        connection,
+        env: process.env,
+    }));
     for (const line of result.lines) {
         input.io.stdout.write(`│${line}\n`);
     }
     if (!result.ok) {
         input.io.stdout.write('│  Setup written; query history will be skipped until fixed.\n');
     }
+    return result.ok;
 }
 async function applyHistoricSqlConfigToExistingConnection(input) {
     if (input.args.inputMode === 'disabled' &&
@@ -1450,8 +1253,8 @@ async function validateAndScanConnection(input) {
     const testIo = createBufferedCommandIo();
     const testCode = await testConnection(input.projectDir, input.connectionId, testIo);
     if (testCode !== 0) {
-        flushBufferedCommandOutput(input.io, testIo);
-        input.io.stderr.write(`Connection test failed for ${input.connectionId}.\n`);
+        flushPrefixedBufferedCommandOutput(input.io, testIo);
+        writePrefixedLines((chunk) => input.io.stderr.write(chunk), `Connection test failed for ${input.connectionId}.`);
         return 'failed';
     }
     const testOutput = testIo.stdoutText();
@@ -1463,7 +1266,7 @@ async function validateAndScanConnection(input) {
     if (scopeStatus !== 'ready') {
         return scopeStatus;
     }
-    await maybeRunHistoricSqlSetupProbe({
+    const queryHistoryAvailable = await maybeRunHistoricSqlSetupProbe({
         projectDir: input.projectDir,
         connectionId: input.connectionId,
         io: input.io,
@@ -1509,7 +1312,7 @@ async function validateAndScanConnection(input) {
             ].join('\n'));
         }
         if (scanCode !== 0) {
-            return 'failed';
+            return queryHistoryAvailable ? 'failed' : 'failed-query-history-unavailable';
         }
     }
     const scanOutput = scanIo.stdoutText();
@@ -1531,6 +1334,7 @@ async function chooseDrivers(args, io, prompts, options) {
         return 'missing-input';
     }
     const initialValues = unique(options?.initialDrivers ?? []);
+    createKtxSetupUiAdapter().note(`Get demo credentials from the Quickstart: ${KTX_QUICKSTART_URL}`, '🎁 Need a warehouse to play with?', io);
     const choices = await prompts.multiselect({
         message: withMultiselectNavigation('Which databases should KTX connect to?'),
         options: [...DRIVER_OPTIONS],
@@ -1625,7 +1429,7 @@ async function runPrimarySourceFullEdit(input) {
     const existing = project.config.connections[input.connectionId];
     const driver = normalizeDriver(existing?.driver);
     if (!existing || !driver) {
-        input.io.stderr.write(`Connection "${input.connectionId}" is not a configured database.\n`);
+        writePrefixedLines((chunk) => input.io.stderr.write(chunk), `Connection "${input.connectionId}" is not a configured database.`);
         return 'failed';
     }
     const rollback = await createConnectionConfigRollback(input.projectDir, input.connectionId);
@@ -1675,7 +1479,7 @@ async function runPrimarySourceFullEdit(input) {
     });
     if (validated !== 'ready') {
         await rollback();
-        return validated;
+        return validated === 'failed-query-history-unavailable' ? 'failed' : validated;
     }
     return 'ready';
 }
@@ -1728,6 +1532,15 @@ export async function runKtxSetupDatabasesStep(args, io, deps = {}) {
                 await markDatabasesComplete(args.projectDir, selectedConnectionIds);
                 return { status: 'ready', projectDir: args.projectDir, connectionIds: selectedConnectionIds };
             }
+            if (action === 'skip-sources') {
+                await markDatabasesComplete(args.projectDir, selectedConnectionIds);
+                return {
+                    status: 'ready',
+                    projectDir: args.projectDir,
+                    connectionIds: selectedConnectionIds,
+                    skipSources: true,
+                };
+            }
             if (action === 'edit') {
                 const connectionId = await choosePrimarySourceToEdit({
                     projectDir: args.projectDir,
@@ -1791,7 +1604,7 @@ export async function runKtxSetupDatabasesStep(args, io, deps = {}) {
                 });
             }
             catch (error) {
-                io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+                writePrefixedLines((chunk) => io.stderr.write(chunk), errorMessage(error));
                 return { status: 'failed', projectDir: args.projectDir };
             }
             if (connectionChoice === 'back') {
@@ -1946,14 +1759,18 @@ export async function runKtxSetupDatabasesStep(args, io, deps = {}) {
                 }
                 if (args.inputMode === 'disabled')
                     return { status: 'failed', projectDir: args.projectDir };
+                const failureOptions = [
+                    { value: 'retry', label: 'Retry connection test' },
+                    { value: 're-enter', label: 'Re-enter connection details' },
+                    ...(setupStatus === 'failed-query-history-unavailable'
+                        ? [{ value: 'disable-query-history', label: 'Disable query history and retry' }]
+                        : []),
+                    { value: 'skip', label: 'Skip this database' },
+                    { value: 'back', label: 'Back' },
+                ];
                 const action = await prompts.select({
                     message: `Database setup failed for ${connectionChoice.connectionId}`,
-                    options: [
-                        { value: 'retry', label: 'Retry connection test' },
-                        { value: 're-enter', label: 'Re-enter connection details' },
-                        { value: 'skip', label: 'Skip this database' },
-                        { value: 'back', label: 'Back' },
-                    ],
+                    options: failureOptions,
                 });
                 if (action === 'back') {
                     if (!canReturnToDriverSelection)
@@ -1975,6 +1792,17 @@ export async function runKtxSetupDatabasesStep(args, io, deps = {}) {
                         prompts,
                     });
                 }
+                else if (action === 'disable-query-history') {
+                    await disableConnectionQueryHistory(args.projectDir, connectionChoice.connectionId);
+                    setupStatus = await validateAndScanConnection({
+                        projectDir: args.projectDir,
+                        connectionId: connectionChoice.connectionId,
+                        io,
+                        deps,
+                        args,
+                        prompts,
+                    });
+                }
                 else if (action === 're-enter') {
                     const connection = await buildConnectionConfig({
                         driver,