feat(connectors): generalize readiness and constraint handling (#212)

* feat(connectors): add postgres maxConnections

* feat(connectors): add mysql maxConnections

* feat(connectors): add sqlserver maxConnections

* feat(connectors): rename snowflake pool config

* docs: document connector maxConnections

* feat(scan): add constraint discovery warning helper

* feat(scan): carry structural warnings through reports

* feat(postgres): soft-fail denied constraint discovery

* feat(mysql): soft-fail denied constraint discovery

* feat(sqlserver): soft-fail denied constraint discovery

* feat(bigquery): soft-fail denied primary key discovery

* feat(snowflake): report denied primary key discovery

* test(scan): verify constraint discovery warnings

* feat(historic-sql): use shared readiness probes

* docs: document query history readiness probes

* test(historic-sql): verify readiness probe registry

* test(ingest): account for live database warnings artifact

* Add skip option for agent setup

packages/cli/src/connectors/sqlserver/connector.ts

@@ -1,6 +1,27 @@
 import { assertReadOnlySql } from '../../context/connections/read-only-sql.js';
-import { createKtxConnectorCapabilities, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaColumn, type KtxSchemaForeignKey, type KtxSchemaSnapshot, type KtxSchemaTable, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
+import {
+  createKtxConnectorCapabilities,
+  type KtxColumnSampleInput,
+  type KtxColumnSampleResult,
+  type KtxColumnStatsInput,
+  type KtxColumnStatsResult,
+  type KtxQueryResult,
+  type KtxReadOnlyQueryInput,
+  type KtxScanConnector,
+  type KtxScanContext,
+  type KtxScanInput,
+  type KtxScanWarning,
+  type KtxSchemaColumn,
+  type KtxSchemaForeignKey,
+  type KtxSchemaSnapshot,
+  type KtxSchemaTable,
+  type KtxTableListEntry,
+  type KtxTableRef,
+  type KtxTableSampleInput,
+  type KtxTableSampleResult,
+} from '../../context/scan/types.js';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
@@ -19,6 +40,7 @@ export interface KtxSqlServerConnectionConfig {
   schema?: string;
   schemas?: string[];
   trustServerCertificate?: boolean;
+  maxConnections?: number;
   [key: string]: unknown;
 }
 
@@ -197,6 +219,23 @@ function maybeNumber(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
 
+function positiveIntegerConfigValue(input: {
+  connection: KtxSqlServerConnectionConfig;
+  key: keyof KtxSqlServerConnectionConfig;
+  connectionId: string;
+  defaultValue: number;
+}): number {
+  const value = input.connection[input.key];
+  if (value === undefined) {
+    return input.defaultValue;
+  }
+  const numberValue = Number(value);
+  if (!Number.isInteger(numberValue) || numberValue < 1) {
+    throw new Error(`connections.${input.connectionId}.${String(input.key)} must be a positive integer`);
+  }
+  return numberValue;
+}
+
 function schemaNames(connection: KtxSqlServerConnectionConfig, env: NodeJS.ProcessEnv): string[] {
   if (Array.isArray(connection.schemas) && connection.schemas.length > 0) {
     return connection.schemas.filter((schema) => schema.trim().length > 0).map((schema) => resolveStringReference(schema, env));
@@ -219,6 +258,14 @@ function firstNumber(value: unknown): number | null {
   return Number.isFinite(numberValue) ? numberValue : null;
 }
 
+function isDeniedError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  const number = (error as { number?: unknown }).number;
+  return number === 229 || number === 230 || number === 297;
+}
+
 function limitSqlForSqlServerExecution(sqlText: string, maxRows: number | undefined): string {
   const trimmed = assertReadOnlySql(sqlText).replace(/;+\s*$/, '');
   if (!maxRows) {
@@ -254,6 +301,12 @@ export function sqlServerConnectionPoolConfigFromConfig(input: {
   const server = stringConfigValue(merged, 'host', env);
   const database = stringConfigValue(merged, 'database', env);
   const user = stringConfigValue(merged, 'username', env) ?? stringConfigValue(merged, 'user', env);
+  const maxConnections = positiveIntegerConfigValue({
+    connection: merged,
+    key: 'maxConnections',
+    connectionId: input.connectionId,
+    defaultValue: 10,
+  });
 
   if (!server) {
     throw new Error(`Native SQL Server connector requires connections.${input.connectionId}.host or url`);
@@ -272,7 +325,7 @@ export function sqlServerConnectionPoolConfigFromConfig(input: {
     user,
     password: stringConfigValue(merged, 'password', env),
     options: { encrypt: true, trustServerCertificate: merged.trustServerCertificate ?? true },
-    pool: { max: 10, min: 0, idleTimeoutMillis: 30000 },
+    pool: { max: maxConnections, min: 0, idleTimeoutMillis: 30000 },
   };
 }
 
@@ -328,11 +381,12 @@ export class KtxSqlServerScanConnector implements KtxScanConnector {
   async introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot> {
     this.assertConnection(input.connectionId);
     const tables: KtxSchemaTable[] = [];
+    const snapshotWarnings: KtxScanWarning[] = [];
     for (const schemaName of this.schemas) {
       const scopedNames = input.tableScope
         ? scopedTableNames(input.tableScope, { catalog: this.poolConfig.database, db: schemaName })
         : null;
-      tables.push(...(await this.introspectSchema(schemaName, scopedNames)));
+      tables.push(...(await this.introspectSchema(schemaName, scopedNames, snapshotWarnings)));
     }
     return {
       connectionId: this.connectionId,
@@ -347,6 +401,7 @@ export class KtxSqlServerScanConnector implements KtxScanConnector {
         total_columns: tables.reduce((sum, table) => sum + table.columns.length, 0),
       },
       tables,
+      warnings: snapshotWarnings,
     };
   }
 
@@ -479,7 +534,11 @@ export class KtxSqlServerScanConnector implements KtxScanConnector {
     }
   }
 
-  private async introspectSchema(schemaName: string, scopedNames: readonly string[] | null): Promise<KtxSchemaTable[]> {
+  private async introspectSchema(
+    schemaName: string,
+    scopedNames: readonly string[] | null,
+    snapshotWarnings: KtxScanWarning[],
+  ): Promise<KtxSchemaTable[]> {
     if (scopedNames && scopedNames.length === 0) return [];
     const tableScope = tableScopeSql(scopedNames, 'TABLE_NAME');
     const tables = await this.queryRaw<{ table_name: string; table_type: string }>(
@@ -510,8 +569,22 @@ export class KtxSqlServerScanConnector implements KtxScanConnector {
     );
     const tableComments = await this.tableComments(schemaName, scopedNames);
     const columnComments = await this.columnComments(schemaName, scopedNames);
-    const primaryKeys = await this.primaryKeys(schemaName, scopedNames);
-    const foreignKeys = await this.foreignKeys(schemaName, scopedNames);
+    const primaryKeysResult = await tryConstraintQuery(
+      { schema: schemaName, kind: 'primary_key', isDeniedError },
+      () => this.primaryKeys(schemaName, scopedNames),
+    );
+    const foreignKeysResult = await tryConstraintQuery(
+      { schema: schemaName, kind: 'foreign_key', isDeniedError },
+      () => this.foreignKeys(schemaName, scopedNames),
+    );
+    const primaryKeys = primaryKeysResult.ok ? primaryKeysResult.value : new Map<string, Set<string>>();
+    const foreignKeys = foreignKeysResult.ok ? foreignKeysResult.value : [];
+    if (!primaryKeysResult.ok) {
+      snapshotWarnings.push(primaryKeysResult.warning);
+    }
+    if (!foreignKeysResult.ok) {
+      snapshotWarnings.push(foreignKeysResult.warning);
+    }
     const rowCounts = await this.rowCounts(schemaName, scopedNames);
     const columnsByTable = groupByTable(columns);
     const foreignKeysByTable = groupByTable(foreignKeys);