@spinajs/orm-mysql 2.0.481 → 2.0.482

package/README.md

@@ -1,11 +1,103 @@
-# `orm-mysql`
+# `@spinajs/orm-mysql`
 
-> TODO: description
+The MySQL / MariaDB dialect driver for [`@spinajs/orm`](../orm), built on
+[`@spinajs/orm-sql`](../orm-sql). Ships two drivers: `MySqlOrmDriver`, and `MySqlSSHOrmDriver`
+which tunnels the connection over SSH.
+
+## Install
+
+```bash
+npm install @spinajs/orm @spinajs/orm-mysql
+```
 
 ## Usage
 
+```ts
+import { DI } from '@spinajs/di';
+import { Orm } from '@spinajs/orm';
+import { MySqlOrmDriver } from '@spinajs/orm-mysql';
+
+DI.register(MySqlOrmDriver).as('orm-driver-mysql');
+await DI.resolve(Orm);
 ```
-const ormMysql = require('orm-mysql');
 
-// TODO: DEMONSTRATE API
+```ts
+// configuration
+{
+  db: {
+    DefaultConnection: 'mysql',
+    Connections: [
+      {
+        Name: 'mysql',
+        Driver: 'orm-driver-mysql',
+        Host: '127.0.0.1',
+        Port: 3306,
+        User: 'app',
+        Password: 'secret',
+        Database: 'app',
+        Encoding: 'utf8mb4',
+        Pool: { Min: 2, Max: 20 },
+        Migration: { OnStartup: true },
+      },
+    ],
+  },
+}
 ```
+
+## What is distinctive
+
+- **`insertIdIsFirstOfBatch: true`** — the only driver where it holds. For a *simple* insert
+  (`INSERT ... VALUES (...), (...)`, the only shape the builder produces) InnoDB reserves one
+  contiguous block of auto-increment values and `LAST_INSERT_ID()` reports the first, so a
+  multi-row insert's keys can be read as `LAST_INSERT_ID() + index`. The ORM applies six guards
+  before relying on it.
+- **No `RETURNING`** — `InsertQueryBuilder.returning()` throws `NotSupported` rather than
+  silently doing nothing.
+- **Database events are supported**, and **all four isolation levels** are honoured.
+- **Retries are suppressed inside a transaction** — replaying a statement after reconnecting
+  would apply it outside the transaction.
+- **DDL is not transactional.** `Migration.Transaction.Mode = PerMigration` cannot roll back a
+  `CREATE TABLE`.
+
+Only two compiler overrides are needed (`TableExistsCompiler`, `ServerResponseMapper`), which is
+a fair measure of how closely the generic SQL layer tracks MySQL.
+
+## SSH tunnelling
+
+```ts
+DI.register(MySqlSSHOrmDriver).as('orm-driver-mysql-ssh');
+```
+
+```ts
+{
+  Name: 'remote',
+  Driver: 'orm-driver-mysql-ssh',
+  Host: '10.0.0.5', Port: 3306,
+  User: 'app', Password: 'secret', Database: 'app',
+  SSH: { Host: 'bastion.example.com', Port: 22, User: 'deploy', PrivateKey: '/home/deploy/.ssh/id_rsa' },
+}
+```
+
+The forward uses local port `12345`, so a second tunnelled connection in the same process will
+collide, and the private key must be unencrypted.
+
+## Documentation
+
+Full documentation lives in **[docs/](docs/)**.
+
+| | Page |
+| --- | --- |
+| 01 | [Configuration](docs/01-configuration.md) |
+| 02 | [Dialect notes](docs/02-dialect-notes.md) |
+
+## Development
+
+```bash
+npm test                                   # unit suite, no server needed
+
+docker compose --profile test up -d mysql  # from the repo root
+npm run test:integration
+```
+
+The container publishes MySQL on host port **3900**, deliberately not 3306, so it cannot collide
+with a locally installed MySQL. See the [repository README](../../README.md).

package/lib/cjs/index.d.ts

@@ -1,31 +1,60 @@
-import { QueryContext, OrmDriver, IColumnDescriptor, QueryBuilder, TransactionCallback, ServerResponseMapper, ISupportedFeature, ITransaction } from '@spinajs/orm';
+import { QueryContext, OrmDriver, IColumnDescriptor, ServerResponseMapper, ISupportedFeature, IsolationLevel, ITransactionContext, ITransactionOptions, IPoolMetrics } from '@spinajs/orm';
 import { SqlDriver } from '@spinajs/orm-sql';
 import * as mysql from 'mysql2';
 import { PoolConnection } from 'mysql2';
 import { Client as SSHClient } from 'ssh2';
