@l-v-yonsama/multi-platform-database-drivers 2.0.1 → 2.1.0

package/built/src/drivers/RDSBaseDriver.js

@@ -7,10 +7,27 @@ const helpers_1 = require("../helpers");
 const resource_1 = require("../resource");
 const utils_1 = require("../utils");
 const BaseSQLSupportDriver_1 = require("./BaseSQLSupportDriver");
+const providers_1 = require("./providers");
 class RDSBaseDriver extends BaseSQLSupportDriver_1.BaseSQLSupportDriver {
     constructor(conRes) {
         super(conRes);
     }
+    assertSessionStateAvailable(operation) {
+        if (this.exclusiveSessionStateOperation) {
+            throw new Error(`Cannot ${operation} while ${this.exclusiveSessionStateOperation} is in progress`);
+        }
+    }
+    beginExclusiveSessionStateOperation(operation) {
+        this.assertSessionStateAvailable(operation);
+        this.exclusiveSessionStateOperation = operation;
+        let released = false;
+        return () => {
+            if (!released) {
+                released = true;
+                this.exclusiveSessionStateOperation = undefined;
+            }
+        };
+    }
     getSqlLang() {
         return 'sql';
     }
@@ -69,6 +86,7 @@ class RDSBaseDriver extends BaseSQLSupportDriver_1.BaseSQLSupportDriver {
     requestSql(params) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
+            this.assertSessionStateAvailable('run a query');
             const { sql, conditions, prepare } = params;
             let qst = undefined;
             let dbTable = undefined;
@@ -114,6 +132,7 @@ class RDSBaseDriver extends BaseSQLSupportDriver_1.BaseSQLSupportDriver {
     }
     explainSql(params) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            this.assertSessionStateAvailable('retrieve an execution plan');
             const { sql, prepare } = params;
             const ast = (0, helpers_1.parseQuery)(sql);
             const dbTable = this.getDbTable(ast);
@@ -135,9 +154,591 @@ class RDSBaseDriver extends BaseSQLSupportDriver_1.BaseSQLSupportDriver {
             return rdb.build();
         });
     }
