@pma-network/sql 1.0.9 → 1.2.0

package/dist/MySQL.js

@@ -1,6 +1,9 @@
-import { performance } from 'node:perf_hooks';
-import mysql from 'mysql2/promise';
-import namedPlaceholders from 'named-placeholders';
+import { spawn } from "node:child_process";
+import { createConnection } from "node:net";
+import { performance } from "node:perf_hooks";
+import mysql from "mysql2/promise";
+import namedPlaceholders from "named-placeholders";
+import { typeCast } from "./type-casting.js";
 /**
  * MySQL database wrapper with connection pooling and named parameter support.
  * Automatically reads connection configuration from environment variables.
@@ -12,37 +15,425 @@ export class MySQL {
     slowQueryThreshold;
     resourceName;
     collectMetrics;
-    versionPrefix = '';
+    versionPrefix = "";
     metricsExportResource;
     metricsExportFunction;
+    defaultQueryOptions = {
+        timeout: 15_000,
+        retryCount: 3,
+    };
+    sshProcess = null;
+    initializationPromise = null;
+    schemas = new Map();
+    autoSync = false;
+    syncComplete = false;
     /**
      * Creates a new MySQL instance with connection pooling.
      * If no config is provided, it will automatically look for connection strings in environment variables.
      *
+     * SSH tunnel connections (mysql-ssh://) are supported and initialized automatically.
+     *
      * @param config - Optional database configuration. If omitted, uses environment variables.
      * @throws {Error} If no connection string is found or if connection string validation fails
      */
     constructor(config) {
         this.resourceName = this.getResourceName();
-        this.debug = this.getConvarBool('mysql_debug', false);
-        this.slowQueryThreshold = this.getConvarInt('mysql_slow_query_warning', 150);
-        this.collectMetrics = this.getConvarBool('mysql_query_metrics', false);
-        this.metricsExportResource = this.getConvar('mysql_metrics_export_resource');
-        this.metricsExportFunction = this.getConvar('mysql_metrics_export_function');
+        this.debug = this.getConvarBool("mysql_debug", false);
+        this.slowQueryThreshold = this.getConvarInt("mysql_slow_query_warning", 150);
+        this.collectMetrics = this.getConvarBool("mysql_query_metrics", false);
+        this.metricsExportResource = this.getConvar("mysql_metrics_export_resource");
+        this.metricsExportFunction = this.getConvar("mysql_metrics_export_function");
         this.setupConvarListeners();
+        this.namedPlaceholdersCompiler = namedPlaceholders();
         const finalConfig = config || this.getDefaultConfig();
-        const poolConfig = finalConfig.connectionString
-            ? this.parseConnectionString(finalConfig.connectionString)
-            : finalConfig;
+        // Register schemas from config
+        if (finalConfig.schemas) {
+            for (const [name, schema] of Object.entries(finalConfig.schemas)) {
+                this.schemas.set(name, schema);
+            }
+        }
+        this.autoSync = finalConfig.autoSync ?? false;
+        if (finalConfig.ssh || this.isSSHConnectionString(finalConfig.connectionString)) {
+            this.initializationPromise = this.initializeSSH(finalConfig);
+        }
+        else {
+            this.initializePool(finalConfig);
+            this.fetchServerVersion();
+        }
+    }
+    async initializeSSH(config) {
+        if (this.isSSHConnectionString(config.connectionString)) {
+            await this.initializeFromSSHConnectionString(config.connectionString);
+        }
+        else if (config.ssh) {
+            await this.initializeWithSSH(config, config.ssh);
+        }
+        this.fetchServerVersion();
+    }
+    async ensureInitialized() {
+        if (this.initializationPromise) {
+            await this.initializationPromise;
+        }
+        if (this.autoSync && !this.syncComplete) {
+            await this.sync();
+        }
+    }
+    /**
+     * Defines a table schema that can be synced to the database.
+     *
+     * @param tableName - Name of the table
+     * @param schema - Table schema definition
+     * @example
+     * db.defineSchema('users', {
+     *   columns: {
+     *     id: { type: 'INT', primaryKey: true, autoIncrement: true },
+     *     name: { type: 'VARCHAR(255)', nullable: false },
+     *     email: { type: 'VARCHAR(255)', unique: true },
+     *     created_at: { type: 'TIMESTAMP', default: 'CURRENT_TIMESTAMP' }
+     *   },
+     *   indexes: ['INDEX idx_email (email)']
+     * });
+     *
+     * // Or use shorthand string syntax
+     * db.defineSchema('logs', {
+     *   columns: {
+     *     id: 'INT AUTO_INCREMENT PRIMARY KEY',
+     *     message: 'TEXT NOT NULL',
+     *     level: 'VARCHAR(20) DEFAULT "info"'
+     *   }
+     * });
+     */
+    defineSchema(tableName, schema) {
+        this.schemas.set(tableName, schema);
+        return this;
+    }
+    /**
+     * Syncs all defined schemas to the database, creating tables if they don't exist.
+     *
+     * @returns Promise that resolves when sync is complete
+     * @example
+     * db.defineSchema('users', { ... });
+     * db.defineSchema('posts', { ... });
+     * await db.sync();
+     */
+    async sync() {
+        if (this.initializationPromise) {
+            await this.initializationPromise;
+        }
+        for (const [tableName, schema] of this.schemas) {
+            await this.createTableIfNotExists(tableName, schema);
+        }
+        this.syncComplete = true;
+    }
+    buildColumnDefinition(columnName, column) {
+        if (typeof column === "string") {
+            return `\`${columnName}\` ${column}`;
+        }
+        const parts = [`\`${columnName}\``, column.type];
+        if (column.nullable === false) {
+            parts.push("NOT NULL");
+        }
+        if (column.default !== undefined) {
+            if (column.default === null) {
+                parts.push("DEFAULT NULL");
+            }
+            else if (typeof column.default === "string" &&
+                (column.default.toUpperCase() === "CURRENT_TIMESTAMP" ||
+                    column.default.toUpperCase().startsWith("CURRENT_TIMESTAMP"))) {
+                parts.push(`DEFAULT ${column.default}`);
+            }
+            else if (typeof column.default === "string") {
+                parts.push(`DEFAULT '${column.default}'`);
+            }
+            else if (typeof column.default === "boolean") {
+                parts.push(`DEFAULT ${column.default ? 1 : 0}`);
+            }
+            else {
+                parts.push(`DEFAULT ${column.default}`);
+            }
+        }
+        if (column.autoIncrement) {
+            parts.push("AUTO_INCREMENT");
+        }
+        if (column.unique) {
+            parts.push("UNIQUE");
+        }
+        if (column.primaryKey) {
+            parts.push("PRIMARY KEY");
+        }
+        if (column.references) {
+            let refClause = `REFERENCES ${column.references}`;
+            if (column.onDelete) {
+                refClause += ` ON DELETE ${column.onDelete}`;
+            }
+            if (column.onUpdate) {
+                refClause += ` ON UPDATE ${column.onUpdate}`;
+            }
+            parts.push(refClause);
+        }
+        return parts.join(" ");
+    }
+    async createTableIfNotExists(tableName, schema) {
+        const columnDefs = [];
+        for (const [columnName, column] of Object.entries(schema.columns)) {
+            columnDefs.push(this.buildColumnDefinition(columnName, column));
+        }
+        // Add composite primary key if specified separately
+        if (schema.primaryKey) {
+            const pkColumns = Array.isArray(schema.primaryKey)
+                ? schema.primaryKey
+                : [schema.primaryKey];
+            columnDefs.push(`PRIMARY KEY (${pkColumns.map((c) => `\`${c}\``).join(", ")})`);
+        }
+        // Add indexes
+        if (schema.indexes) {
+            columnDefs.push(...schema.indexes);
+        }
+        const engine = schema.engine || "InnoDB";
+        const charset = schema.charset || "utf8mb4";
+        const collate = schema.collate || "utf8mb4_unicode_ci";
+        const sql = `CREATE TABLE IF NOT EXISTS \`${tableName}\` (
+			${columnDefs.join(",\n\t\t\t")}
+		) ENGINE=${engine} DEFAULT CHARSET=${charset} COLLATE=${collate}`;
+        await this.rawExecute(sql);
+        if (this.debug) {
+            console.log(`^2Schema synced: ${tableName}^0`);
+        }
+    }
+    /**
+     * Creates a new MySQL instance with SSH tunnel support.
+     * Use this factory method when connecting through an SSH bastion/jump host.
+     *
+     * Supports two formats:
+     * 1. Separate SSH config object
+     * 2. mysql-ssh:// connection string (uses SSH_AUTH_SOCK for auth by default)
+     *
+     * @param config - Database configuration with SSH tunnel settings
+     * @returns Promise resolving to a MySQL instance connected through SSH tunnel
+     * @throws {Error} If SSH connection fails
+     * @throws {Error} If no connection string is found
+     * @example
+     * // Using mysql-ssh:// URL (recommended for 1Password/ssh-agent)
+     * const db = await MySQL.createWithSSH({
+     *   connectionString: 'mysql-ssh://deploy@bastion.example.com/mydb?user=admin&password=secret'
+     * });
+     *
+     * // Using separate SSH config
+     * const db = await MySQL.createWithSSH({
+     *   connectionString: 'mysql://user:pass@localhost:3306/database',
+     *   ssh: {
+     *     host: 'bastion.example.com',
+     *     username: 'ssh-user',
+     *   }
+     * });
+     */
+    static async createWithSSH(config) {
+        const instance = Object.create(MySQL.prototype);
+        instance.resourceName = instance.getResourceName();
+        instance.debug = instance.getConvarBool("mysql_debug", false);
+        instance.slowQueryThreshold = instance.getConvarInt("mysql_slow_query_warning", 150);
+        instance.collectMetrics = instance.getConvarBool("mysql_query_metrics", false);
+        instance.metricsExportResource = instance.getConvar("mysql_metrics_export_resource");
+        instance.metricsExportFunction = instance.getConvar("mysql_metrics_export_function");
+        instance.defaultQueryOptions = { timeout: 15_000, retryCount: 3 };
+        instance.sshProcess = null;
+        instance.setupConvarListeners();
+        instance.namedPlaceholdersCompiler = namedPlaceholders();
+        const finalConfig = config || instance.getDefaultConfig();
+        if (instance.isSSHConnectionString(finalConfig.connectionString)) {
+            await instance.initializeFromSSHConnectionString(finalConfig.connectionString);
+        }
+        else if (finalConfig.ssh) {
+            await instance.initializeWithSSH(finalConfig, finalConfig.ssh);
+        }
+        else {
+            instance.initializePool(finalConfig);
+        }
+        instance.fetchServerVersion();
+        return instance;
+    }
+    isSSHConnectionString(connectionString) {
+        return connectionString?.startsWith("mysql-ssh://") ?? false;
+    }
+    /**
+     * Parses a mysql-ssh:// connection string into SSH and MySQL configs.
+     *
+     * Format: mysql-ssh://sshuser@sshhost[:sshport]/database?user=dbuser&password=dbpass[&host=dbhost][&port=dbport]
+     *
+     * @example
+     * mysql-ssh://deploy@bastion.example.com/mydb?user=admin&password=secret
+     * mysql-ssh://deploy@bastion.example.com:2222/mydb?user=admin&password=secret&host=internal-db&port=3307
+     */
+    parseSSHConnectionString(connectionString) {
+        const url = new URL(connectionString.replace("mysql-ssh://", "http://"));
+        if (!url.username) {
+            throw new Error("mysql-ssh:// URL must include SSH username (e.g., mysql-ssh://user@host/db)");
+        }
+        const dbUser = url.searchParams.get("user");
+        const dbPassword = url.searchParams.get("password");
+        const dbHost = url.searchParams.get("host") || "127.0.0.1";
+        const dbPort = url.searchParams.get("port");
+        const connectionLimit = url.searchParams.get("connectionLimit");
+        const charset = url.searchParams.get("charset");
+        if (!dbUser) {
+            throw new Error("mysql-ssh:// URL must include database user (e.g., ?user=dbuser&password=dbpass)");
+        }
+        const mysqlOptions = {
+            host: dbHost,
+            port: dbPort ? parseInt(dbPort, 10) : 3306,
+            user: dbUser,
+            password: dbPassword || undefined,
+            database: url.pathname.slice(1),
+        };
+        if (connectionLimit) {
+            mysqlOptions.connectionLimit = parseInt(connectionLimit, 10);
+        }
+        if (charset) {
+            mysqlOptions.charset = charset;
+        }
+        return {
+            ssh: {
+                host: url.hostname,
+                port: url.port ? parseInt(url.port, 10) : 22,
+                username: url.username,
+            },
+            mysql: mysqlOptions,
+        };
+    }
+    initializePool(config) {
+        const poolConfig = config.connectionString
+            ? this.parseConnectionString(config.connectionString)
+            : config;
         this.pool = mysql.createPool({
             waitForConnections: true,
             connectionLimit: 10,
             queueLimit: 0,
-            idleTimeout: 300_000,
+            typeCast: typeCast,
             ...poolConfig,
         });
-        this.namedPlaceholdersCompiler = namedPlaceholders();
-        this.fetchServerVersion();
+    }
+    async initializeWithSSH(config, sshConfig) {
+        const poolConfig = config.connectionString
+            ? this.parseConnectionString(config.connectionString)
+            : config;
+        const dbHost = poolConfig.host || "127.0.0.1";
+        const dbPort = poolConfig.port || 3306;
+        const { localPort } = await this.createSSHTunnel(sshConfig, dbHost, dbPort);
+        this.pool = mysql.createPool({
+            waitForConnections: true,
+            connectionLimit: 10,
+            queueLimit: 0,
+            typeCast: typeCast,
+            ...poolConfig,
+            host: "127.0.0.1",
+            port: localPort,
+        });
+    }
+    async initializeFromSSHConnectionString(connectionString) {
+        const { ssh, mysql: mysqlConfig } = this.parseSSHConnectionString(connectionString);
+        const dbHost = mysqlConfig.host || "127.0.0.1";
+        const dbPort = mysqlConfig.port || 3306;
+        const { localPort } = await this.createSSHTunnel(ssh, dbHost, dbPort);
+        this.pool = mysql.createPool({
+            waitForConnections: true,
+            connectionLimit: 10,
+            queueLimit: 0,
+            typeCast: typeCast,
+            ...mysqlConfig,
+            host: "127.0.0.1",
+            port: localPort,
+        });
+    }
+    async createSSHTunnel(sshConfig, dbHost, dbPort) {
+        // Find an available local port by briefly binding to port 0
+        const localPort = await new Promise((resolve, reject) => {
+            const srv = require("node:net").createServer();
+            srv.listen(0, "127.0.0.1", () => {
+                const port = srv.address()?.port;
+                srv.close(() => resolve(port));
+            });
+            srv.on("error", reject);
+        });
+        const sshPort = sshConfig.port || 22;
+        const args = [
+            "-N",
+            "-L",
+            `${localPort}:${dbHost}:${dbPort}`,
+            "-p",
+            String(sshPort),
+            "-o",
+            "StrictHostKeyChecking=accept-new",
+            "-o",
+            "ExitOnForwardFailure=yes",
+        ];
+        if (sshConfig.privateKey) {
+            const keyPath = typeof sshConfig.privateKey === "string"
+                ? sshConfig.privateKey
+                : undefined;
+            if (keyPath) {
+                args.push("-i", keyPath);
+            }
+        }
+        if (sshConfig.agent === false) {
+            args.push("-o", "IdentityAgent=none");
+        }
+        else if (typeof sshConfig.agent === "string") {
+            args.push("-o", `IdentityAgent=${sshConfig.agent}`);
+        }
+        args.push(`${sshConfig.username}@${sshConfig.host}`);
+        this.sshProcess = spawn("ssh", args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                ...(typeof sshConfig.agent === "string"
+                    ? { SSH_AUTH_SOCK: sshConfig.agent }
+                    : {}),
+            },
+        });
+        // Wait for the tunnel to be ready by attempting to connect to the local port
+        await new Promise((resolve, reject) => {
+            const sshProc = this.sshProcess;
+            let stderr = "";
+            sshProc.stderr?.on("data", (data) => {
+                stderr += data.toString();
+            });
+            sshProc.on("error", (err) => {
+                reject(new Error(`Failed to spawn ssh: ${err.message}. Is OpenSSH installed?`));
+            });
+            sshProc.on("close", (code) => {
+                if (code !== null && code !== 0) {
+                    reject(new Error(`SSH tunnel exited with code ${code}: ${stderr.trim()}`));
+                }
+            });
+            // Poll until the tunnel port is accepting connections
+            const maxAttempts = 50;
+            let attempt = 0;
+            const tryConnect = () => {
+                attempt++;
+                const sock = createConnection({ host: "127.0.0.1", port: localPort });
+                sock.on("connect", () => {
+                    sock.destroy();
+                    console.log(`^2SSH tunnel established on port ${localPort}^0`);
+                    resolve();
+                });
+                sock.on("error", () => {
+                    sock.destroy();
+                    if (attempt >= maxAttempts) {
+                        sshProc.kill();
+                        reject(new Error(`SSH tunnel failed to become ready after ${maxAttempts} attempts: ${stderr.trim()}`));
+                    }
+                    else {
+                        setTimeout(tryConnect, 100);
+                    }
+                });
+            };
+            // Give ssh a moment to start before polling
+            setTimeout(tryConnect, 200);
+        });
+        return { localPort };
+    }
+    getQueryOption(option) {
+        return option ?? this.defaultQueryOptions;
     }
     async fetchServerVersion() {
         try {
@@ -62,13 +453,13 @@ export class MySQL {
     // This wrapper is meant to be usable for our Node.js code since it has way better
     // ergonmoics, so we have to test that GetConvar exists before trying to do anything else
     getConvar(varName) {
-        if (typeof globalThis.GetConvar === 'function') {
-            return globalThis.GetConvar(varName, '') || null;
+        if (typeof globalThis.GetConvar === "function") {
+            return globalThis.GetConvar(varName, "") || null;
         }
         return process.env[varName] || null;
     }
     getConvarInt(varName, defaultValue) {
-        if (typeof globalThis.GetConvarInt === 'function') {
+        if (typeof globalThis.GetConvarInt === "function") {
             return globalThis.GetConvarInt(varName, defaultValue);
         }
         const envValue = process.env[varName];
@@ -79,23 +470,23 @@ export class MySQL {
         return defaultValue;
     }
     getConvarBool(varName, defaultValue) {
-        if (typeof globalThis.GetConvarBool === 'function') {
+        if (typeof globalThis.GetConvarBool === "function") {
             return globalThis.GetConvarBool(varName, defaultValue);
         }
         const envValue = process.env[varName];
         if (envValue !== undefined) {
-            return envValue === 'true' || envValue === '1';
+            return envValue === "true" || envValue === "1";
         }
         return defaultValue;
     }
     getResourceName() {
-        if (typeof globalThis.GetCurrentResourceName === 'function') {
+        if (typeof globalThis.GetCurrentResourceName === "function") {
             return globalThis.GetCurrentResourceName() || null;
         }
-        return this.getConvar('RESOURCE_NAME');
+        return this.getConvar("RESOURCE_NAME");
     }
     formatResourceConvar(resourceName) {
-        return resourceName.replace(/-/g, '_').toLowerCase();
+        return resourceName.replace(/-/g, "_").toLowerCase();
     }
     /**
      * Gets default configuration from environment variables.
@@ -107,20 +498,31 @@ export class MySQL {
     getDefaultConfig() {
         let connectionString = null;
         const resourceName = this.getResourceName();
-        if (resourceName) {
-            const resourceConvar = this.formatResourceConvar(resourceName);
+        const resourceConvar = resourceName
+            ? this.formatResourceConvar(resourceName)
+            : null;
+        // Check for SSH connection string first (takes priority)
+        if (resourceConvar) {
+            connectionString = this.getConvar(`${resourceConvar}_ssh_connection_string`);
+        }
+        if (!connectionString) {
+            connectionString = this.getConvar("mysql_ssh_connection_string");
+        }
+        // Fall back to regular connection string
+        if (!connectionString && resourceConvar) {
             connectionString = this.getConvar(`${resourceConvar}_connection_string`);
         }
         if (!connectionString) {
-            connectionString = this.getConvar('mysql_connection_string');
+            connectionString = this.getConvar("mysql_connection_string");
         }
         if (!connectionString) {
-            const resourceHint = resourceName
-                ? `\nTried: ${this.formatResourceConvar(resourceName)}_connection_string and mysql_connection_string`
-                : '\nTried: mysql_connection_string';
-            throw new Error('No MySQL connection string found. ' +
-                'Please set a connection string: ' +
-                'mysql://user:password@host:port/database' +
+            const resourceHint = resourceConvar
+                ? `\nTried: ${resourceConvar}_ssh_connection_string, mysql_ssh_connection_string, ${resourceConvar}_connection_string, mysql_connection_string`
+                : "\nTried: mysql_ssh_connection_string, mysql_connection_string";
+            throw new Error("No MySQL connection string found. " +
+                "Please set a connection string: " +
+                "mysql://user:password@host:port/database or " +
+                "mysql-ssh://sshuser@sshhost/database?user=dbuser&password=dbpass" +
                 resourceHint);
         }
         this.validateConnectionString(connectionString);
@@ -137,25 +539,29 @@ export class MySQL {
      * @throws {Error} If connection string format is invalid
      */
     validateConnectionString(connectionString) {
+        // mysql-ssh:// URLs are validated separately during parsing
+        if (this.isSSHConnectionString(connectionString)) {
+            return;
+        }
         try {
             const url = new URL(connectionString);
-            if (url.protocol !== 'mysql:') {
-                throw new Error(`Invalid protocol "${url.protocol}". Expected "mysql:". ` +
-                    'Connection string must start with mysql://');
+            if (url.protocol !== "mysql:") {
+                throw new Error(`Invalid protocol "${url.protocol}". Expected "mysql:" or "mysql-ssh:". ` +
+                    "Connection string must start with mysql:// or mysql-ssh://");
             }
             if (!url.hostname) {
-                throw new Error('Connection string must include a hostname');
+                throw new Error("Connection string must include a hostname");
             }
-            if (!url.pathname || url.pathname === '/') {
-                throw new Error('Connection string must include a database name');
+            if (!url.pathname || url.pathname === "/") {
+                throw new Error("Connection string must include a database name");
             }
             if (!url.username) {
-                throw new Error('Connection string must include a username');
+                throw new Error("Connection string must include a username");
             }
         }
         catch (error) {
             if (error instanceof TypeError) {
-                throw new Error('Invalid connection string format. Expected: mysql://user:password@host:port/database');
+                throw new Error("Invalid connection string format. Expected: mysql://user:password@host:port/database");
             }
             throw error;
         }
@@ -169,13 +575,22 @@ export class MySQL {
      */
     parseConnectionString(connectionString) {
         const url = new URL(connectionString);
-        return {
+        const connectionLimit = url.searchParams.get("connectionLimit");
+        const charset = url.searchParams.get("charset");
+        const options = {
             host: url.hostname,
             port: url.port ? parseInt(url.port, 10) : 3306,
             user: url.username,
             password: url.password,
             database: url.pathname.slice(1),
         };
+        if (connectionLimit) {
+            options.connectionLimit = parseInt(connectionLimit, 10);
+        }
+        if (charset) {
+            options.charset = charset;
+        }
+        return options;
     }
     normalizeParameters(parameters) {
         if (Array.isArray(parameters)) {
@@ -194,50 +609,76 @@ export class MySQL {
         }
     }
     setupConvarListeners() {
-        if (typeof globalThis.AddConvarChangeListener === 'function') {
-            globalThis.AddConvarChangeListener('mysql_*', (convarName) => {
-                if (convarName === 'mysql_debug') {
-                    this.debug = this.getConvarBool('mysql_debug', false);
+        if (typeof globalThis.AddConvarChangeListener === "function") {
+            globalThis.AddConvarChangeListener("mysql_*", (convarName) => {
+                if (convarName === "mysql_debug") {
+                    this.debug = this.getConvarBool("mysql_debug", false);
                     console.log(`^2Convar changed: mysql_debug = ${this.debug}^0`);
                 }
-                else if (convarName === 'mysql_slow_query_warning') {
-                    this.slowQueryThreshold = this.getConvarInt('mysql_slow_query_warning', 150);
+                else if (convarName === "mysql_slow_query_warning") {
+                    this.slowQueryThreshold = this.getConvarInt("mysql_slow_query_warning", 150);
                     console.log(`^2Convar changed: mysql_slow_query_warning = ${this.slowQueryThreshold}^0`);
                 }
-                else if (convarName === 'mysql_query_metrics') {
-                    this.collectMetrics = this.getConvarBool('mysql_query_metrics', false);
+                else if (convarName === "mysql_query_metrics") {
+                    this.collectMetrics = this.getConvarBool("mysql_query_metrics", false);
                     console.log(`^2Convar changed: mysql_query_metrics = ${this.collectMetrics}^0`);
                 }
-                else if (convarName === 'mysql_metrics_export_resource') {
-                    this.metricsExportResource = this.getConvar('mysql_metrics_export_resource');
+                else if (convarName === "mysql_metrics_export_resource") {
+                    this.metricsExportResource = this.getConvar("mysql_metrics_export_resource");
                     console.log(`^2Convar changed: mysql_metrics_export_resource = ${this.metricsExportResource}^0`);
                 }
-                else if (convarName === 'mysql_metrics_export_function') {
-                    this.metricsExportFunction = this.getConvar('mysql_metrics_export_function');
+                else if (convarName === "mysql_metrics_export_function") {
+                    this.metricsExportFunction = this.getConvar("mysql_metrics_export_function");
                     console.log(`^2Convar changed: mysql_metrics_export_function = ${this.metricsExportFunction}^0`);
                 }
             });
         }
     }
     scheduleResourceTick() {
-        if (typeof globalThis.ScheduleResourceTick === 'function' && this.resourceName) {
+        if (typeof globalThis.ScheduleResourceTick === "function" &&
+            this.resourceName) {
             globalThis.ScheduleResourceTick(this.resourceName);
         }
     }
-    async executeWithTiming(processedQuery, processedParams, executor) {
-        const startTime = performance.now();
-        try {
-            const result = await executor();
-            const executionTime = performance.now() - startTime;
-            this.logQuery(processedQuery, executionTime, processedParams);
-            return result;
+    isTimeoutError(error) {
+        if (error instanceof Error) {
+            const mysqlError = error;
+            return (mysqlError.code === "PROTOCOL_SEQUENCE_TIMEOUT" ||
+                mysqlError.message?.includes("timeout"));
         }
-        catch (error) {
-            const executionTime = performance.now() - startTime;
-            this.logQuery(processedQuery, executionTime, processedParams, error);
-            this.handleError(error);
-            return null;
+        return false;
+    }
+    async executePoolMethod(method, query, params, resultMapper, options) {
+        await this.ensureInitialized();
+        this.scheduleResourceTick();
+        const queryOptions = this.getQueryOption(options);
+        let lastError;
+        for (let attempt = 0; attempt <= queryOptions.retryCount; attempt++) {
+            const startTime = performance.now();
+            try {
+                const poolMethod = method === "execute"
+                    ? this.pool.execute.bind(this.pool)
+                    : this.pool.query.bind(this.pool);
+                const [result] = await poolMethod({ timeout: queryOptions.timeout, sql: query }, params);
+                const executionTime = performance.now() - startTime;
+                this.logQuery(query, executionTime, params);
+                return resultMapper(result);
+            }
+            catch (error) {
+                lastError = error;
+                const executionTime = performance.now() - startTime;
+                if (this.isTimeoutError(error) && attempt < queryOptions.retryCount) {
+                    this.logQuery(query, executionTime, params, error);
+                    console.log(`^3Timeout on attempt ${attempt + 1}/${queryOptions.retryCount + 1}, retrying...^0`);
+                    continue;
+                }
+                this.logQuery(query, executionTime, params, error);
+                this.handleError(error);
+                return null;
+            }
         }
+        this.handleError(lastError);
+        return null;
     }
     exportMetric(metric) {
         if (this.metricsExportResource && this.metricsExportFunction) {
@@ -248,7 +689,7 @@ export class MySQL {
         }
     }
     replaceAtSymbols(query) {
-        return query.replace(/@/g, ':');
+        return query.replace(/@/g, ":");
     }
     /**
      * Executes a query on a specific connection with timing and logging.
@@ -259,12 +700,13 @@ export class MySQL {
      * @returns Query result
      * @throws Query execution errors (SQL errors, syntax errors, constraint violations, etc.)
      */
-    async executeInConnection(connection, query, parameters) {
+    async executeInConnection(connection, query, parameters, queryOptions) {
         this.scheduleResourceTick();
         const [processedQuery, processedParams] = this.processParameters(query, parameters);
         const startTime = performance.now();
         try {
-            const [result] = await connection.execute(processedQuery, processedParams);
+            const options = this.getQueryOption(queryOptions);
+            const [result] = await connection.execute({ ...options, sql: processedQuery }, processedParams);
             const executionTime = performance.now() - startTime;
             this.logQuery(processedQuery, executionTime, processedParams);
             return result;
@@ -276,6 +718,7 @@ export class MySQL {
         }
     }
     async executeTransaction(callback) {
+        await this.ensureInitialized();
         this.scheduleResourceTick();
         const connection = await this.pool.getConnection();
         try {
@@ -317,26 +760,26 @@ export class MySQL {
         }
         const isSlowQuery = executionTime >= this.slowQueryThreshold;
         if (this.debug || isSlowQuery || error) {
-            const resourceName = this.resourceName || 'pma-sql';
+            const resourceName = this.resourceName || "pma-sql";
             let color;
             let statusText;
             if (error) {
-                color = '^1';
+                color = "^1";
                 statusText = `${this.versionPrefix}${color}Query failed^0`;
             }
             else {
-                color = isSlowQuery ? '^3' : '^2';
+                color = isSlowQuery ? "^3" : "^2";
                 statusText = `${this.versionPrefix}${color}${resourceName} took ${executionTime.toFixed(4)}ms to execute a query!^0`;
             }
             console.log(statusText);
-            console.log(`${color}${query} [${parameters && parameters.length > 0 ? parameters.join(',') : ''}]^0`);
+            console.log(`${color}${query} [${parameters && parameters.length > 0 ? parameters.join(",") : ""}]^0`);
             if (error) {
                 console.log(`^1Error: ${error.message}^0`);
             }
         }
     }
     handleError(error) {
-        if (typeof globalThis.printError === 'function') {
+        if (typeof globalThis.printError === "function") {
             globalThis.printError(error);
         }
         else {
@@ -354,13 +797,8 @@ export class MySQL {
      * @example
      * const result = await db.rawExecute('SELECT * FROM users WHERE uid = ?', [1]);
      */
-    async rawExecute(query, parameters) {
-        this.scheduleResourceTick();
-        const params = parameters || [];
-        return this.executeWithTiming(query, params, async () => {
-            const [results] = await this.pool.execute(query, params);
-            return results;
-        });
+    async rawExecute(query, parameters, queryOptions) {
+        return this.executePoolMethod("execute", query, parameters || [], (result) => result, queryOptions);
     }
     /**
      * Executes a SQL query and returns the raw results.
@@ -369,13 +807,14 @@ export class MySQL {
      *
      * @param query - SQL query with :name or ? placeholders
      * @param parameters - Parameter values as object or array
+     * @param queryOptions - Query options to use for this query
      * @returns Query result
      * @example
      * const result = await db.execute('SELECT * FROM users WHERE uid = :uid', { uid: 1 });
      */
-    async execute(query, parameters) {
+    async execute(query, parameters, queryOptions) {
         const [processedQuery, processedParams] = this.processParameters(query, parameters);
-        return this.rawExecute(processedQuery, processedParams);
+        return this.rawExecute(processedQuery, processedParams, queryOptions);
     }
     /**
      * Executes a SELECT query with raw positional parameters.
@@ -384,17 +823,13 @@ export class MySQL {
      *
      * @param query - SELECT query with ? placeholders only
      * @param parameters - Array of values (undefined values are NOT converted to null)
+     * @param queryOptions - Query options to use for this query
      * @returns Array of rows
      * @example
      * const users = await db.rawQuery('SELECT * FROM users WHERE job_name = ?', ['police']);
      */
-    async rawQuery(query, parameters) {
-        this.scheduleResourceTick();
-        const params = parameters || [];
-        return this.executeWithTiming(query, params, async () => {
-            const [rows] = await this.pool.query(query, params);
-            return rows;
-        });
+    async rawQuery(query, parameters, queryOptions) {
+        return this.executePoolMethod("query", query, parameters || [], (result) => result, queryOptions);
     }
     /**
      * Executes a SELECT query and returns rows.
@@ -407,9 +842,9 @@ export class MySQL {
      * @example
      * const users = await db.query('SELECT * FROM users WHERE job_name = :job', { job: 'police' });
      */
-    async query(query, parameters) {
+    async query(query, parameters, queryOptions) {
         const [processedQuery, processedParams] = this.processParameters(query, parameters);
-        return this.rawQuery(processedQuery, processedParams);
+        return this.rawQuery(processedQuery, processedParams, queryOptions);
     }
     /**
      * Inserts a row with raw positional parameters.
@@ -418,17 +853,13 @@ export class MySQL {
      *
      * @param query - INSERT query with ? placeholders only
      * @param parameters - Array of values (undefined values are NOT converted to null)
+     * @param queryOptions - Query options to use for this query
      * @returns Insert ID or null on error
      * @example
      * const insertId = await db.rawInsert('INSERT INTO users (identifier_id, char_data_id, first_name, last_name, inventory_id) VALUES (?, ?, ?, ?, ?)', [1, 1, 'John', 'Doe', 1]);
      */
-    async rawInsert(query, parameters) {
-        this.scheduleResourceTick();
-        const params = parameters || [];
-        return this.executeWithTiming(query, params, async () => {
-            const [result] = await this.pool.execute(query, params);
-            return result.insertId;
-        });
+    async rawInsert(query, parameters, queryOptions) {
+        return this.executePoolMethod("execute", query, parameters || [], (result) => result.insertId, queryOptions);
     }
     /**
      * Inserts a row into the database.
@@ -437,6 +868,7 @@ export class MySQL {
      *
      * @param query - INSERT query with :name or ? placeholders
      * @param parameters - Values to insert
+     * @param queryOptions - Query options to use for this query
      * @returns Insert ID or null on error
      * @example
      * const insertId = await db.insert(
@@ -444,9 +876,9 @@ export class MySQL {
      *   { identifier_id: 1, char_data_id: 1, first_name: 'John', last_name: 'Doe', inventory_id: 1 }
      * );
      */
-    async insert(query, parameters) {
+    async insert(query, parameters, queryOptions) {
         const [processedQuery, processedParams] = this.processParameters(query, parameters);
-        return this.rawInsert(processedQuery, processedParams);
+        return this.rawInsert(processedQuery, processedParams, queryOptions);
     }
     /**
      * Updates rows with raw positional parameters.
@@ -455,17 +887,13 @@ export class MySQL {
      *
      * @param query - UPDATE query with ? placeholders only
      * @param parameters - Array of values (undefined values are NOT converted to null)
+     * @param queryOptions - Query options to use for this query
      * @returns Number of affected rows or null on error
      * @example
      * const affectedRows = await db.rawUpdate('UPDATE users SET job_name = ?, job_rank = ? WHERE uid = ?', ['police', 1, 123]);
      */
-    async rawUpdate(query, parameters) {
-        this.scheduleResourceTick();
-        const params = parameters || [];
-        return this.executeWithTiming(query, params, async () => {
-            const [result] = await this.pool.execute(query, params);
-            return result.affectedRows;
-        });
+    async rawUpdate(query, parameters, queryOptions) {
+        return this.executePoolMethod("execute", query, parameters || [], (result) => result.affectedRows, queryOptions);
     }
     /**
      * Updates rows in the database.
@@ -474,6 +902,7 @@ export class MySQL {
      *
      * @param query - UPDATE query with :name or ? placeholders
      * @param parameters - Values to update
+     * @param queryOptions - Query options to use for this query
      * @returns Number of affected rows or null on error
      * @example
      * const affectedRows = await db.update(
@@ -481,9 +910,9 @@ export class MySQL {
      *   { job: 'police', rank: 1, uid: 123 }
      * );
      */
-    async update(query, parameters) {
+    async update(query, parameters, queryOptions) {
         const [processedQuery, processedParams] = this.processParameters(query, parameters);
-        return this.rawUpdate(processedQuery, processedParams);
+        return this.rawUpdate(processedQuery, processedParams, queryOptions);
     }
     /**
      * Returns a single value with raw positional parameters.
@@ -492,22 +921,19 @@ export class MySQL {
      *
      * @param query - SELECT query with ? placeholders only, returning one column
      * @param parameters - Array of values (undefined values are NOT converted to null)
+     * @param queryOptions - Query options to use for this query
      * @returns Value from first column of first row, or null
      * @example
      * const count = await db.rawScalar('SELECT COUNT(*) FROM users WHERE age > ?', [18]);
      */
-    async rawScalar(query, parameters) {
-        this.scheduleResourceTick();
-        const params = parameters || [];
-        return this.executeWithTiming(query, params, async () => {
-            const [rows] = await this.pool.query(query, params);
+    async rawScalar(query, parameters, queryOptions) {
+        return this.executePoolMethod("query", query, parameters || [], (rows) => {
             if (!rows || rows.length === 0) {
                 return null;
             }
             const firstRow = rows[0];
-            const firstColumn = Object.values(firstRow)[0];
-            return firstColumn;
-        });
+            return Object.values(firstRow)[0];
+        }, queryOptions);
     }
     /**
      * Returns a single value from the database.
@@ -516,14 +942,15 @@ export class MySQL {
      *
      * @param query - SELECT query returning one column
      * @param parameters - Parameter values
+     * @param queryOptions - Query options to use for this query
      * @returns Value from first column of first row, or null
      * @example
      * const count = await db.scalar('SELECT COUNT(*) FROM users');
      * const name = await db.scalar('SELECT name FROM users WHERE id = :id', { id: 1 });
      */
-    async scalar(query, parameters) {
+    async scalar(query, parameters, queryOptions) {
         const [processedQuery, processedParams] = this.processParameters(query, parameters);
-        return this.rawScalar(processedQuery, processedParams);
+        return this.rawScalar(processedQuery, processedParams, queryOptions);
     }
     /**
      * Returns a single row with raw positional parameters.
@@ -532,17 +959,13 @@ export class MySQL {
      *
      * @param query - SELECT query with ? placeholders only
      * @param parameters - Array of values (undefined values are NOT converted to null)
+     * @param queryOptions - Query options to use for this query
      * @returns Single row or null
      * @example
      * const user = await db.rawSingle('SELECT * FROM users WHERE id = ?', [1]);
      */
-    async rawSingle(query, parameters) {
-        this.scheduleResourceTick();
-        const params = parameters || [];
-        return this.executeWithTiming(query, params, async () => {
-            const [rows] = await this.pool.query(query, params);
-            return rows.length > 0 ? rows[0] : null;
-        });
+    async rawSingle(query, parameters, queryOptions) {
+        return this.executePoolMethod("query", query, parameters || [], (rows) => (rows.length > 0 ? rows[0] : null), queryOptions);
     }
     /**
      * Returns a single row from the database.
@@ -551,6 +974,7 @@ export class MySQL {
      *
      * @param query - SELECT query with :name or ? placeholders
      * @param parameters - Parameter values
+     * @param queryOptions - Query options to use for this query
      * @returns Single row or null
      * @example
      * const user = await db.single('SELECT * FROM users WHERE id = :id', { id: 1 });
@@ -558,9 +982,9 @@ export class MySQL {
      *   console.log(user.name);
      * }
      */
-    async single(query, parameters) {
+    async single(query, parameters, queryOptions) {
         const [processedQuery, processedParams] = this.processParameters(query, parameters);
-        return this.rawSingle(processedQuery, processedParams);
+        return this.rawSingle(processedQuery, processedParams, queryOptions);
     }
     /**
      * Executes multiple queries as an atomic transaction.
@@ -625,10 +1049,11 @@ export class MySQL {
      * }
      */
     async getConnection() {
+        await this.ensureInitialized();
         return this.pool.getConnection();
     }
     /**
-     * Closes all connections in the pool.
+     * Closes all connections in the pool and SSH tunnel if active.
      * Call when shutting down the application.
      *
      * @throws {Error} If pool fails to close connections
@@ -636,7 +1061,12 @@ export class MySQL {
      * await db.end();
      */
     async end() {
+        await this.ensureInitialized();
         await this.pool.end();
+        if (this.sshProcess) {
+            this.sshProcess.kill();
+            this.sshProcess = null;
+        }
     }
     /**
      * Returns the underlying mysql2 connection pool.