-import { AsyncLocalStorage } from 'async_hooks';
-export interface IMySqlTransactionContext {
+export interface IMySqlTransactionContext extends ITransactionContext {
     connection: PoolConnection;
 }
 export declare class MysqlServerResponseMapper extends ServerResponseMapper {
     read(data: any): {
         LastInsertId: any;
         RowsAffected: any;
+        Returning: any[];
     };
 }
 export declare class MySqlOrmDriver extends SqlDriver {
     protected Pool: mysql.Pool;
-    protected _executionId: number;
-    protected TransactionStorage: AsyncLocalStorage<IMySqlTransactionContext>;
-    private getNextExecutionId;
+    /**
+     * MySQL/InnoDB honours all four standard levels.
+     */
+    readonly SupportedIsolationLevels: IsolationLevel[];
     executeOnDb(stmt: string, params: any[], context: QueryContext): Promise<any>;
+    /**
+     * True when the error means the transport died rather than the statement being wrong.
+     */
+    protected isRetryableError(err: unknown): boolean;
+    protected _executeOnDbOnce(stmt: string, params: any[], context: QueryContext): Promise<any>;
     supportedFeatures(): ISupportedFeature;
     resolve(): void;
+    /**
+     * mysql2 keeps its pool bookkeeping on the internal `_allConnections` / `_freeConnections` /
+     * `_connectionQueue` lists. They are not public API, so every read is guarded — a mysql2
+     * upgrade that renames them degrades to zeros rather than crashing the health check.
+     */
+    poolMetrics(): IPoolMetrics;
     ping(): Promise<boolean>;
     connect(): Promise<OrmDriver>;
     disconnect(): Promise<OrmDriver>;
     tableInfo(name: string, schema?: string): Promise<IColumnDescriptor[]>;
-    transaction(queryOrCallback?: QueryBuilder<any>[] | TransactionCallback): Promise<ITransaction>;
+    /**
+     * Pulls the pooled connection out of a transaction context. The base class only ever hands
+     * us contexts this driver's own `_begin` produced, so the cast is safe.
+     */
+    private txConnection;
+    /**
+     * Runs a statement on the transaction's own connection, bypassing the ambient-context lookup
+     * in `executeOnDb`. Transaction control statements must never land on a pooled connection
+     * other than their own.
+     */
+    private runOnConnection;
+    protected _begin(options?: ITransactionOptions): Promise<ITransactionContext>;
+    protected _commit(ctx: ITransactionContext): Promise<void>;
+    protected _rollback(ctx: ITransactionContext): Promise<void>;
+    protected _savepoint(ctx: ITransactionContext, name: string): Promise<void>;
+    protected _releaseSavepoint(ctx: ITransactionContext, name: string): Promise<void>;
+    protected _rollbackToSavepoint(ctx: ITransactionContext, name: string): Promise<void>;
+    protected _dispose(ctx: ITransactionContext): Promise<void>;
 }
 export declare class MySqlSSHOrmDriver extends MySqlOrmDriver {
     protected SshClient: SSHClient;

package/lib/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,mBAAmB,EAAqC,oBAAoB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACvM,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,KAAK,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAY,cAAc,EAAe,MAAM,QAAQ,CAAC;AAG/D,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED,qBAAa,yBAA0B,SAAQ,oBAAoB;IAC1D,IAAI,CAAC,IAAI,EAAE,GAAG;;;;CAGtB;AAED,qBAEa,cAAe,SAAQ,SAAS;IAC3C,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;IAC3B,SAAS,CAAC,YAAY,SAAK;IAC3B,SAAS,CAAC,kBAAkB,8CAAqD;IAEjF,OAAO,CAAC,kBAAkB;IAKnB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC;IAkF7E,iBAAiB,IAAI,iBAAiB;IAItC,OAAO;IAOD,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAS9B,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC;IAyC7B,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC;IAkB1B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAiD5E,WAAW,CAAC,eAAe,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,GAAG,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;CA6EvG;AAED,qBAEa,iBAAkB,SAAQ,cAAc;IACnD,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;IAExB,OAAO;IAYD,UAAU;IAUhB,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC;CAuCrC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAqC,oBAAoB,EAAE,iBAAiB,EAAE,cAAc,EAAE,mBAAmB,EAAE,mBAAmB,EAAmB,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/O,OAAO,EAAoB,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,KAAK,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAY,cAAc,EAAe,MAAM,QAAQ,CAAC;AAG/D,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAG3C,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED,qBAAa,yBAA0B,SAAQ,oBAAoB;IAC1D,IAAI,CAAC,IAAI,EAAE,GAAG;;;mBAKA,GAAG,EAAE;;CAG3B;AAED,qBAEa,cAAe,SAAQ,SAAS;IAC3C,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;IAK3B;;OAEG;IACH,SAAgB,wBAAwB,EAAE,cAAc,EAAE,CAA6E;IAEhI,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC;IAMpF;;OAEG;IACH,SAAS,CAAC,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;IA0BjD,SAAS,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC;IA6FrF,iBAAiB,IAAI,iBAAiB;IAQtC,OAAO;IAOd;;;;OAIG;IACI,WAAW,IAAI,YAAY;IAarB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAW9B,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC;IAmD7B,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC;IAqB1B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA8DnF;;;OAGG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAMvB,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAkC7E,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1D,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5D,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3E,SAAS,CAAC,iBAAiB,CAAC,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlF,SAAS,CAAC,oBAAoB,CAAC,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cAIrE,QAAQ,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlE;AAED,qBAEa,iBAAkB,SAAQ,cAAc;IACnD,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;IAExB,OAAO;IAYD,UAAU;IAUhB,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC;CA4CrC"}

package/lib/cjs/index.js

@@ -45,106 +45,175 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MySqlSSHOrmDriver = exports.MySqlOrmDriver = exports.MysqlServerResponseMapper = void 0;
 /* eslint-disable promise/no-promise-in-callback */
 const di_1 = require("@spinajs/di");
-const log_1 = require("@spinajs/log");
+// No LogLevel import: master moved per-query timing out of every driver and into a single
+// `Perf.measure('orm.query', ...)` around SqlDriver.execute, so duplicating it here would
+// emit the same query twice. QueryBuilder / TransactionCallback / ITransaction are gone with
+// the old `{ commit, rollback }` transaction shape this branch replaced. ConnectionState /
+// IPoolMetrics are orm-infra's connection-resilience + pool-telemetry work.
 const orm_1 = require("@spinajs/orm");
 const orm_sql_1 = require("@spinajs/orm-sql");
 const mysql = __importStar(require("mysql2"));
 const compilers_js_1 = require("./compilers.js");
 const ssh2_1 = require("ssh2");
 const fs_1 = __importDefault(require("fs"));
-const async_hooks_1 = require("async_hooks");
 class MysqlServerResponseMapper extends orm_1.ServerResponseMapper {
     read(data) {
-        return { LastInsertId: data.LastInsertId, RowsAffected: data.RowsAffected };
+        // MySQL has no RETURNING; the identity value is all it reports.
+        return {
+            LastInsertId: data?.LastInsertId ?? 0,
+            RowsAffected: data?.RowsAffected ?? 0,
+            Returning: [],
+        };
     }
 }
 exports.MysqlServerResponseMapper = MysqlServerResponseMapper;
 let MySqlOrmDriver = class MySqlOrmDriver extends orm_sql_1.SqlDriver {
     constructor() {
         super(...arguments);
-        this._executionId = 0;
-        this.TransactionStorage = new async_hooks_1.AsyncLocalStorage();
-    }
-    getNextExecutionId() {
-        this._executionId = (this._executionId + 1) % Number.MAX_SAFE_INTEGER;
-        return this._executionId;
+        // `_executionId` went with the per-driver query timing master centralised.
+        // `TransactionStorage` is no longer declared here either — it moved up to OrmDriver so
+        // ambient-connection propagation is part of the contract rather than a MySQL detail.
+        /**
+         * MySQL/InnoDB honours all four standard levels.
+         */
+        this.SupportedIsolationLevels = ['READ UNCOMMITTED', 'READ COMMITTED', 'REPEATABLE READ', 'SERIALIZABLE'];
     }
     executeOnDb(stmt, params, context) {
+        // Reads and writes are both retried: `withReconnect` only re-runs on transport failures,
+        // where the statement provably never reached the server.
+        return this.withReconnect(() => this._executeOnDbOnce(stmt, params, context));
+    }
+    /**
+     * True when the error means the transport died rather than the statement being wrong.
+     */
+    isRetryableError(err) {
+        // Inside a transaction the connection carried uncommitted state. Reconnecting and replaying
+        // one statement would silently apply it OUTSIDE the transaction, so the error must surface.
+        if (this.TransactionStorage.getStore()) {
+            return false;
+        }
+        if (super.isRetryableError(err)) {
+            return true;
+        }
+        // mysql2 marks connection-level failures fatal; a fatal error means the connection is gone
+        // regardless of which code came with it.
+        let current = err;
+        let depth = 0;
+        while (current && depth < 5) {
+            if (current.fatal === true) {
+                return true;
+            }
+            current = current.inner ?? current.cause;
+            depth++;
+        }
+        return false;
+    }
+    _executeOnDbOnce(stmt, params, context) {
         const self = this;
-        const tName = `query-${this.getNextExecutionId()}`;
-        this.Log.timeStart(`query-${tName}`);
-        // Check if we're inside a transaction context and use that connection
+        // Check if we're inside a transaction context and use that connection.
+        // The context comes from the base driver, so `connection` is typed loosely there; only
+        // this driver's `_begin` ever populates it, and it always puts a PoolConnection in.
         const txContext = this.TransactionStorage.getStore();
-        const queryable = txContext?.connection ?? this.Pool;
         return new Promise((resolve, reject) => {
-            queryable.query(stmt, params, function (err, results) {
-                if (err) {
-                    return reject(new orm_1.OrmException(`Error executing orm command `, {
-                        Host: self.Options.Host,
-                        User: self.Options.User,
-                        Name: self.Options.Name,
-                    }, stmt, params, err));
+            const fail = (err) => reject(new orm_1.OrmException(`Error executing orm command `, {
+                Host: self.Options.Host,
+                User: self.Options.User,
+                Name: self.Options.Name,
+            }, stmt, params, err));
+            const run = (queryable, done) => {
+                try {
+                    queryable.query(stmt, params, function (err, results) {
+                        done();
+                        if (err) {
+                            return fail(err);
+                        }
+                        switch (context) {
+                            case orm_1.QueryContext.Update:
+                            case orm_1.QueryContext.Delete:
+                                resolve({
+                                    RowsAffected: results.affectedRows,
+                                });
+                                break;
+                            case orm_1.QueryContext.Insert:
+                            case orm_1.QueryContext.Upsert:
+                                resolve({
+                                    RowsAffected: results.affectedRows,
+                                    LastInsertId: results.insertId,
+                                    Returning: [],
+                                });
+                                break;
+                            default:
+                                resolve(results);
+                                break;
+                        }
+                    });
                 }
-                switch (context) {
-                    case orm_1.QueryContext.Update:
-                    case orm_1.QueryContext.Delete:
-                        resolve({
-                            RowsAffected: results.affectedRows,
-                        });
-                        break;
-                    case orm_1.QueryContext.Insert:
-                    case orm_1.QueryContext.Upsert:
-                        resolve({
-                            RowsAffected: results.affectedRows,
-                            LastInsertId: results.insertId,
-                        });
-                        break;
-                    default:
-                        resolve(results);
-                        break;
+                catch (err) {
+                    // A synchronous throw would otherwise strand the connection outside the pool.
+                    done();
+                    fail(err);
                 }
+            };
+            if (txContext?.connection) {
+                // A transaction owns its connection for its whole lifetime — releasing it after one
+                // statement would hand the rest of the transaction to a different connection.
+                run(txContext.connection, () => undefined);
+                return;
+            }
+            // Acquiring is the part that queues when the pool is saturated, so it is the part worth
+            // timing. Taking the connection explicitly, instead of letting `Pool.query` do it out of
+            // sight, is what makes `orm_pool_acquire_seconds` a real number instead of always zero.
+            const acquireStart = process.hrtime.bigint();
+            this.Pool.getConnection((err, connection) => {
+                const seconds = Number(process.hrtime.bigint() - acquireStart) / 1e9;
+                this.observeAcquireSeconds(seconds);
+                if (err) {
+                    fail(err);
+                    return;
+                }
+                let released = false;
+                run(connection, () => {
+                    if (released) {
+                        return;
+                    }
+                    released = true;
+                    connection.release();
+                });
             });
-        })
-            .then((val) => {
-            const tDiff = this.Log.timeEnd(`query-${tName}`);
-            void this.Log.write({
-                Level: log_1.LogLevel.Trace,
-                Variables: {
-                    error: undefined,
-                    message: `Executed: ${stmt}, bindings: ${params ? params.join(',') : 'none'}`,
-                    logger: this.Log.Name,
-                    level: 'TRACE',
-                    duration: tDiff,
-                },
-            });
-            return val;
-        })
-            .catch((err) => {
-            const tDiff = this.Log.timeEnd(`query-${tName}`);
-            void this.Log.write({
-                Level: log_1.LogLevel.Error,
-                Variables: {
-                    error: err,
-                    message: `Failed: ${stmt}, bindings: ${params ? params.join(',') : 'none'}`,
-                    logger: this.Log.Name,
-                    level: 'Error',
-                    duration: tDiff,
-                },
-            });
-            throw err;
         });
     }
     supportedFeatures() {
-        return { events: true };
+        // insertIdIsFirstOfBatch: a multi-row `INSERT ... VALUES` is a *simple insert* to InnoDB
+        // ( row count known before execution ), so it reserves one contiguous block of
+        // auto-increment values and LAST_INSERT_ID() reports the first of them. True even under
+        // innodb_autoinc_lock_mode = 2, the MySQL 8 default.
+        return { events: true, insertReturning: false, insertIdIsFirstOfBatch: true };
     }
     resolve() {
         super.resolve();
         this.Container.register(compilers_js_1.MySqlTableExistsCompiler).as(orm_1.TableExistsCompiler);
         this.Container.register(MysqlServerResponseMapper).as(orm_1.ServerResponseMapper);
     }
+    /**
+     * mysql2 keeps its pool bookkeeping on the internal `_allConnections` / `_freeConnections` /
+     * `_connectionQueue` lists. They are not public API, so every read is guarded — a mysql2
+     * upgrade that renames them degrades to zeros rather than crashing the health check.
+     */
+    poolMetrics() {
+        const pool = this.Pool;
+        const size = pool?._allConnections?.length ?? 0;
+        const free = pool?._freeConnections?.length ?? 0;
+        return {
+            Size: size,
+            InUse: Math.max(size - free, 0),
+            Waiting: pool?._connectionQueue?.length ?? 0,
+        };
+    }
     async ping() {
         try {
-            await this.executeOnDb('SELECT 1', [], orm_1.QueryContext.Select);
+            // deliberately bypasses `withReconnect` — a health probe that reconnects on its own
+            // would turn one dead connection into a reconnect storm on every tick.
+            await this._executeOnDbOnce('SELECT 1', [], orm_1.QueryContext.Select);
             return true;
         }
         catch {
@@ -154,6 +223,7 @@ let MySqlOrmDriver = class MySqlOrmDriver extends orm_sql_1.SqlDriver {
     connect() {
         return new Promise((resolve, reject) => {
             try {
+                const pool = this.resolvedPoolOptions();
                 this.Pool = mysql.createPool({
                     host: this.Options.Host,
                     user: this.Options.User,
@@ -161,7 +231,14 @@ let MySqlOrmDriver = class MySqlOrmDriver extends orm_sql_1.SqlDriver {
                     port: this.Options.Port,
                     database: this.Options.Database,
                     waitForConnections: true,
-                    connectionLimit: this.Options.PoolLimit,
+                    connectionLimit: pool.Max,
+                    // mysql2's `maxIdle` is a CEILING on idle connections, not a floor, and it never
+                    // pre-warms the pool — so there is no direct equivalent of `Pool.Min`. Passing Min
+                    // straight through would set maxIdle to 0 by default and make mysql2 destroy every
+                    // released connection, i.e. disable pooling. Instead: an explicit Min becomes the
+                    // number of connections we let sit idle; Min = 0 keeps mysql2's own default (Max).
+                    maxIdle: pool.Min > 0 ? pool.Min : pool.Max,
+                    idleTimeout: pool.IdleTimeout,
                     queueLimit: 0,
                 });
                 // Test the pool connection
@@ -175,6 +252,7 @@ let MySqlOrmDriver = class MySqlOrmDriver extends orm_sql_1.SqlDriver {
                     }
                     // Release the test connection
                     connection.release();
+                    this.setState(orm_1.ConnectionState.Connected);
                     resolve(this);
                 });
             }
@@ -192,6 +270,8 @@ let MySqlOrmDriver = class MySqlOrmDriver extends orm_sql_1.SqlDriver {
         });
     }
     disconnect() {
+        this.stopHealthCheck();
+        this.setState(orm_1.ConnectionState.Disconnected);
         return new Promise((resolve, reject) => {
             if (!this.Pool) {
                 resolve(this);
@@ -209,21 +289,31 @@ let MySqlOrmDriver = class MySqlOrmDriver extends orm_sql_1.SqlDriver {
         });
     }
     async tableInfo(name, schema) {
-        const tblInfo = (await this.executeOnDb(`SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME=? ${schema ? 'AND TABLE_SCHEMA=?' : ''} `, schema ? [name, schema] : [name], orm_1.QueryContext.Select));
-        const isView = (await this.executeOnDb(`SHOW FULL TABLES where \`Tables_in_${schema}\`='${name}'`, [], orm_1.QueryContext.Select));
+        const dbSchema = schema ?? this.Options.Database;
+        if (!dbSchema) {
+            throw new orm_1.OrmException(`Cannot read table info for '${name}': no schema/database configured for this connection ( pass a schema or set Options.Database )`);
+        }
+        // backtick-quote an identifier, escaping embedded backticks by doubling them
+        const escapeId = (id) => '`' + String(id).replace(/`/g, '``') + '`';
+        // ORDER BY ORDINAL_POSITION is not decoration. Without it MySQL is free to return the rows
+        // in any order — and does: the same table came back as (Code, TenantId) in one run and
+        // (TenantId, Code) in the next. Column order is part of what a table descriptor means, so
+        // it has to be the table's own order, not whatever the optimizer produced this time.
+        const tblInfo = (await this.executeOnDb(`SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME=? AND TABLE_SCHEMA=? ORDER BY ORDINAL_POSITION`, [name, dbSchema], orm_1.QueryContext.Select));
+        const isView = (await this.executeOnDb(`SHOW FULL TABLES FROM ${escapeId(dbSchema)} WHERE ${escapeId(`Tables_in_${dbSchema}`)}=?`, [name], orm_1.QueryContext.Select));
         let indexInfo = [];
         if (!isView || isView.length === 0) {
-            throw new orm_1.OrmException(`Table ${schema}.${name} does not exist`);
+            throw new orm_1.OrmException(`Table ${dbSchema}.${name} does not exist`);
         }
         if (!tblInfo || !Array.isArray(tblInfo) || tblInfo.length === 0) {
-            this.Log.trace(`Table ${schema}.${name} does not have any columns.`);
+            this.Log.trace(`Table ${dbSchema}.${name} does not have any columns.`);
             return null;
         }
         if (isView && isView[0].Table_type === 'VIEW') {
-            this.Log.trace(`Table ${schema}.${name} is a VIEW and dont have indexes set.`);
+            this.Log.trace(`Table ${dbSchema}.${name} is a VIEW and dont have indexes set.`);
         }
         else {
-            indexInfo = (await this.executeOnDb(`SHOW INDEXES FROM ${name}`, [], orm_1.QueryContext.Select));
+            indexInfo = (await this.executeOnDb(`SHOW INDEXES FROM ${escapeId(name)}`, [], orm_1.QueryContext.Select));
         }
         return tblInfo.map((r) => {
             const isPrimary = indexInfo.find((c) => c.Key_name === 'PRIMARY' && c.Column_name === r.COLUMN_NAME) !== undefined;
@@ -251,75 +341,76 @@ let MySqlOrmDriver = class MySqlOrmDriver extends orm_sql_1.SqlDriver {
             };
         });
     }
-    transaction(queryOrCallback) {
+    /**
+     * Pulls the pooled connection out of a transaction context. The base class only ever hands
+     * us contexts this driver's own `_begin` produced, so the cast is safe.
+     */
+    txConnection(ctx) {
+        return ctx.connection;
+    }
+    /**
+     * Runs a statement on the transaction's own connection, bypassing the ambient-context lookup
+     * in `executeOnDb`. Transaction control statements must never land on a pooled connection
+     * other than their own.
+     */
+    runOnConnection(connection, stmt) {
+        return new Promise((resolve, reject) => {
+            connection.query(stmt, (err) => (err ? reject(err) : resolve()));
+        });
+    }
+    _begin(options) {
         return new Promise((resolve, reject) => {
-            const trx = {
-                commit: () => Promise.resolve(),
-                rollback: () => Promise.resolve(),
-            };
-            if (!queryOrCallback) {
-                resolve(trx);
-                return;
-            }
             this.Pool.getConnection((err, connection) => {
                 if (err) {
                     reject(err);
                     return;
                 }
-                connection.beginTransaction(async (err) => {
-                    if (err) {
+                const begin = () => {
+                    connection.beginTransaction((err) => {
+                        if (err) {
+                            connection.release();
+                            reject(err);
+                            return;
+                        }
+                        resolve({ connection, depth: 0 });
+                    });
+                };
+                if (options?.isolation) {
+                    // isolation levels are a fixed, validated enum — never caller-supplied free text
+                    this.runOnConnection(connection, `SET TRANSACTION ISOLATION LEVEL ${options.isolation}`).then(begin, (err) => {
                         connection.release();
                         reject(err);
-                        return;
-                    }
-                    try {
-                        // Run the callback/queries within async context so executeOnDb uses this connection
-                        await this.TransactionStorage.run({ connection }, async () => {
-                            if (Array.isArray(queryOrCallback)) {
-                                for (const q of queryOrCallback) {
-                                    await q;
-                                }
-                            }
-                            else {
-                                await queryOrCallback(this);
-                            }
-                        });
-                        resolve({
-                            commit: async () => {
-                                return new Promise((res, rej) => {
-                                    connection.commit((err) => {
-                                        if (err) {
-                                            connection.rollback(() => {
-                                                connection.release();
-                                                rej(err);
-                                            });
-                                            return;
-                                        }
-                                        connection.release();
-                                        res();
-                                    });
-                                });
-                            },
-                            rollback: async () => {
-                                return new Promise((res) => {
-                                    connection.rollback(() => {
-                                        connection.release();
-                                        res();
-                                    });
-                                });
-                            },
-                        });
-                    }
-                    catch (ex) {
-                        connection.rollback(() => {
-                            connection.release();
-                            reject(ex);
-                        });
-                    }
-                });
+                    });
+                    return;
+                }
+                begin();
             });
         });
     }
+    _commit(ctx) {
+        return new Promise((resolve, reject) => {
+            this.txConnection(ctx).commit((err) => (err ? reject(err) : resolve()));
+        });
+    }
+    _rollback(ctx) {
+        return new Promise((resolve, reject) => {
+            this.txConnection(ctx).rollback((err) => (err ? reject(err) : resolve()));
+        });
+    }
+    // savepoint names cannot be bound parameters, so they are inlined through the identifier
+    // escaper rather than passed as `?`
+    _savepoint(ctx, name) {
+        return this.runOnConnection(this.txConnection(ctx), `SAVEPOINT ${(0, orm_sql_1.escapeIdentifier)(name)}`);
+    }
+    _releaseSavepoint(ctx, name) {
+        return this.runOnConnection(this.txConnection(ctx), `RELEASE SAVEPOINT ${(0, orm_sql_1.escapeIdentifier)(name)}`);
+    }
+    _rollbackToSavepoint(ctx, name) {
+        return this.runOnConnection(this.txConnection(ctx), `ROLLBACK TO SAVEPOINT ${(0, orm_sql_1.escapeIdentifier)(name)}`);
+    }
+    async _dispose(ctx) {
+        this.txConnection(ctx).release();
+    }
 };
 exports.MySqlOrmDriver = MySqlOrmDriver;
 exports.MySqlOrmDriver = MySqlOrmDriver = __decorate([
@@ -352,6 +443,7 @@ let MySqlSSHOrmDriver = class MySqlSSHOrmDriver extends MySqlOrmDriver {
                         reject(err);
                         return;
                     }
+                    const pool = this.resolvedPoolOptions();
                     this.Pool = mysql.createPool({
                         host: 'localhost', // we tunnel via ssh so we use localhost
                         user: this.Options.User,
@@ -359,7 +451,10 @@ let MySqlSSHOrmDriver = class MySqlSSHOrmDriver extends MySqlOrmDriver {
                         port: this.Options.Port,
                         database: this.Options.Database,
                         waitForConnections: true,
-                        connectionLimit: this.Options.PoolLimit,
+                        connectionLimit: pool.Max,
+                        // see MySqlOrmDriver.connect — `maxIdle` is a ceiling, so Min = 0 must not reach it
+                        maxIdle: pool.Min > 0 ? pool.Min : pool.Max,
+                        idleTimeout: pool.IdleTimeout,
                         queueLimit: 0,
                         stream: stream,
                     });