@hesed/mysql 0.5.2 → 0.6.1

package/README.md

@@ -26,7 +26,7 @@ $ npm install -g @hesed/mysql
 $ mq COMMAND
 running command...
 $ mq (--version)
-@hesed/mysql/0.5.2 linux-x64 node-v24.17.0
+@hesed/mysql/0.6.1 linux-x64 node-v24.18.0
 $ mq --help [COMMAND]
 USAGE
   $ mq COMMAND
@@ -57,16 +57,18 @@ Add MySQL authentication
 ```
 USAGE
   $ mq mysql auth add -p <value> --host <value> --port <value> -u <value> --password <value> -d <value> --ssl
-    [--json]
+    --maxConcurrentQueries <value> --queryQueueTimeoutMs <value> [--json]
 
 FLAGS
-  -d, --database=<value>  (required) Database name
-  -p, --profile=<value>   (required) Profile name
-  -u, --user=<value>      (required) Username
-      --host=<value>      (required) MySQL host
-      --password=<value>  (required) Password
-      --port=<value>      (required) MySQL port
-      --ssl               (required) Use SSL
+  -d, --database=<value>              (required) Database name
+  -p, --profile=<value>               (required) Profile name
+  -u, --user=<value>                  (required) Username
+      --host=<value>                  (required) MySQL host
+      --maxConcurrentQueries=<value>  (required) Max concurrent queries for this profile
+      --password=<value>              (required) Password
+      --port=<value>                  (required) MySQL port
+      --queryQueueTimeoutMs=<value>   (required) Milliseconds a query may wait for a free query slot before failing
+      --ssl                           (required) Use SSL
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -80,7 +82,7 @@ EXAMPLES
   $ mq mysql auth add -p prod
 ```
 
-_See code: [src/commands/mysql/auth/add.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/auth/add.ts)_
+_See code: [src/commands/mysql/auth/add.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/auth/add.ts)_
 
 ## `mq mysql auth delete`
 
@@ -105,7 +107,7 @@ EXAMPLES
   $ mq mysql auth delete -p prod
 ```
 
-_See code: [src/commands/mysql/auth/delete.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/auth/delete.ts)_
+_See code: [src/commands/mysql/auth/delete.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/auth/delete.ts)_
 
 ## `mq mysql auth list`
 
@@ -125,7 +127,7 @@ EXAMPLES
   $ mq mysql auth list
 ```
 
-_See code: [src/commands/mysql/auth/list.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/auth/list.ts)_
+_See code: [src/commands/mysql/auth/list.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/auth/list.ts)_
 
 ## `mq mysql auth profile`
 
@@ -150,7 +152,7 @@ EXAMPLES
   $ mq mysql auth profile --default test
 ```
 
-_See code: [src/commands/mysql/auth/profile.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/auth/profile.ts)_
+_See code: [src/commands/mysql/auth/profile.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/auth/profile.ts)_
 
 ## `mq mysql auth test`
 
@@ -175,7 +177,7 @@ EXAMPLES
   $ mq mysql auth test -p prod
 ```
 
-_See code: [src/commands/mysql/auth/test.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/auth/test.ts)_
+_See code: [src/commands/mysql/auth/test.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/auth/test.ts)_
 
 ## `mq mysql auth update`
 
@@ -184,16 +186,18 @@ Update MySQL authentication
 ```
 USAGE
   $ mq mysql auth update -p <value> --host <value> --port <value> -u <value> --password <value> -d <value> --ssl
-    [--json]
+    --maxConcurrentQueries <value> --queryQueueTimeoutMs <value> [--json]
 
 FLAGS
-  -d, --database=<value>  (required) Database name
-  -p, --profile=<value>   (required) Profile name
-  -u, --user=<value>      (required) Username
-      --host=<value>      (required) MySQL host
-      --password=<value>  (required) Password
-      --port=<value>      (required) MySQL port
-      --ssl               (required) Use SSL
+  -d, --database=<value>              (required) Database name
+  -p, --profile=<value>               (required) Profile name
+  -u, --user=<value>                  (required) Username
+      --host=<value>                  (required) MySQL host
+      --maxConcurrentQueries=<value>  (required) Max concurrent queries for this profile
+      --password=<value>              (required) Password
+      --port=<value>                  (required) MySQL port
+      --queryQueueTimeoutMs=<value>   (required) Milliseconds a query may wait for a free query slot before failing
+      --ssl                           (required) Use SSL
 
 GLOBAL FLAGS
   --json  Format output as json.
@@ -207,7 +211,7 @@ EXAMPLES
   $ mq mysql auth update -p test
 ```
 
