@hesed/mysql 0.5.1 → 0.6.0

package/dist/commands/mysql/tables.js

@@ -1,21 +1,21 @@
-import { Command, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
 import { closeConnections, listTables } from '../../mysql/index.js';
-export default class MySQLTables extends Command {
+export default class MySQLTables extends BaseCommand {
     static description = 'List all tables in the current MySQL database';
     static examples = ['<%= config.bin %> <%= command.id %>', '<%= config.bin %> <%= command.id %> -p local'];
     static flags = {
         profile: Flags.string({ char: 'p', description: 'Database profile name from config', required: false }),
     };
-    jsonEnabled() {
-        return true;
-    }
     async run() {
         const { flags } = await this.parse(MySQLTables);
         const result = await listTables(this.config, flags.profile);
         await closeConnections();
         if (result.success) {
-            return result.tables ?? [];
+            this.log(result.data?.result ?? '');
+            delete result.data.result;
+            return result;
         }
-        this.error(result.error ?? 'Failed to list tables');
+        this.error(String(result.error ?? 'Failed to list tables'));
     }
 }

package/dist/mysql/config-loader.d.ts

@@ -2,14 +2,18 @@ import type { ConnectionOptions as MySQL2ConnectionOptions } from 'mysql2/promis
 export interface DatabaseProfile {
     database: string;
     host: string;
+    maxConcurrentQueries?: number;
     password: string;
     port: number;
+    queryQueueTimeoutMs?: number;
     ssl?: boolean;
     user: string;
 }
 interface SafetyConfig {
     blacklistedOperations: string[];
     defaultLimit: number;
+    maxConcurrentQueries?: number;
+    queryQueueTimeoutMs?: number;
     requireConfirmationFor: string[];
 }
 export interface MySQLConfig {

package/dist/mysql/database.d.ts

@@ -1,49 +1,57 @@
-export interface QueryResult {
-    error?: string;
+import type { ApiResult } from '@hesed/plugin-lib';
+export type OutputFormat = 'csv' | 'json' | 'table' | 'toon';
+export interface QueryData {
     message?: string;
     notices?: string;
     requiresConfirmation?: boolean;
-    result?: string;
-    success: boolean;
+    result?: unknown;
 }
-export interface DatabaseListResult {
-    databases?: string[];
-    error?: string;
+export interface DatabaseListData {
+    databases: string[];
     result?: string;
-    success: boolean;
 }
-export interface TableListResult {
-    error?: string;
+export interface TableListData {
     result?: string;
-    success: boolean;
-    tables?: string[];
+    tables: string[];
 }
-export interface TableStructureResult {
-    error?: string;
+export interface TableStructureData {
     result?: string;
-    structure?: Record<string, unknown>[];
-    success: boolean;
+    structure: Record<string, unknown>[];
 }
-export interface IndexResult {
-    error?: string;
-    indexes?: Record<string, unknown>[];
+export interface IndexData {
+    indexes: Record<string, unknown>[];
     result?: string;
-    success: boolean;
 }
-export interface ExplainResult {
-    error?: string;
-    plan?: Record<string, unknown>[];
+export interface ExplainData {
+    plan: Record<string, unknown>[];
     result?: string;
-    success: boolean;
 }
-export interface ConnectionTestResult {
-    database?: string;
-    error?: string;
+interface ConnectionTestData {
+    database: string;
     result?: string;
-    success: boolean;
-    version?: string;
+    version: string;
 }
-export type OutputFormat = 'csv' | 'json' | 'table' | 'toon';
+export type QueryResult = ApiResult & {
+    data?: QueryData;
+};
+export type DatabaseListResult = ApiResult & {
+    data?: DatabaseListData;
+};
+export type TableListResult = ApiResult & {
+    data?: TableListData;
+};
+export type TableStructureResult = ApiResult & {
+    data?: TableStructureData;
+};
+export type IndexResult = ApiResult & {
+    data?: IndexData;
+};
+export type ExplainResult = ApiResult & {
+    data?: ExplainData;
+};
+export type ConnectionTestResult = ApiResult & {
+    data?: ConnectionTestData;
+};
 export interface DatabaseUtil {
     closeAll(): Promise<void>;
     describeTable(profileName: string, table: string, format?: OutputFormat): Promise<TableStructureResult>;
@@ -53,3 +61,4 @@ export interface DatabaseUtil {
     listTables(profileName: string): Promise<TableListResult>;
     showIndexes(profileName: string, table: string, format?: OutputFormat): Promise<IndexResult>;
 }
+export {};

package/dist/mysql/mysql-client.js

@@ -5,6 +5,8 @@ let cachedConfig = null;
 const DEFAULT_SAFETY_CONFIG = {
     blacklistedOperations: ['DROP DATABASE'],
     defaultLimit: 100,
+    maxConcurrentQueries: 5,
+    queryQueueTimeoutMs: 60_000,
     requireConfirmationFor: ['DELETE', 'UPDATE', 'DROP', 'TRUNCATE', 'ALTER'],
 };
 async function initMySQL(config) {

package/dist/mysql/mysql-utils.d.ts

@@ -2,7 +2,8 @@ import type { MySQLConfig } from './config-loader.js';
 import type { ConnectionTestResult, DatabaseListResult, DatabaseUtil, ExplainResult, IndexResult, OutputFormat, QueryResult, TableListResult, TableStructureResult } from './database.js';
 export declare class MySQLUtil implements DatabaseUtil {
     private config;
-    private connections;
+    private pools;
+    private querySlots;
     constructor(config: MySQLConfig);
     closeAll(): Promise<void>;
     describeTable(profileName: string, table: string, format?: 'json' | 'table' | 'toon'): Promise<TableStructureResult>;
@@ -12,8 +13,11 @@ export declare class MySQLUtil implements DatabaseUtil {
     listTables(profileName: string): Promise<TableListResult>;
     showIndexes(profileName: string, table: string, format?: 'json' | 'table' | 'toon'): Promise<IndexResult>;
     testConnection(profileName: string): Promise<ConnectionTestResult>;
+    private acquireQuerySlot;
     private formatReadResult;
     private formatRows;
     private formatWriteResult;
-    private getConnection;
+    private getPool;
+    private getQueryLimit;
+    private runQuery;
 }

package/dist/mysql/mysql-utils.js

@@ -2,25 +2,37 @@ import mysql from 'mysql2/promise';
 import { getMySQLConnectionOptions } from './config-loader.js';
 import { FORMATTERS } from './formatters.js';
 import { analyzeQuery, applyDefaultLimit, checkBlacklist, getQueryType, requiresConfirmation } from './query-validator.js';
+const DEFAULT_MAX_CONCURRENT_QUERIES = 5;
+const DEFAULT_QUEUE_TIMEOUT_MS = 60_000;
 export class MySQLUtil {
     config;
-    connections;
+    pools;
+    querySlots;
     constructor(config) {
         this.config = config;
-        this.connections = new Map();
+        this.pools = new Map();
+        this.querySlots = new Map();
     }
     async closeAll() {
-        const entries = [...this.connections.values()];
-        this.connections.clear();
-        await Promise.allSettled(entries.map(async (connPromise) => (await connPromise).end()));
+        // Reject queued queries first so nothing waits forever on a closed util.
+        for (const slot of this.querySlots.values()) {
+            for (const waiter of slot.waiting.splice(0)) {
+                waiter.reject(new Error('Connections were closed while the query was waiting for a free slot'));
+            }
+        }
+        this.querySlots.clear();
+        const pools = [...this.pools.values()];
+        this.pools.clear();
+        await Promise.allSettled(pools.map((pool) => pool.end()));
     }
     async describeTable(profileName, table, format = 'table') {
         try {
-            const connection = await this.getConnection(profileName);
-            const [rows, fields] = await connection.query(`DESCRIBE ${table}`);
+            const [rows, fields] = await this.runQuery(profileName, `DESCRIBE ${table}`);
             return {
-                result: this.formatRows(rows, fields, format),
-                structure: rows,
+                data: {
+                    result: this.formatRows(rows, fields, format),
+                    structure: rows,
+                },
                 success: true,
             };
         }
@@ -44,8 +56,10 @@ export class MySQLUtil {
             const confirmationCheck = requiresConfirmation(query, this.config.safety.requireConfirmationFor);
             if (confirmationCheck.required) {
                 return {
-                    message: `${confirmationCheck.message}\nQuery: ${query}`,
-                    requiresConfirmation: true,
+                    data: {
+                        message: `${confirmationCheck.message}\nQuery: ${query}`,
+                        requiresConfirmation: true,
+                    },
                     success: false,
                 };
             }
@@ -68,18 +82,22 @@ export class MySQLUtil {
             }
         }
         try {
-            const connection = await this.getConnection(profileName);
-            const [rows, fields] = await connection.query(finalQuery);
+            const [rows, fields] = await this.runQuery(profileName, finalQuery);
             const isRead = queryType === 'SELECT' || queryType === 'SHOW' || queryType === 'DESCRIBE' || queryType === 'EXPLAIN';
-            const data = isRead
+            let data = isRead
                 ? this.formatReadResult(rows, fields, format, notices)
-                : this.formatWriteResult(rows, notices);
+                : this.formatWriteResult(rows, notices, format);
+            if (format === 'json') {
+                data = JSON.parse(data);
+            }
             const notice = notices.join('\n\n');
             // For human (table) output everything stays on stdout, exactly as before.
             // For machine formats the data is returned alone and notices go to stderr.
             return {
-                notices: machineFormat ? notice : undefined,
-                result: machineFormat ? data : `${notice}\n\n${data}`,
+                data: {
+                    notices: machineFormat ? notice : undefined,
+                    result: machineFormat ? data : `${notice}\n\n${data}`,
+                },
                 success: true,
             };
         }
@@ -93,11 +111,12 @@ export class MySQLUtil {
     }
     async explainQuery(profileName, query, format = 'table') {
         try {
-            const connection = await this.getConnection(profileName);
-            const [rows, fields] = await connection.query(`EXPLAIN ${query}`);
+            const [rows, fields] = await this.runQuery(profileName, `EXPLAIN ${query}`);
             return {
-                plan: rows,
-                result: this.formatRows(rows, fields, format),
+                data: {
+                    plan: rows,
+                    result: this.formatRows(rows, fields, format),
+                },
                 success: true,
             };
         }
@@ -111,12 +130,13 @@ export class MySQLUtil {
     }
     async listDatabases(profileName) {
         try {
-            const connection = await this.getConnection(profileName);
-            const [rows] = await connection.query('SHOW DATABASES');
+            const [rows] = await this.runQuery(profileName, 'SHOW DATABASES');
             const databases = rows.map((row) => row.Database);
             return {
-                databases,
-                result: `Databases:\n${databases.map((db) => `  • ${db}`).join('\n')}`,
+                data: {
+                    databases,
+                    result: `Databases:\n${databases.map((db) => `  • ${db}`).join('\n')}`,
+                },
                 success: true,
             };
         }
@@ -130,15 +150,16 @@ export class MySQLUtil {
     }
     async listTables(profileName) {
         try {
-            const connection = await this.getConnection(profileName);
-            const [rows] = await connection.query('SHOW TABLES');
+            const [rows] = await this.runQuery(profileName, 'SHOW TABLES');
             const rowsArray = rows;
             const tableKey = Object.keys(rowsArray[0])[0];
             const tables = rowsArray.map((row) => row[tableKey]);
             return {
-                result: `Tables in database:\n${tables.map((table) => `  • ${table}`).join('\n')}`,
+                data: {
+                    result: `Tables in database:\n${tables.map((table) => `  • ${table}`).join('\n')}`,
+                    tables,
+                },
                 success: true,
-                tables,
             };
         }
         catch (error) {
@@ -151,11 +172,12 @@ export class MySQLUtil {
     }
     async showIndexes(profileName, table, format = 'table') {
         try {
-            const connection = await this.getConnection(profileName);
-            const [rows, fields] = await connection.query(`SHOW INDEXES FROM ${table}`);
+            const [rows, fields] = await this.runQuery(profileName, `SHOW INDEXES FROM ${table}`);
             return {
-                indexes: rows,
-                result: this.formatRows(rows, fields, format),
+                data: {
+                    indexes: rows,
+                    result: this.formatRows(rows, fields, format),
+                },
                 success: true,
             };
         }
@@ -169,14 +191,15 @@ export class MySQLUtil {
     }
     async testConnection(profileName) {
         try {
-            const connection = await this.getConnection(profileName);
-            const [rows] = await connection.query('SELECT VERSION() as version, DATABASE() as current_database');
+            const [rows] = await this.runQuery(profileName, 'SELECT VERSION() as version, DATABASE() as current_database');
             const info = rows[0];
             return {
-                database: info.current_database,
-                result: `Connection successful!\n\nProfile: ${profileName}\nMySQL Version: ${info.version}\nCurrent Database: ${info.current_database}`,
+                data: {
+                    database: info.current_database,
+                    result: `Connection successful!\n\nProfile: ${profileName}\nMySQL Version: ${info.version}\nCurrent Database: ${info.current_database}`,
+                    version: info.version,
+                },
                 success: true,
-                version: info.version,
             };
         }
         catch (error) {
@@ -187,6 +210,56 @@ export class MySQLUtil {
             };
         }
     }
+    // Grants a query slot for the profile, or waits until one frees up. The
+    // returned release callback must be invoked exactly once per acquisition.
+    acquireQuerySlot(profileName) {
+        const limit = this.getQueryLimit(profileName);
+        let slot = this.querySlots.get(profileName);
+        if (!slot) {
+            slot = { active: 0, waiting: [] };
+            this.querySlots.set(profileName, slot);
+        }
+        const state = slot;
+        const release = () => {
+            const next = state.waiting.shift();
+            if (next) {
+                next.grant();
+            }
+            else {
+                state.active -= 1;
+            }
+        };
+        if (state.active < limit) {
+            state.active += 1;
+            return Promise.resolve(release);
+        }
+        const timeoutMs = this.config.profiles[profileName]?.queryQueueTimeoutMs ??
+            this.config.safety.queryQueueTimeoutMs ??
+            DEFAULT_QUEUE_TIMEOUT_MS;
+        process.stderr.write(`Waiting for a free query slot (${limit}/${limit} in use for profile "${profileName}")...\n`);
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                grant() {
+                    clearTimeout(timer);
+                    resolve(release);
+                },
+                reject(error) {
+                    clearTimeout(timer);
+                    reject(error);
+                },
+            };
+            const timer = setTimeout(() => {
+                const index = state.waiting.indexOf(waiter);
+                if (index !== -1)
+                    state.waiting.splice(index, 1);
+                reject(new Error(`Timed out after ${timeoutMs / 1000}s waiting for a free query slot ` +
+                    `(limit: ${limit} concurrent queries for profile "${profileName}")`));
+            }, timeoutMs);
+            // Don't let a pending queue timer keep the CLI process alive.
+            timer.unref?.();
+            state.waiting.push(waiter);
+        });
+    }
     formatReadResult(rows, fields, format, notices) {
         const rowCount = Array.isArray(rows) ? rows.length : 0;
         notices.push(`Query executed successfully. Rows returned: ${rowCount}`);
@@ -195,35 +268,54 @@ export class MySQLUtil {
     formatRows(rows, fields, format) {
         return FORMATTERS[format](rows, fields);
     }
-    formatWriteResult(rows, notices) {
+    formatWriteResult(rows, notices, format) {
         const affectedRows = rows.affectedRows ?? 0;
         const insertId = rows.insertId ?? null;
         notices.push('Query executed successfully.');
+        // The caller JSON.parses the result for json output, so emit valid JSON
+        // here rather than the human-readable string (which would throw on parse).
+        if (format === 'json') {
+            const payload = { affectedRows };
+            if (insertId)
+                payload.insertId = insertId;
+            return JSON.stringify(payload, null, 2);
+        }
         let data = `Affected rows: ${affectedRows}\n`;
         if (insertId)
             data += `Insert ID: ${insertId}\n`;
         return data;
     }
-    async getConnection(profileName) {
-        const existing = this.connections.get(profileName);
-        if (existing) {
-            try {
-                const conn = await existing;
-                await conn.ping();
-                return conn;
-            }
-            catch {
-                this.connections.delete(profileName);
-            }
-        }
-        const connPromise = mysql.createConnection(getMySQLConnectionOptions(this.config, profileName));
-        this.connections.set(profileName, connPromise);
+    // The pool is sized to the profile's query limit so slot holders each get a
+    // real physical connection — a single Connection would serialize commands on
+    // the wire and make the concurrency limit meaningless.
+    getPool(profileName) {
+        const existing = this.pools.get(profileName);
+        if (existing)
+            return existing;
+        const pool = mysql.createPool({
+            ...getMySQLConnectionOptions(this.config, profileName),
+            connectionLimit: this.getQueryLimit(profileName),
+            waitForConnections: true,
+        });
+        this.pools.set(profileName, pool);
+        return pool;
+    }
+    getQueryLimit(profileName) {
+        const configuredLimit = this.config.profiles[profileName]?.maxConcurrentQueries ??
+            this.config.safety.maxConcurrentQueries ??
+            DEFAULT_MAX_CONCURRENT_QUERIES;
+        // A limit below 1 would leave every query waiting forever.
+        return Math.max(1, configuredLimit);
+    }
+    // All queries go through here so concurrent load on the same profile is
+    // capped at maxConcurrentQueries; excess queries wait for a free slot.
+    async runQuery(profileName, sql) {
+        const release = await this.acquireQuerySlot(profileName);
         try {
-            return await connPromise;
+            return (await this.getPool(profileName).query(sql));
         }
-        catch (error) {
-            this.connections.delete(profileName);
-            throw error;
+        finally {
+            release();
         }
     }
 }