taurusdb-core 0.1.0

package/dist/engine.js

@@ -0,0 +1,240 @@
+import { createSqlProfileLoader, } from "./auth/sql-profile-loader.js";
+import { createSecretResolver, } from "./auth/secret-resolver.js";
+import { createCapabilityProbe, } from "./capability/probe.js";
+import { getConfig } from "./config/index.js";
+import { createDatasourceResolver } from "./context/datasource-resolver.js";
+import { createConnectionPoolManager, } from "./executor/connection-pool.js";
+import { createMySqlDriverAdapter } from "./executor/adapters/mysql.js";
+import { createSqlExecutor, } from "./executor/sql-executor.js";
+import { createConfirmationStore, } from "./safety/confirmation-store.js";
+import { createGuardrail, } from "./safety/guardrail.js";
+import { createSchemaIntrospector, } from "./schema/introspector.js";
+import { createMySqlSchemaAdapter } from "./schema/adapters/mysql.js";
+import { createSlowSqlSource, } from "./diagnostics/slow-sql-source.js";
+import { createMetricsSource, } from "./diagnostics/metrics-source.js";
+import { findLatestDeadlock, findMetadataLockWaits, findStatementDigestCandidatesForSqlHints, findStatementDigestSample, findStatementDigestSampleForSql, findStatementWaitEvents, findStorageStatementDigests, findTableStorageStats, findTopStatementDigests, isPerformanceSchemaEnabled, showLockWaits, showProcesslist, } from "./engine/data-access.js";
+import { diagnoseConnectionSpike, diagnoseDbHotspot, diagnoseLockContention, diagnoseServiceLatency, diagnoseSlowQuery, diagnoseStoragePressure, findTopSlowSql, } from "./engine/diagnostics.js";
+import { cancelQuery, close, executeMutation, executeReadonly, explain, explainEnhanced, flashbackQuery, getQueryStatus, handleConfirmation, issueConfirmation, listRecycleBin, restoreRecycleBinTable, validateConfirmation, } from "./engine/runtime.js";
+function toDataSourceInfo(profile, defaultDatasource) {
+    return {
+        name: profile.name,
+        engine: profile.engine,
+        host: profile.host,
+        port: profile.port,
+        database: profile.database,
+        hasMutationUser: profile.mutationUser !== undefined,
+        poolSize: profile.poolSize,
+        isDefault: profile.name === defaultDatasource,
+    };
+}
+export class TaurusDBEngine {
+    config;
+    profileLoader;
+    secretResolver;
+    datasourceResolver;
+    connectionPool;
+    schemaIntrospector;
+    guardrail;
+    executor;
+    confirmationStore;
+    capabilityProbe;
+    slowSqlSource;
+    metricsSource;
+    constructor(deps) {
+        this.config = deps.config;
+        this.profileLoader = deps.profileLoader;
+        this.secretResolver = deps.secretResolver;
+        this.datasourceResolver = deps.datasourceResolver;
+        this.connectionPool = deps.connectionPool;
+        this.schemaIntrospector = deps.schemaIntrospector;
+        this.guardrail = deps.guardrail;
+        this.executor = deps.executor;
+        this.confirmationStore = deps.confirmationStore;
+        this.capabilityProbe = deps.capabilityProbe;
+        this.slowSqlSource = deps.slowSqlSource;
+        this.metricsSource = deps.metricsSource;
+    }
+    static async create(options = {}) {
+        const config = options.config ?? getConfig();
+        const profileLoader = options.profileLoader ?? createSqlProfileLoader({ config });
+        const secretResolver = options.secretResolver ?? createSecretResolver();
+        const datasourceResolver = options.datasourceResolver ??
+            createDatasourceResolver({
+                config,
+                profileLoader,
+            });
+        const connectionPool = options.connectionPool ??
+            createConnectionPoolManager({
+                config,
+                profileLoader,
+                secretResolver,
+                adapters: {
+                    mysql: createMySqlDriverAdapter(),
+                },
+            });
+        const schemaIntrospector = options.schemaIntrospector ??
+            createSchemaIntrospector({
+                adapters: {
+                    mysql: createMySqlSchemaAdapter({ connectionPool }),
+                },
+            });
+        const executor = options.executor ??
+            createSqlExecutor({
+                connectionPool,
+            });
+        const guardrail = options.guardrail ?? createGuardrail();
+        const confirmationStore = options.confirmationStore ?? createConfirmationStore();
+        const capabilityProbe = options.capabilityProbe ??
+            createCapabilityProbe({
+                connectionPool,
+            });
+        const slowSqlSource = options.slowSqlSource ?? createSlowSqlSource(config);
+        const metricsSource = options.metricsSource ?? createMetricsSource(config);
+        return new TaurusDBEngine({
+            config,
+            profileLoader,
+            secretResolver,
+            datasourceResolver,
+            connectionPool,
+            schemaIntrospector,
+            guardrail,
+            executor,
+            confirmationStore,
+            capabilityProbe,
+            slowSqlSource,
+            metricsSource,
+        });
+    }
+    async listDataSources() {
+        const [profiles, defaultDatasource] = await Promise.all([
+            this.profileLoader.load(),
+            this.profileLoader.getDefault(),
+        ]);
+        return [...profiles.values()]
+            .map((profile) => toDataSourceInfo(profile, defaultDatasource))
+            .sort((left, right) => left.name.localeCompare(right.name));
+    }
+    async getDefaultDataSource() {
+        return this.profileLoader.getDefault();
+    }
+    async resolveContext(input, taskId) {
+        return this.datasourceResolver.resolve(input, taskId);
+    }
+    async listDatabases(ctx) {
+        return this.schemaIntrospector.listDatabases(ctx);
+    }
+    async listTables(ctx, database) {
+        return this.schemaIntrospector.listTables(ctx, database);
+    }
+    async describeTable(ctx, database, table) {
+        return this.schemaIntrospector.describeTable(ctx, database, table);
+    }
+    async inspectSql(input) {
+        return this.guardrail.inspect(input);
+    }
+    async probeCapabilities(ctx) {
+        return this.capabilityProbe.probe(ctx);
+    }
+    async getKernelInfo(ctx) {
+        return this.capabilityProbe.getKernelInfo(ctx);
+    }
+    async listFeatures(ctx) {
+        return this.capabilityProbe.listFeatures(ctx);
+    }
+    async showProcesslist(input, ctx) {
+        return showProcesslist(this, input, ctx);
+    }
+    async showLockWaits(input, ctx) {
+        return showLockWaits(this, input, ctx);
+    }
+    async findMetadataLockWaits(input, ctx) {
+        return findMetadataLockWaits(this, input, ctx);
+    }
+    async findLatestDeadlock(ctx) {
+        return findLatestDeadlock(this, ctx);
+    }
+    async findStatementDigestSample(digestText, ctx) {
+        return findStatementDigestSample(this, digestText, ctx);
+    }
+    async findStatementDigestSampleForSql(sql, ctx) {
+        return findStatementDigestSampleForSql(this, sql, ctx);
+    }
+    async findStatementDigestCandidatesForSqlHints(sqlText, ctx) {
+        return findStatementDigestCandidatesForSqlHints(this, sqlText, ctx);
+    }
+    async findTopStatementDigests(input, ctx) {
+        return findTopStatementDigests(this, input, ctx);
+    }
+    async isPerformanceSchemaEnabled(ctx) {
+        return isPerformanceSchemaEnabled(this, ctx);
+    }
+    async findStorageStatementDigests(input, ctx) {
+        return findStorageStatementDigests(this, input, ctx);
+    }
+    async findStatementWaitEvents(digestText, ctx) {
+        return findStatementWaitEvents(this, digestText, ctx);
+    }
+    async findTableStorageStats(input, ctx) {
+        return findTableStorageStats(this, input, ctx);
+    }
+    async diagnoseSlowQuery(input, ctx) {
+        return diagnoseSlowQuery(this, input, ctx);
+    }
+    async diagnoseServiceLatency(input, ctx) {
+        return diagnoseServiceLatency(this, input, ctx);
+    }
+    async diagnoseDbHotspot(input, ctx) {
+        return diagnoseDbHotspot(this, input, ctx);
+    }
+    async findTopSlowSql(input, ctx) {
+        return findTopSlowSql(this, input, ctx);
+    }
+    async diagnoseConnectionSpike(input, ctx) {
+        return diagnoseConnectionSpike(this, input, ctx);
+    }
+    async diagnoseLockContention(input, ctx) {
+        return diagnoseLockContention(this, input, ctx);
+    }
+    async diagnoseStoragePressure(input, ctx) {
+        return diagnoseStoragePressure(this, input, ctx);
+    }
+    async explain(sql, ctx) {
+        return explain(this, sql, ctx);
+    }
+    async explainEnhanced(sql, ctx) {
+        return explainEnhanced(this, sql, ctx);
+    }
+    async executeReadonly(sql, ctx, opts) {
+        return executeReadonly(this, sql, ctx, opts);
+    }
+    async executeMutation(sql, ctx, opts) {
+        return executeMutation(this, sql, ctx, opts);
+    }
+    async flashbackQuery(input, ctx, opts) {
+        return flashbackQuery(this, input, ctx, opts);
+    }
+    async listRecycleBin(ctx, opts) {
+        return listRecycleBin(this, ctx, opts);
+    }
+    async restoreRecycleBinTable(input, ctx, opts) {
+        return restoreRecycleBinTable(this, input, ctx, opts);
+    }
+    async getQueryStatus(queryId) {
+        return getQueryStatus(this, queryId);
+    }
+    async cancelQuery(queryId) {
+        return cancelQuery(this, queryId);
+    }
+    async issueConfirmation(input) {
+        return issueConfirmation(this, input);
+    }
+    async validateConfirmation(token, sql, ctx) {
+        return validateConfirmation(this, token, sql, ctx);
+    }
+    async handleConfirmation(decision, ctx) {
+        return handleConfirmation(this, decision, ctx);
+    }
+    async close() {
+        return close(this);
+    }
+}