-_See code: [src/commands/mysql/auth/update.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/auth/update.ts)_
+_See code: [src/commands/mysql/auth/update.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/auth/update.ts)_
 
 ## `mq mysql databases`
 
@@ -232,7 +236,7 @@ EXAMPLES
   $ mq mysql databases -p staging
 ```
 
-_See code: [src/commands/mysql/databases.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/databases.ts)_
+_See code: [src/commands/mysql/databases.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/databases.ts)_
 
 ## `mq mysql describe-table TABLE`
 
@@ -261,7 +265,7 @@ EXAMPLES
   $ mq mysql describe-table orders --toon -p prod
 ```
 
-_See code: [src/commands/mysql/describe-table.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/describe-table.ts)_
+_See code: [src/commands/mysql/describe-table.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/describe-table.ts)_
 
 ## `mq mysql explain QUERY`
 
@@ -290,7 +294,7 @@ EXAMPLES
   $ mq mysql explain "SELECT * FROM orders JOIN users ON orders.user_id = users.id" --json
 ```
 
-_See code: [src/commands/mysql/explain.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/explain.ts)_
+_See code: [src/commands/mysql/explain.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/explain.ts)_
 
 ## `mq mysql indexes TABLE`
 
@@ -319,7 +323,7 @@ EXAMPLES
   $ mq mysql indexes orders --json -p prod
 ```
 
-_See code: [src/commands/mysql/indexes.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/indexes.ts)_
+_See code: [src/commands/mysql/indexes.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/indexes.ts)_
 
 ## `mq mysql query QUERY`
 
@@ -351,7 +355,7 @@ EXAMPLES
   $ mq mysql query "DELETE FROM sessions" -p prod --skip-confirmation
 ```
 
-_See code: [src/commands/mysql/query.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/query.ts)_
+_See code: [src/commands/mysql/query.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/query.ts)_
 
 ## `mq mysql tables`
 
@@ -376,5 +380,5 @@ EXAMPLES
   $ mq mysql tables -p local
 ```
 
