taurusdb-core 0.4.0 → 0.5.0-rc.1

package/dist/diagnostics/replication-lag.js

@@ -0,0 +1,138 @@
+function rowsAsObjects(result) {
+    return result.rows.map((row) => Object.fromEntries(result.columns.map((column, index) => [column.name, row[index]])));
+}
+function text(row, ...names) {
+    for (const name of names) {
+        const value = row[name];
+        if (value !== undefined && value !== null && String(value).trim()) {
+            return String(value).trim();
+        }
+    }
+    return undefined;
+}
+function number(row, ...names) {
+    const value = text(row, ...names);
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+async function readReplicationStatus(executor, ctx) {
+    try {
+        return rowsAsObjects(await executor.executeReadonly("SHOW REPLICA STATUS", ctx, {
+            maxRows: 20,
+            maxColumns: 80,
+            maxFieldChars: 512,
+            maxResultBytes: 262144,
+        }));
+    }
+    catch {
+        return rowsAsObjects(await executor.executeReadonly("SHOW SLAVE STATUS", ctx, {
+            maxRows: 20,
+            maxColumns: 80,
+            maxFieldChars: 512,
+            maxResultBytes: 262144,
+        }));
+    }
+}
+export async function diagnoseReplicationLag(executor, input, ctx) {
+    let rows;
+    try {
+        rows = await readReplicationStatus(executor, ctx);
+    }
+    catch {
+        rows = [];
+    }
+    const filtered = rows.filter((row) => {
+        const channel = text(row, "Channel_Name");
+        const replicaId = text(row, "Server_Id", "Source_Server_Id", "Master_Server_Id");
+        return ((!input.channel || channel === input.channel) &&
+            (!input.replicaId || replicaId === input.replicaId));
+    });
+    const window = {
+        from: input.timeRange?.from,
+        to: input.timeRange?.to,
+        relative: input.timeRange?.relative,
+    };
+    if (filtered.length === 0) {
+        return {
+            tool: "diagnose_replication_lag",
+            status: "not_applicable",
+            severity: "info",
+            summary: "No replication channel was visible on the selected database endpoint.",
+            diagnosisWindow: window,
+            rootCauseCandidates: [],
+            keyFindings: [
+                "SHOW REPLICA STATUS and SHOW SLAVE STATUS returned no matching channel.",
+            ],
+            evidence: [],
+            recommendedActions: [
+                "Confirm that the selected endpoint is a read replica and that the read-only SQL user can inspect replication status.",
+            ],
+            limitations: [
+                "A primary or standalone endpoint legitimately has no replica status.",
+                "Cloud time-series replication metrics are not included in this data-plane-only result.",
+            ],
+        };
+    }
+    const findings = filtered.map((row) => {
+        const lag = number(row, "Seconds_Behind_Source", "Seconds_Behind_Master");
+        const io = text(row, "Replica_IO_Running", "Slave_IO_Running") ?? "unknown";
+        const sql = text(row, "Replica_SQL_Running", "Slave_SQL_Running") ?? "unknown";
+        const channel = text(row, "Channel_Name") ?? "default";
+        return { lag, io, sql, channel };
+    });
+    const maxLag = Math.max(...findings.map((item) => item.lag ?? 0));
+    const stopped = findings.some((item) => item.io.toLowerCase() === "no" || item.sql.toLowerCase() === "no");
+    const severity = stopped || maxLag >= 300 ? "high" : maxLag >= 30 ? "warning" : "info";
+    const status = stopped || maxLag >= 30 ? "inconclusive" : "ok";
+    return {
+        tool: "diagnose_replication_lag",
+        status,
+        severity,
+        summary: stopped
+            ? "At least one replication worker is not running."
+            : `Observed maximum replication delay of ${maxLag} seconds.`,
+        diagnosisWindow: window,
+        rootCauseCandidates: [
+            ...(stopped
+                ? [{
+                        code: "replication_worker_stopped",
+                        title: "Replication worker stopped",
+                        confidence: "high",
+                        rationale: "Replica IO or SQL worker reports No.",
+                    }]
+                : []),
+            ...(maxLag >= 30
+                ? [{
+                        code: "replication_delay",
+                        title: "Replica apply delay",
+                        confidence: "high",
+                        rationale: `Seconds behind source reached ${maxLag}.`,
+                    }]
+                : []),
+        ],
+        keyFindings: findings.map((item) => `Channel ${item.channel}: lag=${item.lag ?? "unknown"}s, io=${item.io}, sql=${item.sql}.`),
+        evidence: [{
+                source: "replication_status",
+                title: "Current replication status",
+                summary: `Collected ${findings.length} matching replication channel(s).`,
+            }],
+        recommendedActions: stopped
+            ? [
+                "Inspect Last_IO_Error and Last_SQL_Error directly with a privileged DBA account.",
+                "Do not skip replication errors until the failed event and data consistency impact are understood.",
+            ]
+            : maxLag >= 30
+                ? [
+                    "Check long transactions, write bursts, DDL, and replica resource saturation.",
+                    "Compare lag over time in Cloud Eye before changing replica topology.",
+                ]
+                : ["Continue monitoring the replication delay trend."],
+        limitations: [
+            "This result is a point-in-time data-plane snapshot.",
+            "Error text and relay-log SQL are intentionally not returned to the MCP client.",
+        ],
+    };
+}

package/dist/diagnostics/types.d.ts

@@ -1,4 +1,4 @@
-export type DiagnosticToolName = "diagnose_service_latency" | "diagnose_db_hotspot" | "find_top_slow_sql" | "diagnose_slow_query" | "diagnose_connection_spike" | "diagnose_lock_contention" | "diagnose_storage_pressure";
+export type DiagnosticToolName = "diagnose_service_latency" | "diagnose_db_hotspot" | "find_top_slow_sql" | "diagnose_slow_query" | "diagnose_connection_spike" | "diagnose_lock_contention" | "diagnose_replication_lag" | "diagnose_storage_pressure";
 export type DiagnosticStatus = "ok" | "inconclusive" | "not_applicable";
 export type DiagnosticSeverity = "info" | "warning" | "high" | "critical";
 export type DiagnosticEvidenceLevel = "basic" | "standard" | "full";
@@ -46,6 +46,10 @@ export interface DiagnoseStoragePressureInput extends DiagnosticBaseInput {
     scope?: "instance" | "database" | "table";
     table?: string;
 }
+export interface DiagnoseReplicationLagInput extends DiagnosticBaseInput {
+    replicaId?: string;
+    channel?: string;
+}
 export interface DiagnosticRootCauseCandidate {
     code: string;
     title: string;

package/dist/diagnostics/types.js

@@ -11,29 +11,29 @@ export function createPlaceholderDiagnosticResult(tool, input, options) {
         },
         rootCauseCandidates: [
             {
-                code: `${tool}_pending`,
+                code: `${tool}_insufficient_evidence`,
                 title: options.candidateTitle,
                 confidence: "low",
                 rationale: options.candidateRationale,
             },
         ],
         keyFindings: options.keyFindings ?? [
-            "The diagnostic contract is available, but evidence collectors have not been wired yet.",
-            "No live control-plane or data-plane evidence was collected in this run.",
+            "No conclusive live control-plane or data-plane evidence matched this diagnosis.",
+            "The result is intentionally inconclusive rather than inferring a root cause without evidence.",
         ],
         suspiciousEntities: options.suspiciousEntities,
         evidence: options.evidence ?? [
             {
-                source: "diagnostics_scaffold",
-                title: "Diagnostic scaffold active",
-                summary: "Typed inputs, outputs, and engine entrypoints are in place, but collectors and analyzers are pending.",
+                source: "diagnostic_limitations",
+                title: "No conclusive evidence",
+                summary: "The configured collectors returned no evidence sufficient for a root-cause conclusion.",
             },
         ],
         recommendedActions: options.recommendedActions ?? [
             "Implement the required collectors before relying on this tool for production diagnosis.",
         ],
         limitations: options.limitations ?? [
-            "This diagnostic currently returns a scaffolded result instead of live evidence-backed analysis.",
+            "The configured datasource, permissions, time window, or cloud metric sources did not provide sufficient evidence.",
         ],
     };
 }