package/dist/executor/adapters/mysql.d.ts

@@ -0,0 +1,2 @@
+import type { DriverAdapter } from "../connection-pool.js";
+export declare function createMySqlDriverAdapter(): DriverAdapter;

package/dist/executor/adapters/mysql.js

@@ -0,0 +1,114 @@
+import mysql from "mysql2/promise";
+function normalizeRows(value) {
+    return Array.isArray(value) ? value : [];
+}
+function normalizeResult(rows, fields) {
+    const normalizedRows = normalizeRows(rows);
+    if (Array.isArray(rows)) {
+        return {
+            rows: normalizedRows,
+            rowCount: normalizedRows.length,
+            fields: fields?.map((field) => ({
+                name: field.name,
+                type: field.columnType !== undefined ? String(field.columnType) : undefined,
+            })),
+            raw: rows,
+        };
+    }
+    if (rows && typeof rows === "object") {
+        const header = rows;
+        return {
+            rows: [],
+            rowCount: header.affectedRows ?? 0,
+            affectedRows: header.affectedRows ?? 0,
+            raw: rows,
+        };
+    }
+    return {
+        rows: [],
+        rowCount: 0,
+        raw: rows,
+    };
+}
+function toSslOptions(tls) {
+    if (!tls?.enabled) {
+        return undefined;
+    }
+    return {
+        rejectUnauthorized: tls.rejectUnauthorized,
+        servername: tls.servername,
+        ca: tls.ca,
+        cert: tls.cert,
+        key: tls.key,
+    };
+}
+class MySqlDriverSession {
+    connection;
+    state;
+    constructor(connection, state) {
+        this.connection = connection;
+        this.state = state;
+    }
+    async execute(sql, options = {}) {
+        const [rows, fields] = await this.connection.query({
+            sql,
+            timeout: options.timeoutMs,
+            rowsAsArray: false,
+        });
+        return normalizeResult(rows, fields);
+    }
+    async cancel() {
+        if (this.state.destroyed) {
+            return;
+        }
+        this.state.destroyed = true;
+        this.connection.destroy();
+    }
+    async release() {
+        if (this.state.released) {
+            return;
+        }
+        this.state.released = true;
+        if (this.state.destroyed) {
+            return;
+        }
+        this.connection.release();
+    }
+}
+class MySqlDriverPool {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async acquire() {
+        const connection = await this.pool.getConnection();
+        return new MySqlDriverSession(connection, {
+            destroyed: false,
+            released: false,
+        });
+    }
+    async close() {
+        await this.pool.end();
+    }
+}
+export function createMySqlDriverAdapter() {
+    return {
+        async createPool(input) {
+            const pool = mysql.createPool({
+                host: input.host,
+                port: input.port,
+                database: input.database,
+                user: input.username,
+                password: input.password,
+                dateStrings: true,
+                connectionLimit: input.poolSize ?? 4,
+                waitForConnections: true,
+                queueLimit: 0,
+                enableKeepAlive: true,
+                multipleStatements: false,
+                ssl: toSslOptions(input.tls),
+            });
+            return new MySqlDriverPool(pool);
+        },
+    };
+}