-_See code: [src/commands/mysql/tables.ts](https://github.com/hesedcasa/mysql/blob/v0.5.2/src/commands/mysql/tables.ts)_
+_See code: [src/commands/mysql/tables.ts](https://github.com/hesedcasa/mysql/blob/v0.6.1/src/commands/mysql/tables.ts)_
 <!-- commandsstop -->

package/dist/commands/mysql/auth/add.js

@@ -7,6 +7,20 @@ const fields = [
     { description: 'Password', name: 'password', type: 'string' },
     { char: 'd', description: 'Database name', name: 'database', type: 'string' },
     { default: false, description: 'Use SSL', name: 'ssl', required: false, type: 'boolean' },
+    {
+        default: 5,
+        description: 'Max concurrent queries for this profile',
+        name: 'maxConcurrentQueries',
+        required: false,
+        type: 'number',
+    },
+    {
+        default: 60_000,
+        description: 'Milliseconds a query may wait for a free query slot before failing',
+        name: 'queryQueueTimeoutMs',
+        required: false,
+        type: 'number',
+    },
 ];
 export default createAuthAddCommand({
     clearClients: closeConnections,

package/dist/commands/mysql/auth/update.js

@@ -7,6 +7,20 @@ const fields = [
     { description: 'Password', name: 'password', type: 'string' },
     { char: 'd', description: 'Database name', name: 'database', type: 'string' },
     { default: false, description: 'Use SSL', name: 'ssl', required: false, type: 'boolean' },
+    {
+        default: 5,
+        description: 'Max concurrent queries for this profile',
+        name: 'maxConcurrentQueries',
+        required: false,
+        type: 'number',
+    },
+    {
+        default: 60_000,
+        description: 'Milliseconds a query may wait for a free query slot before failing',
+        name: 'queryQueueTimeoutMs',
+        required: false,
+        type: 'number',
+    },
 ];
 export default createAuthUpdateCommand({
     clearClients: closeConnections,

package/dist/commands/mysql/describe-table.d.ts

@@ -1,4 +1,4 @@
-import { ApiResult } from '@hesed/plugin-lib';
+import { type ApiResult } from '@hesed/plugin-lib';
 import { BaseCommand } from '../../base-command.js';
 export default class MySQLDescribeTable extends BaseCommand {
     static args: {

package/dist/commands/mysql/explain.d.ts

@@ -1,4 +1,4 @@
-import { ApiResult } from '@hesed/plugin-lib';
+import { type ApiResult } from '@hesed/plugin-lib';
 import { BaseCommand } from '../../base-command.js';
 export default class MySQLExplain extends BaseCommand {
     static args: {

package/dist/commands/mysql/indexes.d.ts

@@ -1,4 +1,4 @@
-import { ApiResult } from '@hesed/plugin-lib';
+import { type ApiResult } from '@hesed/plugin-lib';
 import { BaseCommand } from '../../base-command.js';
 export default class MySQLIndexes extends BaseCommand {
     static args: {

package/dist/commands/mysql/query.d.ts

@@ -1,4 +1,4 @@
-import { ApiResult } from '@hesed/plugin-lib';
+import { type ApiResult } from '@hesed/plugin-lib';
 import { BaseCommand } from '../../base-command.js';
 export default class MySQLQuery extends BaseCommand {
     static args: {

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

@@ -1,23 +1,27 @@
 import type { ConnectionOptions as MySQL2ConnectionOptions } from 'mysql2/promise';
-export interface DatabaseProfile {
+export type DatabaseProfile = {
     database: string;
     host: string;
+    maxConcurrentQueries?: number;
     password: string;
     port: number;
+    queryQueueTimeoutMs?: number;
     ssl?: boolean;
     user: string;
-}
-interface SafetyConfig {
+};
+type SafetyConfig = {
     blacklistedOperations: string[];
     defaultLimit: number;
+    maxConcurrentQueries?: number;
+    queryQueueTimeoutMs?: number;
     requireConfirmationFor: string[];
-}
-export interface MySQLConfig {
+};
+export type MySQLConfig = {
     defaultFormat: 'csv' | 'json' | 'table' | 'toon';
     defaultProfile: string;
     profiles: Record<string, DatabaseProfile>;
     safety: SafetyConfig;
-}
+};
 type MySQLConnectionOptions = Pick<MySQL2ConnectionOptions, 'connectTimeout' | 'database' | 'host' | 'multipleStatements' | 'password' | 'port' | 'ssl' | 'user'>;
 export declare function getMySQLConnectionOptions(config: MySQLConfig, profileName: string): MySQLConnectionOptions;
 export {};

package/dist/mysql/database.d.ts

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

package/dist/mysql/formatters.js

@@ -1,4 +1,5 @@
 import { encode } from '@toon-format/toon';
+import { Buffer } from 'node:buffer';
 function formatAsCsv(rows, fields) {
     if (!rows || rows.length === 0) {
         return '';

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) {
@@ -66,9 +68,10 @@ export async function testDirectConnection(profile) {
     return result;
 }
 export async function closeConnections() {
-    if (mysqlUtil) {
-        await mysqlUtil.closeAll();
-        mysqlUtil = null;
-        cachedConfig = null;
+    if (!mysqlUtil) {
+        return;
     }
+    await mysqlUtil.closeAll();
+    mysqlUtil = null;
+    cachedConfig = null;
 }

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

@@ -1,8 +1,9 @@
-import type { MySQLConfig } from './config-loader.js';
 import type { ConnectionTestResult, DatabaseListResult, DatabaseUtil, ExplainResult, IndexResult, OutputFormat, QueryResult, TableListResult, TableStructureResult } from './database.js';
+import { type MySQLConfig } from './config-loader.js';
 export declare class MySQLUtil implements DatabaseUtil {
-    private config;
-    private connections;
+    private readonly config;
+    private readonly pools;
+    private readonly 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,22 +2,38 @@ 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;
+// Formats that must emit only the data payload on stdout.
+const MACHINE_FORMATS = new Set(['csv', 'json', 'toon']);
+// Query types whose result set is rows rather than an OkPacket.
+const READ_QUERY_TYPES = new Set(['DESCRIBE', 'EXPLAIN', 'SELECT', 'SHOW']);
 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()) {
+            const { waiting } = slot;
+            slot.waiting = [];
+            for (const waiter of waiting) {
+                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(async (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 {
                 data: {
                     result: this.formatRows(rows, fields, format),
@@ -56,7 +72,7 @@ export class MySQLUtil {
         }
         // Machine-readable formats must emit only the data payload on stdout, so
         // analysis warnings and status lines are collected as notices instead.
-        const machineFormat = format === 'json' || format === 'csv' || format === 'toon';
+        const isMachineFormat = MACHINE_FORMATS.has(format);
         const notices = [];
         const warnings = analyzeQuery(query);
         if (warnings.length > 0) {
@@ -72,9 +88,8 @@ export class MySQLUtil {
             }
         }
         try {
-            const connection = await this.getConnection(profileName);
-            const [rows, fields] = await connection.query(finalQuery);
-            const isRead = queryType === 'SELECT' || queryType === 'SHOW' || queryType === 'DESCRIBE' || queryType === 'EXPLAIN';
+            const [rows, fields] = await this.runQuery(profileName, finalQuery);
+            const isRead = READ_QUERY_TYPES.has(queryType);
             let data = isRead
                 ? this.formatReadResult(rows, fields, format, notices)
                 : this.formatWriteResult(rows, notices, format);
@@ -86,8 +101,8 @@ export class MySQLUtil {
             // For machine formats the data is returned alone and notices go to stderr.
             return {
                 data: {
-                    notices: machineFormat ? notice : undefined,
-                    result: machineFormat ? data : `${notice}\n\n${data}`,
+                    notices: isMachineFormat ? notice : undefined,
+                    result: isMachineFormat ? data : `${notice}\n\n${data}`,
                 },
                 success: true,
             };
@@ -102,8 +117,7 @@ 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 {
                 data: {
                     plan: rows,
@@ -122,8 +136,7 @@ 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 {
                 data: {
@@ -143,8 +156,7 @@ 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]);
@@ -166,8 +178,7 @@ 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 {
                 data: {
                     indexes: rows,
@@ -186,8 +197,7 @@ 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 {
                 data: {
@@ -206,6 +216,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.
+    async 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 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}`);
@@ -231,26 +291,37 @@ export class MySQLUtil {
             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();
         }
     }
 }

package/dist/mysql/query-validator.d.ts

@@ -1,16 +1,16 @@
-interface BlacklistCheckResult {
+type BlacklistCheckResult = {
     allowed: boolean;
     reason?: string;
-}
-interface ConfirmationCheckResult {
+};
+type ConfirmationCheckResult = {
     message?: string;
     required: boolean;
-}
-interface QueryWarning {
+};
+type QueryWarning = {
     level: 'info' | 'warning';
     message: string;
     suggestion: string;
-}
+};
 export declare function checkBlacklist(query: string, blacklistedOperations: string[]): BlacklistCheckResult;
 export declare function requiresConfirmation(query: string, confirmationOperations: string[]): ConfirmationCheckResult;
 export declare function getQueryType(query: string): string;

package/dist/mysql/query-validator.js

@@ -26,7 +26,7 @@ export function requiresConfirmation(query, confirmationOperations) {
 }
 export function getQueryType(query) {
     const normalizedQuery = query.trim().toUpperCase();
-    const firstWord = normalizedQuery.split(/\s+/)[0];
+    const firstWord = normalizedQuery.split(/\s+/, 1)[0];
     const knownTypes = [
         'SELECT',
         'INSERT',

package/oclif.manifest.json

@@ -384,6 +384,22 @@
           "required": true,
           "allowNo": false,
           "type": "boolean"
+        },
+        "maxConcurrentQueries": {
+          "description": "Max concurrent queries for this profile",
+          "name": "maxConcurrentQueries",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "queryQueueTimeoutMs": {
+          "description": "Milliseconds a query may wait for a free query slot before failing",
+          "name": "queryQueueTimeoutMs",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -637,6 +653,22 @@
           "required": true,
           "allowNo": false,
           "type": "boolean"
+        },
+        "maxConcurrentQueries": {
+          "description": "Max concurrent queries for this profile",
+          "name": "maxConcurrentQueries",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "queryQueueTimeoutMs": {
+          "description": "Milliseconds a query may wait for a free query slot before failing",
+          "name": "queryQueueTimeoutMs",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -657,5 +689,5 @@
       ]
     }
   },
-  "version": "0.5.2"
+  "version": "0.6.1"
 }

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@hesed/mysql",
   "description": "CLI for MySQL database interaction",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "author": "Hesed",
   "bin": {
     "mq": "./bin/run.js"
   },
   "bugs": "https://github.com/hesedcasa/mysql/issues",
   "dependencies": {
-    "@hesed/plugin-lib": "^0.9.0",
+    "@hesed/plugin-lib": "^0.12.1",
     "@inquirer/prompts": "^8.3.0",
     "@oclif/core": "^4",
     "@toon-format/toon": "^2.1.0",
@@ -23,11 +23,11 @@
     "@types/fs-extra": "^11.0.4",
     "@types/mocha": "^10",
     "@types/node": "^26",
-    "@types/sinon": "^21.0.0",
+    "@types/sinon": "^22.0.0",
     "c8": "^11.0.0",
     "chai": "^6",
-    "eslint": "^9",
-    "eslint-config-oclif": "^6",
+    "eslint": "^10",
+    "eslint-config-oclif": "^7",
     "eslint-config-prettier": "^10",
     "esmock": "^2.7.3",
     "mocha": "^11",
@@ -37,10 +37,11 @@
     "sinon": "^22.0.0",
     "ts-node": "^10",
     "ts-prune": "^0.10.3",
-    "typescript": "^5"
+    "typescript": "^5",
+    "typescript-eslint": "^8.67.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.13.0"
   },
   "files": [
     "./bin",