package/dist/engine/runtime.d.ts

@@ -1,6 +1,6 @@
 import type { SessionContext } from "../context/session-context.js";
 import type { CancelResult, ExplainResult, MutationOptions, MutationResult, QueryResult, QueryStatus, ReadonlyOptions } from "../executor/sql-executor.js";
-import type { ConfirmationToken, ConfirmationValidationResult } from "../safety/confirmation-store.js";
+import type { ConfirmationRequest, ConfirmationValidationResult } from "../safety/confirmation-store.js";
 import type { GuardrailDecision } from "../safety/guardrail.js";
 import { type FlashbackInput } from "../taurus/flashback.js";
 import { type RestoreRecycleBinTableInput } from "../taurus/recycle-bin.js";
@@ -14,7 +14,7 @@ export declare function listRecycleBin(engine: TaurusDBEngine, ctx: SessionConte
 export declare function restoreRecycleBinTable(engine: TaurusDBEngine, input: RestoreRecycleBinTableInput, ctx: SessionContext, opts?: MutationOptions): Promise<MutationResult>;
 export declare function getQueryStatus(engine: TaurusDBEngine, queryId: string): Promise<QueryStatus>;
 export declare function cancelQuery(engine: TaurusDBEngine, queryId: string): Promise<CancelResult>;
-export declare function issueConfirmation(engine: TaurusDBEngine, input: IssueConfirmationInput): Promise<ConfirmationToken>;
+export declare function issueConfirmation(engine: TaurusDBEngine, input: IssueConfirmationInput): Promise<ConfirmationRequest>;
 export declare function validateConfirmation(engine: TaurusDBEngine, token: string, sql: string, ctx: SessionContext): Promise<ConfirmationValidationResult>;
 export declare function handleConfirmation(engine: TaurusDBEngine, decision: GuardrailDecision, ctx: SessionContext): Promise<ConfirmationOutcome>;
 export declare function close(engine: TaurusDBEngine): Promise<void>;

package/dist/engine/runtime.js

@@ -3,6 +3,7 @@ import { InMemoryConfirmationStore } from "../safety/confirmation-store.js";
 import { buildFlashbackSql, FlashbackNoViewError, flashbackReadonlyOptions, formatTimestamp, normalizeFlashbackWhereClause, resolveRelativeTimestampFromBase, resolveFlashbackTimestamp, } from "../taurus/flashback.js";
 import { buildListRecycleBinSql, buildRestoreRecycleBinTableSql, recycleBinMutationOptions, recycleBinReadonlyOptions } from "../taurus/recycle-bin.js";
 import { normalizeSql, sqlHash } from "../utils/hash.js";
+import { quoteMysqlIdentifier } from "../utils/mysql-identifier.js";
 function resolveConfirmationSql(input) {
     const normalized = input.normalizedSql ?? (input.sql ? normalizeSql(input.sql) : undefined);
     const hash = input.sqlHash ?? (normalized ? sqlHash(normalized) : undefined);
@@ -26,13 +27,6 @@ function hasSqlPattern(sql, pattern) {
     return pattern.test(sql);
 }
 const NO_FLASHBACK_VIEW_PATTERN = /No view available for provided TIMESTAMP/i;
-const SIMPLE_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
-function quoteIdentifier(identifier) {
-    if (!SIMPLE_IDENTIFIER_PATTERN.test(identifier)) {
-        throw new Error(`Invalid identifier: "${identifier}".`);
-    }
-    return `\`${identifier}\``;
-}
 function firstRowAsObject(result) {
     if (result.rows.length === 0) {
         return undefined;
@@ -91,7 +85,7 @@ async function buildFlashbackNoViewError(engine, ctx, input, database, requested
     if (input.where?.trim()) {
         try {
             const where = normalizeFlashbackWhereClause(input.where);
-            const updatedAtResult = await engine.executor.executeReadonly(`SELECT ${quoteIdentifier("updated_at")} FROM ${quoteIdentifier(database)}.${quoteIdentifier(input.table)} WHERE (${where}) LIMIT 1`, ctx, { maxRows: 1, maxColumns: 1, maxFieldChars: 128 });
+            const updatedAtResult = await engine.executor.executeReadonly(`SELECT ${quoteMysqlIdentifier("updated_at")} FROM ${quoteMysqlIdentifier(database, "database")}.${quoteMysqlIdentifier(input.table, "table")} WHERE (${where}) LIMIT 1`, ctx, { maxRows: 1, maxColumns: 1, maxFieldChars: 128 });
             const updatedAtRow = firstRowAsObject(updatedAtResult);
             if (typeof updatedAtRow?.updated_at === "string") {
                 details.current_row_updated_at = updatedAtRow.updated_at;
@@ -341,7 +335,6 @@ export async function restoreRecycleBinTable(engine, input, ctx, opts) {
     }
     return engine.executor.executeMutation(buildRestoreRecycleBinTableSql(input), ctx, {
         ...recycleBinMutationOptions(opts),
-        allowReadonlyFallbackForMutations: true,
     });
 }
 export async function getQueryStatus(engine, queryId) {
@@ -367,17 +360,18 @@ export async function handleConfirmation(engine, decision, ctx) {
     if (!decision.requiresConfirmation) {
         return { status: "confirmed" };
     }
-    const token = await engine.confirmationStore.issue({
+    const approval = await engine.confirmationStore.issue({
         sqlHash: decision.sqlHash,
         normalizedSql: decision.normalizedSql,
         context: ctx,
         riskLevel: decision.riskLevel,
     });
     return {
-        status: "token_issued",
-        token: token.token,
-        issuedAt: token.issuedAt,
-        expiresAt: token.expiresAt,
+        status: "approval_required",
+        request: approval.request,
+        requestId: approval.requestId,
+        issuedAt: approval.issuedAt,
+        expiresAt: approval.expiresAt,
     };
 }
 export async function close(engine) {

package/dist/engine/types.d.ts

@@ -31,8 +31,9 @@ export type IssueConfirmationInput = {
 export type ConfirmationOutcome = {
     status: "confirmed";
 } | {
-    status: "token_issued";
-    token: string;
+    status: "approval_required";
+    request: string;
+    requestId: string;
     issuedAt: number;
     expiresAt: number;
 };

package/dist/engine.d.ts

@@ -6,12 +6,12 @@ import { type Config } from "./config/index.js";
 import type { DatasourceResolveInput, DatasourceResolver, SessionContext } from "./context/session-context.js";
 import { type ConnectionPool } from "./executor/connection-pool.js";
 import { type CancelResult, type ExplainResult, type MutationOptions, type MutationResult, type QueryResult, type QueryStatus, type ReadonlyOptions, type SqlExecutor } from "./executor/sql-executor.js";
-import { type ConfirmationStore, type ConfirmationToken, type ConfirmationValidationResult } from "./safety/confirmation-store.js";
+import { type ConfirmationStore, type ConfirmationRequest, type ConfirmationValidationResult } from "./safety/confirmation-store.js";
 import { type Guardrail, type GuardrailDecision, type InspectInput } from "./safety/guardrail.js";
 import { type DatabaseInfo, type SchemaIntrospector, type TableInfo, type TableSchema } from "./schema/introspector.js";
 import { type FlashbackInput } from "./taurus/flashback.js";
 import { type RestoreRecycleBinTableInput } from "./taurus/recycle-bin.js";
-import { type DbHotspotResult, type DiagnoseDbHotspotInput, type DiagnoseServiceLatencyInput, type FindTopSlowSqlInput, type FindTopSlowSqlResult, type DiagnoseConnectionSpikeInput, type DiagnoseLockContentionInput, type DiagnoseSlowQueryInput, type DiagnoseStoragePressureInput, type DiagnosticResult, type ServiceLatencyResult } from "./diagnostics/types.js";
+import { type DbHotspotResult, type DiagnoseDbHotspotInput, type DiagnoseServiceLatencyInput, type FindTopSlowSqlInput, type FindTopSlowSqlResult, type DiagnoseConnectionSpikeInput, type DiagnoseLockContentionInput, type DiagnoseSlowQueryInput, type DiagnoseStoragePressureInput, type DiagnoseReplicationLagInput, type DiagnosticResult, type ServiceLatencyResult } from "./diagnostics/types.js";
 import { type SlowSqlSource } from "./diagnostics/slow-sql-source.js";
 import { type MetricsSource } from "./diagnostics/metrics-source.js";
 import type { ConfirmationOutcome, DataSourceInfo, EnhancedExplainResult, IssueConfirmationInput, ShowLockWaitsInput, ShowProcesslistInput, TaurusDBEngineCreateOptions, TaurusDBEngineDeps } from "./engine/types.js";
@@ -44,6 +44,7 @@ export declare class TaurusDBEngine {
     listFeatures(ctx: SessionContext): Promise<FeatureMatrix>;
     showProcesslist(input: ShowProcesslistInput, ctx: SessionContext): Promise<QueryResult>;
     showLockWaits(input: ShowLockWaitsInput, ctx: SessionContext): Promise<QueryResult>;
+    diagnoseReplicationLag(input: DiagnoseReplicationLagInput, ctx: SessionContext): Promise<DiagnosticResult>;
     findMetadataLockWaits(input: DiagnoseLockContentionInput, ctx: SessionContext): Promise<MetadataLockRow[]>;
     findLatestDeadlock(ctx: SessionContext): Promise<DeadlockSummary | undefined>;
     findStatementDigestSample(digestText: string, ctx: SessionContext): Promise<StatementDigestRow | undefined>;
@@ -70,7 +71,7 @@ export declare class TaurusDBEngine {
     restoreRecycleBinTable(input: RestoreRecycleBinTableInput, ctx: SessionContext, opts?: MutationOptions): Promise<MutationResult>;
     getQueryStatus(queryId: string): Promise<QueryStatus>;
     cancelQuery(queryId: string): Promise<CancelResult>;
-    issueConfirmation(input: IssueConfirmationInput): Promise<ConfirmationToken>;
+    issueConfirmation(input: IssueConfirmationInput): Promise<ConfirmationRequest>;
     validateConfirmation(token: string, sql: string, ctx: SessionContext): Promise<ConfirmationValidationResult>;
     handleConfirmation(decision: GuardrailDecision, ctx: SessionContext): Promise<ConfirmationOutcome>;
     close(): Promise<void>;

package/dist/engine.js

@@ -1,3 +1,4 @@
+import { lstat, readFile } from "node:fs/promises";
 import { createSqlProfileLoader, } from "./auth/sql-profile-loader.js";
 import { createSecretResolver, } from "./auth/secret-resolver.js";
 import { createHuaweiKmsSecretResolver } from "./cloud/kms.js";
@@ -12,11 +13,26 @@ 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 { diagnoseReplicationLag } from "./diagnostics/replication-lag.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";
+async function readMutationApprovalSecret(filePath) {
+    const info = await lstat(filePath);
+    if (!info.isFile() || info.isSymbolicLink()) {
+        throw new Error("Mutation approval secret must be a regular, non-symlink file.");
+    }
+    if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
+        throw new Error("Mutation approval secret file must not be accessible by group or other users.");
+    }
+    const secret = (await readFile(filePath, "utf8")).trim();
+    if (Buffer.byteLength(secret, "utf8") < 32) {
+        throw new Error("Mutation approval secret must contain at least 32 bytes.");
+    }
+    return secret;
+}
 function toDataSourceInfo(profile, defaultDatasource) {
     return {
         name: profile.name,
@@ -89,9 +105,23 @@ export class TaurusDBEngine {
         const executor = options.executor ??
             createSqlExecutor({
                 connectionPool,
+                maxConcurrentQueries: config.limits.maxConcurrentQueries,
+                maxQueuedQueries: config.limits.maxQueuedQueries,
+                queueTimeoutMs: config.limits.queueTimeoutMs,
             });
         const guardrail = options.guardrail ?? createGuardrail();
-        const confirmationStore = options.confirmationStore ?? createConfirmationStore();
+        let approvalSecret;
+        if (config.security.approvalSecretPath) {
+            approvalSecret = await readMutationApprovalSecret(config.security.approvalSecretPath);
+        }
+        if (config.security.mutationsEnabled && !approvalSecret && !options.confirmationStore) {
+            throw new Error("Mutations require TAURUSDB_MUTATION_APPROVAL_SECRET_FILE with at least 32 bytes.");
+        }
+        const confirmationStore = options.confirmationStore ??
+            createConfirmationStore({
+                approvalSecret,
+                ttlSeconds: config.security.approvalTtlSeconds,
+            });
         const capabilityProbe = options.capabilityProbe ??
             createCapabilityProbe({
                 connectionPool,
@@ -155,6 +185,9 @@ export class TaurusDBEngine {
     async showLockWaits(input, ctx) {
         return showLockWaits(this, input, ctx);
     }
+    async diagnoseReplicationLag(input, ctx) {
+        return diagnoseReplicationLag(this.executor, input, ctx);
+    }
     async findMetadataLockWaits(input, ctx) {
         return findMetadataLockWaits(this, input, ctx);
     }

package/dist/executor/bounded-sql.d.ts

@@ -0,0 +1 @@
+export declare function buildServerBoundedReadonlySql(sql: string, maxRows: number): string;

package/dist/executor/bounded-sql.js

@@ -0,0 +1,10 @@
+export function buildServerBoundedReadonlySql(sql, maxRows) {
+    const normalized = sql.trim().replace(/;\s*$/, "");
+    if (!/^(?:select|with)\b/i.test(normalized)) {
+        return normalized;
+    }
+    if (!Number.isInteger(maxRows) || maxRows <= 0) {
+        throw new Error("maxRows must be a positive integer.");
+    }
+    return `SELECT * FROM (${normalized}) AS __taurus_mcp_bounded LIMIT ${maxRows + 1}`;
+}

package/dist/executor/concurrency-limiter.d.ts

@@ -0,0 +1,15 @@
+export declare class QueryConcurrencyError extends Error {
+    readonly code = "SERVER_BUSY";
+    constructor(message: string);
+}
+export declare class QueryConcurrencyLimiter {
+    private readonly maxConcurrent;
+    private readonly maxQueued;
+    private readonly queueTimeoutMs;
+    private active;
+    private readonly queue;
+    constructor(maxConcurrent: number, maxQueued: number, queueTimeoutMs: number);
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    private acquire;
+    private releaseFactory;
+}

package/dist/executor/concurrency-limiter.js

@@ -0,0 +1,67 @@
+export class QueryConcurrencyError extends Error {
+    code = "SERVER_BUSY";
+    constructor(message) {
+        super(message);
+        this.name = "QueryConcurrencyError";
+    }
+}
+export class QueryConcurrencyLimiter {
+    maxConcurrent;
+    maxQueued;
+    queueTimeoutMs;
+    active = 0;
+    queue = [];
+    constructor(maxConcurrent, maxQueued, queueTimeoutMs) {
+        this.maxConcurrent = maxConcurrent;
+        this.maxQueued = maxQueued;
+        this.queueTimeoutMs = queueTimeoutMs;
+    }
+    async run(operation) {
+        const release = await this.acquire();
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    acquire() {
+        if (this.active < this.maxConcurrent) {
+            this.active += 1;
+            return Promise.resolve(this.releaseFactory());
+        }
+        if (this.queue.length >= this.maxQueued) {
+            return Promise.reject(new QueryConcurrencyError("Query concurrency queue is full."));
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    const index = this.queue.indexOf(waiter);
+                    if (index >= 0) {
+                        this.queue.splice(index, 1);
+                    }
+                    reject(new QueryConcurrencyError("Timed out waiting for query capacity."));
+                }, this.queueTimeoutMs),
+            };
+            this.queue.push(waiter);
+        });
+    }
+    releaseFactory() {
+        let released = false;
+        return () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            const waiter = this.queue.shift();
+            if (waiter) {
+                clearTimeout(waiter.timer);
+                waiter.resolve(this.releaseFactory());
+                return;
+            }
+            this.active -= 1;
+        };
+    }
+}

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

@@ -18,6 +18,7 @@ export interface RawResult {
 export interface Session {
     id: string;
     datasource: string;
+    database?: string;
     mode: PoolMode;
     execute(sql: string, options?: ExecOptions): Promise<RawResult>;
     cancel(): Promise<void>;
@@ -35,7 +36,7 @@ export interface PoolHealth {
 }
 export interface ConnectionPool {
     acquire(datasource: string, mode: PoolMode, opts?: {
-        allowReadonlyFallbackForMutations?: boolean;
+        database?: string;
     }): Promise<Session>;
     release(session: Session): Promise<void>;
     healthCheck(datasource: string): Promise<PoolHealth>;
@@ -91,7 +92,7 @@ export declare class ConnectionPoolManager implements ConnectionPool {
     private readonly activeSessions;
     constructor(options: ConnectionPoolManagerOptions);
     acquire(datasource: string, mode: PoolMode, opts?: {
-        allowReadonlyFallbackForMutations?: boolean;
+        database?: string;
     }): Promise<Session>;
     release(session: Session): Promise<void>;
     healthCheck(datasource: string): Promise<PoolHealth>;

package/dist/executor/connection-pool.js

@@ -1,3 +1,4 @@
+import { isIP } from "node:net";
 import { ulid } from "ulid";
 export class ConnectionPoolError extends Error {
     code = "CONNECTION_FAILED";
@@ -9,35 +10,42 @@ export class ConnectionPoolError extends Error {
         }
     }
 }
-function poolKey(datasource, mode) {
-    return `${datasource}:${mode}`;
+function poolKey(datasource, mode, database) {
+    return JSON.stringify([datasource, mode, database ?? null]);
 }
-async function resolveTls(tls, secretResolver) {
-    if (!tls) {
+async function resolveTls(tls, secretResolver, host, requireTls) {
+    if (!tls && !requireTls) {
         return undefined;
     }
+    if (requireTls && tls?.enabled === false) {
+        throw new ConnectionPoolError("TLS is required by server policy and cannot be disabled for this datasource.");
+    }
+    if (requireTls && tls?.rejectUnauthorized === false) {
+        throw new ConnectionPoolError("TLS certificate verification is required by server policy.");
+    }
     const resolved = {
-        enabled: tls.enabled,
-        rejectUnauthorized: tls.rejectUnauthorized,
-        servername: tls.servername,
+        enabled: tls?.enabled ?? true,
+        rejectUnauthorized: tls?.rejectUnauthorized ?? true,
+        servername: tls?.servername ?? (isIP(host) === 0 ? host : undefined),
     };
-    if (tls.ca) {
+    if (tls?.ca) {
         resolved.ca = await secretResolver.resolve(tls.ca);
     }
-    if (tls.cert) {
+    if (tls?.cert) {
         resolved.cert = await secretResolver.resolve(tls.cert);
     }
-    if (tls.key) {
+    if (tls?.key) {
         resolved.key = await secretResolver.resolve(tls.key);
     }
     return resolved;
 }
-function selectCredential(profile, mode, _opts = {}) {
-    void mode;
-    if (!profile.user) {
-        throw new ConnectionPoolError(`Datasource "${profile.name}" does not define SQL credentials. Configure a database username and password reference before executing SQL.`);
+function selectCredential(profile, mode) {
+    const credential = mode === "rw" ? profile.mutationUser : profile.user;
+    if (!credential) {
+        const credentialKind = mode === "rw" ? "mutation" : "read-only";
+        throw new ConnectionPoolError(`Datasource "${profile.name}" does not define ${credentialKind} SQL credentials. Configure a dedicated ${credentialKind} database username and password reference.`);
     }
-    return profile.user;
+    return credential;
 }
 async function resolveCredentialValue(ref, secretResolver, context) {
     try {
@@ -65,7 +73,8 @@ export class ConnectionPoolManager {
         if (!profile) {
             throw new ConnectionPoolError(`Datasource profile not found: "${datasource}".`);
         }
-        const entry = await this.getOrCreatePool(profile, mode, opts);
+        const database = opts.database ?? profile.database;
+        const entry = await this.getOrCreatePool(profile, mode, database);
         let driverSession;
         try {
             driverSession = await entry.pool.acquire();
@@ -79,6 +88,7 @@ export class ConnectionPoolManager {
             entryKey: entry.key,
             driverSession,
             datasource,
+            database,
             mode,
         };
         this.activeSessions.set(sessionId, active);
@@ -86,6 +96,7 @@ export class ConnectionPoolManager {
         return {
             id: sessionId,
             datasource,
+            database,
             mode,
             async execute(sql, options) {
                 return active.driverSession.execute(sql, options);
@@ -151,13 +162,13 @@ export class ConnectionPoolManager {
             };
         }
     }
-    async getOrCreatePool(profile, mode, opts = {}) {
-        const key = poolKey(profile.name, mode);
+    async getOrCreatePool(profile, mode, database) {
+        const key = poolKey(profile.name, mode, database);
         const existing = this.pools.get(key);
         if (existing) {
             return existing instanceof Promise ? existing : existing;
         }
-        const pending = this.createPool(profile, mode, opts)
+        const pending = this.createPool(profile, mode, database)
             .then((entry) => {
             this.pools.set(key, entry);
             return entry;
@@ -169,7 +180,7 @@ export class ConnectionPoolManager {
         this.pools.set(key, pending);
         return pending;
     }
-    async createPool(profile, mode, opts = {}) {
+    async createPool(profile, mode, database) {
         const adapter = this.adapters[profile.engine];
         if (!adapter) {
             throw new ConnectionPoolError(`No driver adapter registered for engine "${profile.engine}".`);
@@ -177,9 +188,9 @@ export class ConnectionPoolManager {
         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 credential = selectCredential(profile, mode);
         const password = await resolveCredentialValue(credential.password, this.secretResolver, `${profile.name}.${mode}.password`);
-        const tls = await resolveTls(profile.tls, this.secretResolver);
+        const tls = await resolveTls(profile.tls, this.secretResolver, profile.host, this.config.security.requireTls);
         let pool;
         try {
             pool = await adapter.createPool({
@@ -188,7 +199,7 @@ export class ConnectionPoolManager {
                 engine: profile.engine,
                 host: profile.host,
                 port: profile.port,
-                database: profile.database,
+                database,
                 username: credential.username,
                 password,
                 poolSize: profile.poolSize,
@@ -199,8 +210,9 @@ export class ConnectionPoolManager {
             throw new ConnectionPoolError(`Failed to create ${mode === "ro" ? "readonly" : "mutation"} pool for datasource "${profile.name}".`, error);
         }
         return {
-            key: poolKey(profile.name, mode),
+            key: poolKey(profile.name, mode, database),
             datasource: profile.name,
+            database,
             mode,
             pool,
         };