package/dist/executor/connection-pool.d.ts

@@ -0,0 +1,105 @@
+import type { Config } from "../config/index.js";
+import type { DatabaseEngine, ProfileLoader } from "../auth/sql-profile-loader.js";
+import type { SecretResolver } from "../auth/secret-resolver.js";
+export type PoolMode = "ro" | "rw";
+export interface ExecOptions {
+    timeoutMs?: number;
+}
+export interface RawResult {
+    rows?: unknown[];
+    rowCount?: number;
+    affectedRows?: number;
+    fields?: Array<{
+        name: string;
+        type?: string;
+    }>;
+    raw?: unknown;
+}
+export interface Session {
+    id: string;
+    datasource: string;
+    mode: PoolMode;
+    execute(sql: string, options?: ExecOptions): Promise<RawResult>;
+    cancel(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface ModeHealth {
+    mode: PoolMode;
+    status: "ok" | "error" | "skipped";
+    message?: string;
+}
+export interface PoolHealth {
+    datasource: string;
+    checkedAt: string;
+    modes: ModeHealth[];
+}
+export interface ConnectionPool {
+    acquire(datasource: string, mode: PoolMode, opts?: {
+        allowWithoutGlobalMutations?: boolean;
+        allowReadonlyFallbackForMutations?: boolean;
+    }): Promise<Session>;
+    release(session: Session): Promise<void>;
+    healthCheck(datasource: string): Promise<PoolHealth>;
+    close(): Promise<void>;
+}
+export interface DriverSession {
+    execute(sql: string, options?: ExecOptions): Promise<RawResult>;
+    cancel(): Promise<void>;
+    release(): Promise<void>;
+}
+export interface DriverPool {
+    acquire(): Promise<DriverSession>;
+    close(): Promise<void>;
+}
+export interface DriverPoolCreateInput {
+    datasource: string;
+    mode: PoolMode;
+    engine: DatabaseEngine;
+    host: string;
+    port: number;
+    database?: string;
+    username: string;
+    password: string;
+    poolSize?: number;
+    tls?: {
+        enabled?: boolean;
+        rejectUnauthorized?: boolean;
+        servername?: string;
+        ca?: string;
+        cert?: string;
+        key?: string;
+    };
+}
+export interface DriverAdapter {
+    createPool(input: DriverPoolCreateInput): Promise<DriverPool>;
+}
+export type ConnectionPoolManagerOptions = {
+    config: Config;
+    profileLoader: ProfileLoader;
+    secretResolver: SecretResolver;
+    adapters: Partial<Record<DatabaseEngine, DriverAdapter>>;
+};
+export declare class ConnectionPoolError extends Error {
+    readonly code = "CONNECTION_FAILED";
+    constructor(message: string, cause?: unknown);
+}
+export declare class ConnectionPoolManager implements ConnectionPool {
+    private readonly config;
+    private readonly profileLoader;
+    private readonly secretResolver;
+    private readonly adapters;
+    private readonly pools;
+    private readonly activeSessions;
+    constructor(options: ConnectionPoolManagerOptions);
+    acquire(datasource: string, mode: PoolMode, opts?: {
+        allowWithoutGlobalMutations?: boolean;
+        allowReadonlyFallbackForMutations?: boolean;
+    }): Promise<Session>;
+    release(session: Session): Promise<void>;
+    healthCheck(datasource: string): Promise<PoolHealth>;
+    close(): Promise<void>;
+    private healthCheckMode;
+    private getOrCreatePool;
+    private createPool;
+}
+export declare function createConnectionPoolManager(options: ConnectionPoolManagerOptions): ConnectionPoolManager;

package/dist/executor/connection-pool.js

@@ -0,0 +1,236 @@
+import { ulid } from "ulid";
+export class ConnectionPoolError extends Error {
+    code = "CONNECTION_FAILED";
+    constructor(message, cause) {
+        super(message);
+        this.name = "ConnectionPoolError";
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+function poolKey(datasource, mode) {
+    return `${datasource}:${mode}`;
+}
+async function resolveTls(tls, secretResolver) {
+    if (!tls) {
+        return undefined;
+    }
+    const resolved = {
+        enabled: tls.enabled,
+        rejectUnauthorized: tls.rejectUnauthorized,
+        servername: tls.servername,
+    };
+    if (tls.ca) {
+        resolved.ca = await secretResolver.resolve(tls.ca);
+    }
+    if (tls.cert) {
+        resolved.cert = await secretResolver.resolve(tls.cert);
+    }
+    if (tls.key) {
+        resolved.key = await secretResolver.resolve(tls.key);
+    }
+    return resolved;
+}
+function ensureMutationAllowed(config) {
+    if (!config.enableMutations) {
+        throw new ConnectionPoolError("Mutation mode is disabled by configuration.");
+    }
+}
+function selectCredential(profile, mode, opts = {}) {
+    if (mode === "ro") {
+        return profile.readonlyUser;
+    }
+    if (!profile.mutationUser) {
+        if (opts.allowReadonlyFallbackForMutations) {
+            return profile.readonlyUser;
+        }
+        throw new ConnectionPoolError(`Mutation user is not configured for datasource "${profile.name}".`);
+    }
+    return profile.mutationUser;
+}
+async function resolveCredentialValue(ref, secretResolver, context) {
+    try {
+        return await secretResolver.resolve(ref);
+    }
+    catch (error) {
+        throw new ConnectionPoolError(`Failed to resolve credential for ${context}.`, error);
+    }
+}
+export class ConnectionPoolManager {
+    config;
+    profileLoader;
+    secretResolver;
+    adapters;
+    pools = new Map();
+    activeSessions = new Map();
+    constructor(options) {
+        this.config = options.config;
+        this.profileLoader = options.profileLoader;
+        this.secretResolver = options.secretResolver;
+        this.adapters = options.adapters;
+    }
+    async acquire(datasource, mode, opts = {}) {
+        const profile = await this.profileLoader.get(datasource);
+        if (!profile) {
+            throw new ConnectionPoolError(`Datasource profile not found: "${datasource}".`);
+        }
+        if (mode === "rw" && !opts.allowWithoutGlobalMutations) {
+            ensureMutationAllowed(this.config);
+        }
+        const entry = await this.getOrCreatePool(profile, mode, opts);
+        let driverSession;
+        try {
+            driverSession = await entry.pool.acquire();
+        }
+        catch (error) {
+            throw new ConnectionPoolError(`Failed to acquire database session for datasource "${datasource}".`, error);
+        }
+        const sessionId = `sess_${ulid().toLowerCase()}`;
+        const active = {
+            id: sessionId,
+            entryKey: entry.key,
+            driverSession,
+            datasource,
+            mode,
+        };
+        this.activeSessions.set(sessionId, active);
+        const self = this;
+        return {
+            id: sessionId,
+            datasource,
+            mode,
+            async execute(sql, options) {
+                return active.driverSession.execute(sql, options);
+            },
+            async cancel() {
+                await active.driverSession.cancel();
+            },
+            async close() {
+                await self.release({ id: sessionId });
+            },
+        };
+    }
+    async release(session) {
+        const active = this.activeSessions.get(session.id);
+        if (!active) {
+            return;
+        }
+        this.activeSessions.delete(session.id);
+        await active.driverSession.release();
+    }
+    async healthCheck(datasource) {
+        const modes = [];
+        modes.push(await this.healthCheckMode(datasource, "ro"));
+        if (!this.config.enableMutations) {
+            modes.push({
+                mode: "rw",
+                status: "skipped",
+                message: "Mutation mode disabled by config.",
+            });
+        }
+        else {
+            modes.push(await this.healthCheckMode(datasource, "rw"));
+        }
+        return {
+            datasource,
+            checkedAt: new Date().toISOString(),
+            modes,
+        };
+    }
+    async close() {
+        const activeSessions = [...this.activeSessions.values()];
+        this.activeSessions.clear();
+        for (const active of activeSessions) {
+            try {
+                await active.driverSession.release();
+            }
+            catch {
+                // Ignore release failure during shutdown.
+            }
+        }
+        const closers = [];
+        for (const value of this.pools.values()) {
+            const resolved = await value;
+            closers.push(resolved.pool.close().catch(() => {
+                // Ignore close failure during shutdown.
+            }));
+        }
+        await Promise.all(closers);
+        this.pools.clear();
+    }
+    async healthCheckMode(datasource, mode) {
+        try {
+            const session = await this.acquire(datasource, mode);
+            await this.release(session);
+            return { mode, status: "ok" };
+        }
+        catch (error) {
+            if (mode === "rw" && error instanceof ConnectionPoolError && /not configured/.test(error.message)) {
+                return { mode, status: "skipped", message: error.message };
+            }
+            return {
+                mode,
+                status: "error",
+                message: error instanceof Error ? error.message : "unknown error",
+            };
+        }
+    }
+    async getOrCreatePool(profile, mode, opts = {}) {
+        const key = poolKey(profile.name, mode);
+        const existing = this.pools.get(key);
+        if (existing) {
+            return existing instanceof Promise ? existing : existing;
+        }
+        const pending = this.createPool(profile, mode, opts)
+            .then((entry) => {
+            this.pools.set(key, entry);
+            return entry;
+        })
+            .catch((error) => {
+            this.pools.delete(key);
+            throw error;
+        });
+        this.pools.set(key, pending);
+        return pending;
+    }
+    async createPool(profile, mode, opts = {}) {
+        const adapter = this.adapters[profile.engine];
+        if (!adapter) {
+            throw new ConnectionPoolError(`No driver adapter registered for engine "${profile.engine}".`);
+        }
+        if (!profile.host) {
+            throw new ConnectionPoolError(`Datasource "${profile.name}" does not define a host. Select a cloud instance or configure host in the datasource profile.`);
+        }
+        const credential = selectCredential(profile, mode, opts);
+        const password = await resolveCredentialValue(credential.password, this.secretResolver, `${profile.name}.${mode}.password`);
+        const tls = await resolveTls(profile.tls, this.secretResolver);
+        let pool;
+        try {
+            pool = await adapter.createPool({
+                datasource: profile.name,
+                mode,
+                engine: profile.engine,
+                host: profile.host,
+                port: profile.port,
+                database: profile.database,
+                username: credential.username,
+                password,
+                poolSize: profile.poolSize,
+                tls,
+            });
+        }
+        catch (error) {
+            throw new ConnectionPoolError(`Failed to create ${mode === "ro" ? "readonly" : "mutation"} pool for datasource "${profile.name}".`, error);
+        }
+        return {
+            key: poolKey(profile.name, mode),
+            datasource: profile.name,
+            mode,
+            pool,
+        };
+    }
+}
+export function createConnectionPoolManager(options) {
+    return new ConnectionPoolManager(options);
+}

package/dist/executor/explain.d.ts

@@ -0,0 +1,5 @@
+import type { RawResult } from "./connection-pool.js";
+import type { ExplainRiskSummary } from "../safety/sql-validator.js";
+export declare function normalizeExplainRows(result: RawResult): Record<string, unknown>[];
+export declare function summarizeExplainRows(rows: Record<string, unknown>[]): ExplainRiskSummary;
+export declare function buildExplainRecommendations(summary: ExplainRiskSummary): string[];