+    getRdbDashboardProvider() {
+        return undefined;
+    }
+    supportsRdbDashboard() {
+        return this.getRdbDashboardProvider() !== undefined;
+    }
+    checkRdbDashboardAvailability(target, options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const provider = this.getRdbDashboardProvider();
+            const effectiveOptions = this.normalizeRdbDashboardCallOptions(options);
+            const invalid = this.validateRdbDashboardTarget(target);
+            if (!provider) {
+                return { ok: false, message: 'RDB dashboard is not supported for this database.' };
+            }
+            if (invalid) {
+                return { ok: false, message: invalid };
+            }
+            const result = yield this.callRdbDashboardProvider(() => provider.checkCapabilities(target, effectiveOptions), effectiveOptions, 'capability check');
+            if (result.ok && result.result) {
+                const validationError = (0, providers_1.validateRdbDashboardCapabilities)(result.result, provider.providerId);
+                if (validationError) {
+                    return { ok: false, message: validationError };
+                }
+            }
+            return result;
+        });
+    }
+    resolveRdbDashboard(target, selection, options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const provider = this.getRdbDashboardProvider();
+            const effectiveOptions = this.normalizeRdbDashboardCallOptions(options);
+            const invalid = this.validateRdbDashboardTarget(target);
+            if (!provider) {
+                return { ok: false, message: 'RDB dashboard is not supported for this database.' };
+            }
+            if (invalid) {
+                return { ok: false, message: invalid };
+            }
+            if (!this.isValidRdbDashboardSelection(selection)) {
+                return { ok: false, message: 'RDB dashboard selection is invalid.' };
+            }
+            const result = yield this.callRdbDashboardProvider(() => provider.resolveDashboard(target, selection, effectiveOptions), effectiveOptions, 'definition resolution');
+            if (result.ok && result.result) {
+                const validationError = (0, providers_1.validateResolvedRdbDashboard)(result.result, provider.providerId);
+                if (validationError) {
+                    return { ok: false, message: validationError };
+                }
+            }
+            return result;
+        });
+    }
+    collectRdbDashboardSample(request, options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const provider = this.getRdbDashboardProvider();
+            const effectiveOptions = this.normalizeRdbDashboardCallOptions(options);
+            const invalid = this.validateRdbDashboardTarget(request === null || request === void 0 ? void 0 : request.target);
+            if (!provider) {
+                return { ok: false, message: 'RDB dashboard is not supported for this database.' };
+            }
+            if (invalid ||
+                !(request === null || request === void 0 ? void 0 : request.sampleSessionId) ||
+                !Number.isInteger(request.definitionVersion) ||
+                request.definitionVersion < 0 ||
+                !Number.isInteger(request.sequence) ||
+                request.sequence < 0 ||
+                !this.isValidRdbDashboardSelection(request.selection) ||
+                !Array.isArray(request.metricIds) ||
+                request.metricIds.length === 0 ||
+                request.metricIds.length > 200 ||
+                request.metricIds.some((id) => typeof id !== 'string' || !id || id.length > 128) ||
+                new Set(request.metricIds).size !== request.metricIds.length) {
+                return { ok: false, message: invalid !== null && invalid !== void 0 ? invalid : 'RDB dashboard sample request is invalid.' };
+            }
+            const result = yield this.callRdbDashboardProvider(() => provider.collectSample(request, effectiveOptions), effectiveOptions, 'sample collection');
+            if (!result.ok || !result.result) {
+                return result;
+            }
+            const batch = result.result;
+            const allowedMetrics = new Set(request.metricIds);
+            if (batch.sampleSessionId !== request.sampleSessionId ||
+                batch.definitionVersion !== request.definitionVersion ||
+                batch.sequence !== request.sequence ||
+                !Array.isArray(batch.observations) ||
+                batch.observations.some((it) => !allowedMetrics.has(it.metricId))) {
+                return { ok: false, message: 'RDB dashboard provider returned a mismatched sample.' };
+            }
+            this.enforceRdbDashboardSampleBudget(batch, 2000000);
+            return result;
+        });
+    }
+    validateRdbDashboardTarget(target) {
+        if (!(target === null || target === void 0 ? void 0 : target.resourceKey) || target.resourceKey.length > 256) {
+            return 'RDB dashboard resourceKey is required.';
+        }
+        if (!target.databaseName || target.databaseName.length > 256) {
+            return 'RDB dashboard databaseName is required.';
+        }
+        if (target.dbType !== this.conRes.dbType) {
+            return 'RDB dashboard target database type does not match this driver.';
+        }
+        return undefined;
+    }
+    isValidRdbDashboardSelection(selection) {
+        if (!selection || typeof selection !== 'object' || Array.isArray(selection)) {
+            return false;
+        }
+        const entries = Object.entries(selection);
+        return (entries.length <= 20 &&
+            entries.every(([key, value]) => key.length > 0 && key.length <= 128 && typeof value === 'string' && value.length <= 256));
+    }
+    normalizeRdbDashboardCallOptions(options) {
+        var _a;
+        return {
+            signal: options === null || options === void 0 ? void 0 : options.signal,
+            timeoutMs: Math.max(100, Math.min((_a = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _a !== void 0 ? _a : 3000, 30000)),
+        };
+    }
+    callRdbDashboardProvider(fn, options, stage) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            if ((_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+                return { ok: false, message: providers_1.RDB_DASHBOARD_CANCELLED_MESSAGE };
+            }
+            const timeoutMs = (_b = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _b !== void 0 ? _b : 3000;
+            return new Promise((resolve) => {
+                var _a;
+                let settled = false;
+                const settle = (value) => {
+                    var _a;
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    (_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.removeEventListener('abort', onAbort);
+                    resolve(value);
+                };
+                const onAbort = () => settle({ ok: false, message: providers_1.RDB_DASHBOARD_CANCELLED_MESSAGE });
+                const timer = setTimeout(() => settle({ ok: false, message: (0, providers_1.rdbDashboardTimeoutMessage)(stage, timeoutMs) }), timeoutMs);
+                (_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.addEventListener('abort', onAbort);
+                Promise.resolve()
+                    .then(fn)
+                    .then((result) => {
+                    if (!result || typeof result.ok !== 'boolean') {
+                        settle({ ok: false, message: providers_1.RDB_DASHBOARD_UNEXPECTED_ERROR_MESSAGE });
+                        return;
+                    }
+                    settle(result);
+                })
+                    .catch((error) => {
+                    console.error(`[rdbDashboard:${stage}] Provider failed:`, error);
+                    settle({ ok: false, message: providers_1.RDB_DASHBOARD_UNEXPECTED_ERROR_MESSAGE });
+                });
+            });
+        });
+    }
+    enforceRdbDashboardSampleBudget(batch, maxBytes) {
+        const size = () => Buffer.byteLength(JSON.stringify(batch), 'utf8');
+        let truncated = false;
+        while (batch.observations.length > 0 && size() > maxBytes) {
+            batch.observations.pop();
+            truncated = true;
+        }
+        if (truncated) {
+            batch.diagnostics.push({
+                sectionId: 'dashboard',
+                severity: 'warning',
+                code: 'payload-truncated',
+                message: 'Some observations were omitted to stay within the payload limit.',
+            });
+        }
+    }
+    getPerformanceTuningContextProvider() {
+        return undefined;
+    }
+    supportsGetPerformanceTuningContext() {
+        return this.getPerformanceTuningContextProvider() !== undefined;
+    }
+    checkPerformanceTuningContextAvailability(params, options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const provider = this.getPerformanceTuningContextProvider();
+            if (!provider) {
+                return {
+                    ok: false,
+                    message: 'Performance tuning context is not supported for this database.',
+                };
+            }
+            if (!params || !params.databaseName) {
+                return { ok: false, message: 'databaseName is required.' };
+            }
+            if ((_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+                return { ok: false, message: 'Performance tuning context collection was cancelled.' };
+            }
+            try {
+                return yield provider.checkCapabilities(params, options);
+            }
+            catch (e) {
+                return this.toPerformanceTuningContextErrorResult(e, 'checkCapabilities');
+            }
+        });
+    }
+    toPerformanceTuningContextErrorResult(e, stage) {
+        console.error(`[getPerformanceTuningContext:${stage}] Provider threw an unexpected error:`, e);
+        return {
+            ok: false,
+            message: 'Performance tuning context collection failed unexpectedly. Check the extension/driver logs for details.',
+        };
+    }
+    safeCollect(fn, stage) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield fn();
+            }
+            catch (e) {
+                return this.toPerformanceTuningContextErrorResult(e, stage);
+            }
+        });
+    }
+    withDeadline(fn, deadline, stage) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if ((_a = deadline.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+                return { ok: false, message: 'Performance tuning context collection was cancelled.' };
+            }
+            return new Promise((resolve) => {
+                var _a;
+                let settled = false;
+                const cleanup = () => {
+                    var _a;
+                    clearTimeout(timer);
+                    (_a = deadline.signal) === null || _a === void 0 ? void 0 : _a.removeEventListener('abort', onAbort);
+                };
+                const settle = (result) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    cleanup();
+                    resolve(result);
+                };
+                const onAbort = () => {
+                    settle({ ok: false, message: 'Performance tuning context collection was cancelled.' });
+                };
+                const timer = setTimeout(() => {
+                    settle({ ok: false, message: `${stage} timed out after ${deadline.timeoutMs}ms.` });
+                }, deadline.timeoutMs);
+                (_a = deadline.signal) === null || _a === void 0 ? void 0 : _a.addEventListener('abort', onAbort);
+                this.safeCollect(fn, stage).then(settle);
+            });
+        });
+    }
+    enforcePayloadBudget(context, maxPayloadBytes) {
+        const payloadSize = () => Buffer.byteLength(JSON.stringify(context), 'utf8');
+        if (payloadSize() <= maxPayloadBytes) {
+            return false;
+        }
+        let truncated = false;
+        while (context.tables.length > 0 && payloadSize() > maxPayloadBytes) {
+            const dropped = context.tables.pop();
+            if (!dropped) {
+                break;
+            }
+            truncated = true;
+            for (const section of [
+                'tableDefinition',
+                'tableStatistics',
+                'columnStatistics',
+                'physicalHealth',
+            ]) {
+                context.collection.unavailableSections.push({
+                    section,
+                    schemaName: dropped.schemaName,
+                    tableName: dropped.tableName,
+                    reason: 'Dropped to keep the result within maxPayloadBytes.',
+                });
+            }
+        }
+        if (payloadSize() > maxPayloadBytes && context.executionPlan.vendorPlan !== undefined) {
+            truncated = true;
+            context.executionPlan.vendorPlan = undefined;
+            context.executionPlan.normalizedPlan = undefined;
+            context.executionPlan.dominantCostPlanNode = undefined;
+            context.collection.unavailableSections.push({
+                section: 'executionPlan',
+                reason: 'The raw and normalized plan were omitted to keep the result within maxPayloadBytes.',
+            });
+        }
+        if (payloadSize() > maxPayloadBytes) {
+            context.collection.diagnostics.push({
+                code: 'COLLECTION_TRUNCATED',
+                severity: 'warning',
+                affectsCompleteness: true,
+                scope: 'collection',
+                message: `Result still exceeds maxPayloadBytes (${maxPayloadBytes} bytes) after truncation.`,
+            });
+        }
+        else if (truncated) {
+            context.collection.diagnostics.push({
+                code: 'COLLECTION_TRUNCATED',
+                severity: 'warning',
+                affectsCompleteness: true,
+                scope: 'collection',
+                message: 'Result was truncated to satisfy maxPayloadBytes.',
+            });
+        }
+        if (truncated) {
+            context.collection.status = 'partial';
+        }
+        return payloadSize() > maxPayloadBytes;
+    }
+    getPerformanceTuningContext(params, options) {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+            try {
+                this.assertSessionStateAvailable('collect a performance tuning context');
+            }
+            catch (_q) {
+                return {
+                    ok: false,
+                    message: 'An actual-plan capture is still restoring its session state. Retry shortly.',
+                };
+            }
+            const provider = this.getPerformanceTuningContextProvider();
+            if (!provider) {
+                return {
+                    ok: false,
+                    message: 'Performance tuning context is not supported for this database.',
+                };
+            }
+            const errors = (0, utils_1.validatePerformanceTuningContextParams)(params);
+            if (errors.length > 0) {
+                return { ok: false, message: errors.join(' ') };
+            }
+            if ((_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+                return { ok: false, message: 'Performance tuning context collection was cancelled.' };
+            }
+            const normalized = (0, utils_1.normalizePerformanceTuningContextParams)(params);
+            try {
+                const planResult = yield this.withDeadline(() => provider.collectExecutionPlan(params, {
+                    signal: options === null || options === void 0 ? void 0 : options.signal,
+                    timeoutMs: normalized.plan.timeoutMs,
+                }), { signal: options === null || options === void 0 ? void 0 : options.signal, timeoutMs: normalized.plan.timeoutMs }, 'collectExecutionPlan');
+                if (!planResult.ok) {
+                    return { ok: false, message: planResult.message || 'Failed to retrieve the execution plan.' };
+                }
+                const vendorPlan = planResult.result;
+                const rawPlanTableMappings = (_b = vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.planTableMappings) !== null && _b !== void 0 ? _b : [];
+                const tableAliasMap = (_c = normalized.tableAliasMap) !== null && _c !== void 0 ? _c : {};
+                const planTableMappings = rawPlanTableMappings.map((mapping) => {
+                    const hit = tableAliasMap[mapping.tableName.toLowerCase()];
+                    if (!hit || hit.tableName.toLowerCase() === mapping.tableName.toLowerCase()) {
+                        return mapping;
+                    }
+                    return Object.assign(Object.assign({}, mapping), { schemaName: hit.schemaName, tableName: hit.tableName });
+                });
+                const tableKeyOf = (t) => { var _a; return `${(_a = t.schemaName) !== null && _a !== void 0 ? _a : ''}.${t.tableName}`; };
+                const resolvedTables = new Map();
+                for (const mapping of planTableMappings) {
+                    const key = tableKeyOf(mapping);
+                    if (!resolvedTables.has(key)) {
+                        resolvedTables.set(key, { schemaName: mapping.schemaName, tableName: mapping.tableName });
+                    }
+                }
+                const isSameTable = (a, b) => {
+                    if (a.tableName.toLowerCase() !== b.tableName.toLowerCase()) {
+                        return false;
+                    }
+                    return a.schemaName && b.schemaName ? a.schemaName.toLowerCase() === b.schemaName.toLowerCase() : true;
+                };
+                for (const target of (_d = normalized.targetTables) !== null && _d !== void 0 ? _d : []) {
+                    const alreadyResolved = [...resolvedTables.values()].some((existing) => isSameTable(existing, target));
+                    if (!alreadyResolved) {
+                        const key = tableKeyOf(target);
+                        resolvedTables.set(key, { schemaName: target.schemaName, tableName: target.tableName });
+                    }
+                }
+                const unavailableSections = [];
+                const diagnostics = [...((_e = vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.diagnostics) !== null && _e !== void 0 ? _e : [])];
+                const allResolvedTables = [...resolvedTables.values()];
+                const tablesToCollect = allResolvedTables.slice(0, normalized.limits.maxTables);
+                if (allResolvedTables.length > tablesToCollect.length) {
+                    diagnostics.push({
+                        code: 'COLLECTION_TRUNCATED',
+                        severity: 'warning',
+                        affectsCompleteness: true,
+                        scope: 'collection',
+                        message: `Table collection truncated to ${normalized.limits.maxTables} of ${allResolvedTables.length} resolved tables.`,
+                    });
+                }
+                const relevantColumnsByTable = new Map();
+                for (const mapping of planTableMappings) {
+                    const key = tableKeyOf(mapping);
+                    const set = (_f = relevantColumnsByTable.get(key)) !== null && _f !== void 0 ? _f : new Set();
+                    for (const col of [
+                        ...((_g = mapping.filterColumns) !== null && _g !== void 0 ? _g : []),
+                        ...((_h = mapping.joinColumns) !== null && _h !== void 0 ? _h : []),
+                        ...((_j = mapping.groupColumns) !== null && _j !== void 0 ? _j : []),
+                        ...((_k = mapping.sortColumns) !== null && _k !== void 0 ? _k : []),
+                    ]) {
+                        set.add(col);
+                    }
+                    relevantColumnsByTable.set(key, set);
+                }
+                const collectionOptions = {
+                    signal: options === null || options === void 0 ? void 0 : options.signal,
+                    limits: normalized.limits,
+                    timeoutMs: normalized.plan.timeoutMs,
+                };
+                const deadline = { signal: options === null || options === void 0 ? void 0 : options.signal, timeoutMs: normalized.plan.timeoutMs };
+                const tables = yield Promise.all(tablesToCollect.map((_a) => tslib_1.__awaiter(this, [_a], void 0, function* ({ schemaName, tableName }) {
+                    var _b, _c;
+                    const tableTarget = { databaseName: normalized.databaseName, schemaName, tableName };
+                    const columnNames = [...((_b = relevantColumnsByTable.get(tableKeyOf(tableTarget))) !== null && _b !== void 0 ? _b : [])];
+                    const pushTableDiagnostic = (code, section, message) => {
+                        diagnostics.push({
+                            code,
+                            severity: 'warning',
+                            affectsCompleteness: true,
+                            scope: section,
+                            message,
+                            schemaName,
+                            tableName,
+                            section,
+                        });
+                    };
+                    const [definitionResult, statisticsResult, columnStatsResult, physicalHealthResult] = yield Promise.all([
+                        this.withDeadline(() => provider.collectTableDefinition(tableTarget, collectionOptions), deadline, 'collectTableDefinition'),
+                        this.withDeadline(() => provider.collectTableStatistics(tableTarget, collectionOptions), deadline, 'collectTableStatistics'),
+                        this.withDeadline(() => provider.collectColumnStatistics(Object.assign(Object.assign({}, tableTarget), { columnNames }), collectionOptions), deadline, 'collectColumnStatistics'),
+                        this.withDeadline(() => provider.collectPhysicalHealth(tableTarget, collectionOptions), deadline, 'collectPhysicalHealth'),
+                    ]);
+                    const unavailable = (section, reason) => {
+                        unavailableSections.push({ section, schemaName, tableName, reason });
+                    };
+                    let definition;
+                    if (definitionResult.ok && definitionResult.result) {
+                        definition = definitionResult.result;
+                        if (definitionResult.message) {
+                            pushTableDiagnostic('SECTION_COLLECTION_FAILED', 'tableDefinition', definitionResult.message);
+                        }
+                        const { columns, indexes } = definition;
+                        if (columns.length > normalized.limits.maxColumnsPerTable) {
+                            definition.columns = columns.slice(0, normalized.limits.maxColumnsPerTable);
+                            pushTableDiagnostic('COLLECTION_TRUNCATED', 'tableDefinition', `Columns truncated to ${normalized.limits.maxColumnsPerTable} of ${columns.length}.`);
+                        }
+                        if (indexes.length > normalized.limits.maxIndexesPerTable) {
+                            definition.indexes = indexes.slice(0, normalized.limits.maxIndexesPerTable);
+                            pushTableDiagnostic('COLLECTION_TRUNCATED', 'tableDefinition', `Indexes truncated to ${normalized.limits.maxIndexesPerTable} of ${indexes.length}.`);
+                        }
+                    }
+                    else {
+                        unavailable('tableDefinition', definitionResult.message || 'Table definition unavailable.');
+                    }
+                    let statistics;
+                    if (statisticsResult.ok && statisticsResult.result) {
+                        statistics = Object.assign(Object.assign({}, statisticsResult.result), { columns: [] });
+                        if (statisticsResult.message) {
+                            pushTableDiagnostic('SECTION_COLLECTION_FAILED', 'tableStatistics', statisticsResult.message);
+                        }
+                    }
+                    else {
+                        unavailable('tableStatistics', statisticsResult.message || 'Table statistics unavailable.');
+                    }
+                    if (columnStatsResult.ok) {
+                        statistics !== null && statistics !== void 0 ? statistics : (statistics = { columns: [] });
+                        statistics.columns = (_c = columnStatsResult.result) !== null && _c !== void 0 ? _c : [];
+                        if (columnStatsResult.message) {
+                            pushTableDiagnostic('SECTION_COLLECTION_FAILED', 'columnStatistics', columnStatsResult.message);
+                        }
+                    }
+                    else {
+                        unavailable('columnStatistics', columnStatsResult.message || 'Column statistics unavailable.');
+                    }
+                    let physicalHealth;
+                    if (physicalHealthResult.ok && physicalHealthResult.result) {
+                        physicalHealth = { provider: this.conRes.dbType, metrics: physicalHealthResult.result.metrics };
+                        if (physicalHealthResult.message) {
+                            pushTableDiagnostic('SECTION_COLLECTION_FAILED', 'physicalHealth', physicalHealthResult.message);
+                        }
+                    }
+                    else {
+                        unavailable('physicalHealth', physicalHealthResult.message || 'Physical health unavailable.');
+                    }
+                    return { schemaName, tableName, definition, statistics, physicalHealth };
+                })));
+                const tableStatsByKey = new Map();
+                for (const t of tables) {
+                    tableStatsByKey.set(tableKeyOf(t), (_l = t.statistics) === null || _l === void 0 ? void 0 : _l.estimatedRowCount);
+                }
+                const planTableMappingsWithSelectivity = planTableMappings.map((mapping) => (Object.assign(Object.assign({}, mapping), { tableAccessFraction: (0, providers_1.computeTableAccessFraction)(mapping.tableAccessRows, tableStatsByKey.get(tableKeyOf(mapping))), predicateFilterSelectivity: (0, providers_1.computePredicateFilterSelectivity)(mapping.predicateFilterInputRows, mapping.predicateFilterOutputRows) })));
+                for (const mapping of planTableMappingsWithSelectivity) {
+                    const ratio = mapping.rowEstimateRatio;
+                    if (mapping.estimatedRows === undefined ||
+                        mapping.actualRows === undefined ||
+                        ratio === undefined ||
+                        (ratio < 10 && ratio > 0.1)) {
+                        continue;
+                    }
+                    const candidatePredicateColumns = [
+                        ...((_m = mapping.filterColumns) !== null && _m !== void 0 ? _m : []),
+                        ...((_o = mapping.joinColumns) !== null && _o !== void 0 ? _o : []),
+                    ];
+                    diagnostics.push({
+                        code: 'CARDINALITY_MISESTIMATE',
+                        severity: 'info',
+                        affectsCompleteness: false,
+                        scope: 'executionPlan',
+                        message: `Actual rows (${mapping.actualRows}) differ materially from estimated rows (${mapping.estimatedRows}) for ${mapping.tableName}.`,
+                        schemaName: mapping.schemaName,
+                        tableName: mapping.tableName,
+                        cardinality: {
+                            estimatedRows: mapping.estimatedRows,
+                            actualRows: mapping.actualRows,
+                            actualToEstimatedRatio: ratio,
+                            candidatePredicateColumns: [...new Set(candidatePredicateColumns)],
+                        },
+                    });
+                }
+                let version;
+                try {
+                    version = yield this.getVersion();
+                }
+                catch (_r) {
+                    diagnostics.push({
+                        code: 'DATABASE_VERSION_UNAVAILABLE',
+                        severity: 'warning',
+                        affectsCompleteness: true,
+                        scope: 'collection',
+                        message: 'Failed to retrieve the database version.',
+                    });
+                }
+                const context = {
+                    formatVersion: 1,
+                    database: {
+                        vendor: this.conRes.dbType,
+                        version,
+                        databaseName: normalized.databaseName,
+                        schemaName: normalized.schemaName,
+                        environment: this.conRes.environment,
+                    },
+                    statement: Object.assign(Object.assign({ sql: normalized.statement.sql, source: normalized.statement.source }, (0, utils_1.classifyPerformanceTuningStatement)(normalized.statement.sql)), { bindMetadata: normalized.plan.bindMetadata }),
+                    workload: normalized.statement.statistics,
+                    executionPlan: {
+                        mode: normalized.plan.mode,
+                        format: 'json',
+                        vendorPlan: vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.raw,
+                        normalizedPlan: vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.normalizedPlan,
+                        planningTimeMs: vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.planningTimeMs,
+                        executionTimeMs: vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.executionTimeMs,
+                        actualPlan: vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.actualPlan,
+                        runtimeObservations: vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.runtimeObservations,
+                        dominantCostPlanNode: (_p = vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.dominantCostPlanNode) !== null && _p !== void 0 ? _p : (0, providers_1.findDominantCostPlanNode)(vendorPlan === null || vendorPlan === void 0 ? void 0 : vendorPlan.normalizedPlan),
+                    },
+                    tables,
+                    planTableMappings: planTableMappingsWithSelectivity,
+                    collection: {
+                        collectedAt: new Date().toISOString(),
+                        status: unavailableSections.length > 0 || diagnostics.some((d) => d.affectsCompleteness)
+                            ? 'partial'
+                            : 'complete',
+                        diagnostics,
+                        unavailableSections,
+                    },
+                };
+                const stillOverBudget = this.enforcePayloadBudget(context, normalized.limits.maxPayloadBytes);
+                if (stillOverBudget) {
+                    return {
+                        ok: false,
+                        message: `Result exceeds maxPayloadBytes (${normalized.limits.maxPayloadBytes} bytes) even after dropping every table and the execution plan.`,
+                    };
+                }
+                return { ok: true, message: '', result: context };
+            }
+            catch (e) {
+                return this.toPerformanceTuningContextErrorResult(e, 'getPerformanceTuningContext');
+            }
+        });
+    }
     explainAnalyzeSql(params) {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            this.assertSessionStateAvailable('run explain analyze');
             const { sql, prepare } = params;
+            if (!(0, utils_1.isSingleSelectStatement)(sql)) {
+                throw new Error('Explain analyze is limited to a single SELECT statement');
+            }
             const ast = (0, helpers_1.parseQuery)(sql);
             const dbTable = this.getDbTable(ast);
             if (prepare && prepare.useDatabaseName) {