knex 3.2.10 → 3.3.0

package/CHANGELOG.md

@@ -1,4 +1,38 @@
-# [Master (Unreleased)](https://github.com/knex/knex/compare/3.2.10...master)
+# [Master (Unreleased)](https://github.com/knex/knex/compare/3.3.0...master)
+
+# 3.3.0 - 26 June, 2026
+
+### New features
+
+- feat: add support for returning in mariadb [#4572](https://github.com/knex/knex/pull/4572)
+- feat: mariadb driver support [#6415](https://github.com/knex/knex/pull/6415)
+- Fixes \_setNullableState not respecting schema [#6025](https://github.com/knex/knex/pull/6025)
+- feat: add connectionPool option for bringing an external pool [#6414](https://github.com/knex/knex/pull/6414)
+- Added knex.migrate.to and knex.migrate.before [#6420](https://github.com/knex/knex/pull/6420)
+- feat: set error.cause for tarn acquire connection error [#5681](https://github.com/knex/knex/pull/5681)
+
+### Bug fixes
+
+- Fix FOR UPDATE OF with explicit schema [#5791](https://github.com/knex/knex/pull/5791)
+- Fix sqlite conditional insert/merge when inserting multiple rows [#6185](https://github.com/knex/knex/pull/6185)
+- Fix: Stream postProcessResponse error is not catchable with .on('error') [#6033](https://github.com/knex/knex/pull/6033)
+- fix(pg): preserve updateFrom binding order [#6454](https://github.com/knex/knex/pull/6454)
+- fix: #6451, support token-credential in mssql auth [#6465](https://github.com/knex/knex/pull/6465)
+- fix(types): #6452 - .where type regression for invalid types [#6463](https://github.com/knex/knex/pull/6463)
+- fix: #6460 unhandled error on connection timeout with stream [#6462](https://github.com/knex/knex/pull/6462)
+- fix: #6455, correctly state tedious as dependency needed for mssql [#6464](https://github.com/knex/knex/pull/6464)
+- fix(pg,mssql): preserve binding order in delete and update queries [#6438](https://github.com/knex/knex/pull/6438)
+
+### Misc
+
+- chore: bump tarn@3.1.0 [#6492](https://github.com/knex/knex/pull/6492)
+- micro-optimization in wrappingFormatter [#6456](https://github.com/knex/knex/pull/6456)
+- cleanup flake in the cancellation tests [#6486](https://github.com/knex/knex/pull/6486)
+- Update docs: timeout section [#6471](https://github.com/knex/knex/pull/6471)
+- ci: make npm install resilient to transient network failures [#6468](https://github.com/knex/knex/pull/6468)
+- Update homepage urls [#6450](https://github.com/knex/knex/pull/6450)
+- chore: add mariadb to docker-compose [#6466](https://github.com/knex/knex/pull/6466)
+- chore: set codecov to default coverage provider [#6448](https://github.com/knex/knex/pull/6448)
 
 # 3.2.10 - 2 May, 2026
 

package/README.md

@@ -1,9 +1,9 @@
-# [knex.js](https://knex.github.io/documentation/)
+# [knex.js](https://knexjs.org/)
 
 [![npm version](http://img.shields.io/npm/v/knex.svg)](https://npmjs.org/package/knex)
 [![npm downloads](https://img.shields.io/npm/dm/knex.svg)](https://npmjs.org/package/knex)
 ![](https://github.com/knex/knex/workflows/CI/badge.svg)
-[![Coverage Status](https://coveralls.io/repos/knex/knex/badge.svg?branch=master)](https://coveralls.io/r/knex/knex?branch=master)
+[![codecov](https://codecov.io/gh/knex/knex/graph/badge.svg?token=bH39w8lIA9)](https://codecov.io/gh/knex/knex)
 [![Dependencies Status](https://img.shields.io/librariesio/github/knex/knex)](https://libraries.io/npm/knex)
 [![Gitter chat](https://badges.gitter.im/tgriesser/knex.svg)](https://gitter.im/tgriesser/knex)
 

package/bin/cli.js

@@ -280,19 +280,13 @@ function invoke() {
       }
     });
 
-  commander
-    .command('migrate:up [<name>]')
-    .option(
-      '--disable-transactions',
-      'run migrations without an implicit transaction'
-    )
-    .description(
-      '        Run the next or the specified migration that has not yet been run.'
-    )
-    .action((name, cmd) => {
+  function migrateUpAction(method) {
+    return (name, cmd) => {
       const disableTransactions = !!cmd.disableTransactions;
       initKnex(env, commander.opts())
-        .then((instance) => instance.migrate.up({ name, disableTransactions }))
+        .then((instance) =>
+          instance.migrate[method]({ name, disableTransactions })
+        )
         .then(([batchNo, log]) => {
           if (log.length === 0) {
             success(color.cyan('Already up to date'));
@@ -307,7 +301,19 @@ function invoke() {
           );
         })
         .catch(exit);
-    });
+    };
+  }
+
+  commander
+    .command('migrate:up [<name>]')
+    .option(
+      '--disable-transactions',
+      'run migrations without an implicit transaction'
+    )
+    .description(
+      '        Run the next or the specified migration that has not yet been run.'
+    )
+    .action(migrateUpAction('up'));
 
   commander
     .command('migrate:rollback')
@@ -371,6 +377,28 @@ function invoke() {
         .catch(exit);
     });
 
+  commander
+    .command('migrate:to <name>')
+    .option(
+      '--disable-transactions',
+      'run migrations without an implicit transaction'
+    )
+    .description(
+      '        Run all migrations up to and including the specified migration.'
+    )
+    .action(migrateUpAction('to'));
+
+  commander
+    .command('migrate:before <name>')
+    .option(
+      '--disable-transactions',
+      'run migrations without an implicit transaction'
+    )
+    .description(
+      '        Run all migrations before the specified migration (exclusive).'
+    )
+    .action(migrateUpAction('before'));
+
   commander
     .command('migrate:currentVersion')
     .description('        View the current version for the migration.')

package/lib/client.js

@@ -1,8 +1,9 @@
-const { Pool, TimeoutError } = require('tarn');
+const { TimeoutError } = require('tarn');
+const { KnexPool, isTarnPool } = require('./pool');
 const { EventEmitter } = require('events');
 const { promisify } = require('util');
 const { makeEscape } = require('./util/string');
-const cloneDeep = require('lodash/cloneDeep');
+const cloneDeepWith = require('lodash/cloneDeepWith');
 const defaults = require('lodash/defaults');
 const uniqueId = require('lodash/uniqueId');
 
@@ -35,6 +36,17 @@ const { setHiddenProperty } = require('./util/security.js');
 
 const debug = require('debug')('knex:client');
 
+function preserveClassInstances(value) {
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    !isPlainObject(value)
+  ) {
+    return value;
+  }
+}
+
 // The base client provides the general structure
 // for a dialect specific client object.
 
@@ -72,11 +84,14 @@ class Client extends EventEmitter {
       this.version = config.version;
     }
 
-    if (config.connection && config.connection instanceof Function) {
+    if (this.config.connection && this.config.connection instanceof Function) {
       this.connectionConfigProvider = this.config.connection;
       this.connectionConfigExpirationChecker = () => true; // causes the provider to be called on first use
     } else {
-      this.connectionSettings = cloneDeep(this.config.connection || {});
+      this.connectionSettings = cloneDeepWith(
+        this.config.connection || {},
+        preserveClassInstances
+      );
       if (config.connection && config.connection.password) {
         setHiddenProperty(this.connectionSettings, this.config.connection);
       }
@@ -84,6 +99,10 @@ class Client extends EventEmitter {
     }
     if (this.driverName && config.connection) {
       this.initializeDriver();
+    }
+    const shouldInitPool =
+      this.driverName && (config.connection || config.connectionPool);
+    if (shouldInitPool) {
       if (!config.pool || (config.pool && config.pool.max !== 0)) {
         this.initializePool(this.config);
       }
@@ -200,7 +219,8 @@ class Client extends EventEmitter {
     try {
       this.driver = this._driver();
     } catch (e) {
-      const message = `Knex: run\n$ npm install ${this.driverName} --save`;
+      const packageName = this._packageName || this.driverName;
+      const message = `Knex: run\n$ npm install ${packageName} --save`;
       this.logger.error(`${message}\n${e.message}\n${e.stack}`);
       throw new Error(`${message}\n${e.message}`);
     }
@@ -390,8 +410,46 @@ class Client extends EventEmitter {
       this.logger.warn('The pool has already been initialized');
       return;
     }
+    if (config.connectionPool) {
+      // External pool mode — delegate to a tarn-compatible or native pool
+      this.connectionSettings = {};
+      this.connectionConfigExpirationChecker = null;
+      if (this.driverName) {
+        this.initializeDriver();
+      }
+      this.initializeExternalPool(config.connectionPool);
+    } else {
+      this.pool = new KnexPool(this.getPoolSettings(config.pool));
+      this._ownsPool = true;
+    }
+  }
 
-    this.pool = new Pool(this.getPoolSettings(config.pool));
+  // Accept an external pool — either a tarn-compatible pool (KnexPool, tarn Pool)
+  // or a native driver pool (pg.Pool, mysql.createPool(), etc.)
+  initializeExternalPool(externalPool) {
+    if (this.pool) {
+      this.logger.warn('The pool has already been initialized');
+      return;
+    }
+    if (isTarnPool(externalPool)) {
+      // Tarn-compatible pool — use directly
+      this.pool = externalPool;
+    } else {
+      // Native driver pool — wrap via dialect-specific adapter
+      this.pool = this.wrapNativePool(externalPool);
+    }
+    this._ownsPool = false;
+  }
+
+  // Override in dialects that support native driver pools.
+  // Must return an object with { acquire(), release(), destroy() } matching tarn's interface.
+  wrapNativePool(_nativePool) {
+    throw new Error(
+      `The '${
+        this.driverName || 'base'
+      }' dialect does not support native driver pools in 'connectionPool'. ` +
+        `Pass a tarn Pool or KnexPool instance instead.`
+    );
   }
 
   validateConnection(connection) {
@@ -420,12 +478,23 @@ class Client extends EventEmitter {
       }
       return connection;
     } catch (error) {
+      // Tarn only gives us the propagated error's message, not its stack. However, for the "original"
+      // promise that rejected, the stack will be present when Tarn passes us the error directly (not
+      // as a timeout). The stack is likely of little use, but let's give all the information we can.
+      const withStack =
+        error instanceof Error ? error.stack ?? error.message : String(error);
+
+      // Errors like this can be noisy; use logger.warn to make it easier for operators to opt out of
+      // noise but still surface more critical problems
+      this.logger.warn(`Acquire connection error: ${withStack}`);
+
       let convertedError = error;
       if (error instanceof TimeoutError) {
         convertedError = new KnexTimeoutError(
           'Knex: Timeout acquiring a connection. The pool is probably full. ' +
             'Are you missing a .transacting(trx) call?'
         );
+        convertedError.cause = error;
       }
       throw convertedError;
     }
@@ -445,9 +514,11 @@ class Client extends EventEmitter {
   }
 
   // Destroy the current connection pool for the client.
+  // When the pool is externally provided (_ownsPool === false), we only drop
+  // our reference — the caller is responsible for tearing it down.
   async destroy(callback) {
     try {
-      if (this.pool && this.pool.destroy) {
+      if (this.pool && this.pool.destroy && this._ownsPool !== false) {
         await this.pool.destroy();
       }
       this.pool = undefined;

package/lib/constants.js

@@ -7,6 +7,7 @@ const CLIENT_ALIASES = Object.freeze({
 
 const SUPPORTED_CLIENTS = Object.freeze(
   [
+    'mariadb',
     'mssql',
     'mysql',
     'mysql2',
@@ -21,6 +22,7 @@ const SUPPORTED_CLIENTS = Object.freeze(
 );
 
 const DRIVER_NAMES = Object.freeze({
+  MariaDB: 'mariadb',
   MsSQL: 'mssql',
   MySQL: 'mysql',
   MySQL2: 'mysql2',

package/lib/dialects/index.js

@@ -7,6 +7,7 @@ const dbNameToDialectLoader = Object.freeze({
   cockroachdb: () => require('./cockroachdb'),
   mssql: () => require('./mssql'),
   mysql: () => require('./mysql'),
+  mariadb: () => require('./mariadb'),
   mysql2: () => require('./mysql2'),
   oracle: () => require('./oracle'),
   oracledb: () => require('./oracledb'),

package/lib/dialects/mariadb/index.js

@@ -0,0 +1,55 @@
+// MariaDB Client
+// -------
+const Client_MySQL = require('../mysql');
+const Transaction = require('./transaction');
+const QueryCompiler = require('./query/mariadb-querycompiler');
+const ColumnCompiler = require('./schema/mariadb-columncompiler');
+
+class Client_MariaDB extends Client_MySQL {
+  transaction() {
+    return new Transaction(this, ...arguments);
+  }
+
+  queryCompiler(builder, formatter) {
+    return new QueryCompiler(this, builder, formatter);
+  }
+
+  columnCompiler() {
+    return new ColumnCompiler(this, ...arguments);
+  }
+
+  _driver() {
+    return require('mariadb/callback');
+  }
+
+  processResponse(obj, runner) {
+    if (obj == null) return;
+    if (obj.returning) {
+      const rows = obj.response[0];
+      const fields = obj.response[1];
+      if (obj.output) {
+        return obj.output.call(runner, rows, fields);
+      }
+      return rows;
+    }
+    return super.processResponse(obj, runner);
+  }
+
+  validateConnection(connection) {
+    if (typeof connection.isValid === 'function') {
+      return connection.isValid();
+    }
+    return (
+      connection &&
+      !connection._fatalError &&
+      !connection._protocolError &&
+      !connection._closing
+    );
+  }
+}
+
+Object.assign(Client_MariaDB.prototype, {
+  driverName: 'mariadb',
+});
+
+module.exports = Client_MariaDB;

package/lib/dialects/mariadb/query/mariadb-querycompiler.js

@@ -0,0 +1,98 @@
+// MariaDB Query Compiler
+// -------
+const QueryCompiler_MySQL = require('../../mysql/query/mysql-querycompiler');
+const { wrap: wrap_ } = require('../../../formatter/wrappingFormatter');
+
+class QueryCompiler_MariaDB extends QueryCompiler_MySQL {
+  // On MariaDB, json_extract() yields a quoted JSON scalar (e.g. "cold") whose
+  // values do not compare equal with `=`. json_unquote() is required for the
+  // comparison to behave like MySQL's native JSON type
+  onJsonPathEquals(clause) {
+    const extract = (column, path) =>
+      `json_unquote(json_extract(${wrap_(
+        column,
+        undefined,
+        this.builder,
+        this.client,
+        this.bindingsHolder
+      )}, ${this.client.parameter(path, this.builder, this.bindingsHolder)}))`;
+
+    return `${extract(clause.columnFirst, clause.jsonPathFirst)} = ${extract(
+      clause.columnSecond,
+      clause.jsonPathSecond
+    )}`;
+  }
+
+  insert() {
+    const sql = super.insert();
+    if (sql === '') return sql;
+    const { returning } = this.single;
+    if (returning && this._supportsReturning('insert')) {
+      return { sql: sql + this._returning(returning), returning };
+    }
+    return sql;
+  }
+
+  update() {
+    const sql = super.update();
+    if (sql === '') return sql;
+    const { returning } = this.single;
+    if (returning && this._supportsReturning('update')) {
+      return { sql: sql + this._returning(returning), returning };
+    }
+    return sql;
+  }
+
+  del() {
+    const sql = super.del();
+    if (sql === '') return sql;
+    const { returning } = this.single;
+    if (returning && this._supportsReturning('del')) {
+      return { sql: sql + this._returning(returning), returning };
+    }
+    return sql;
+  }
+
+  _returning(value) {
+    return value ? ` returning ${this.formatter.columnize(value)}` : '';
+  }
+
+  _supportsReturning(method) {
+    // Assume that if the version doesn't exist, we're on the latest
+    // (fail open and assume the user is building queries correctly)
+    const version = parseFloat(this.client.version) ?? 13;
+    if (version < 10.5) {
+      return false;
+    }
+    if (method === 'update') {
+      return version >= 13 && (this.grouped.join || []).length === 0;
+    }
+    if (method === 'del') {
+      return (this.grouped.join || []).length === 0;
+    }
+    return true;
+  }
+
+  _returningCheck() {
+    const { returning } = this.single;
+    if (!returning || this._supportsReturning(this.method)) {
+      return;
+    }
+    let reason;
+    const hasJoin = (this.grouped.join || []).length;
+    if (this.method === 'update') {
+      reason = (this.grouped.join || []).length
+        ? 'multi-table update statements'
+        : 'mariadb versions older than 13.0';
+    } else if (this.method === 'del' && hasJoin) {
+      reason = 'multi-table delete statements';
+    } else {
+      reason = 'mariadb versions older than 10.5';
+    }
+    this.client.logger.warn(
+      `.returning() is not supported for ${reason} and will not have any effect.`
+    );
+  }
+}
+
+module.exports = QueryCompiler_MariaDB;

package/lib/dialects/mariadb/schema/mariadb-columncompiler.js

@@ -0,0 +1,17 @@
+// MariaDB Column Compiler
+// -------
+const ColumnCompiler_MySQL = require('../../mysql/schema/mysql-columncompiler');
+
+class ColumnCompiler_MariaDB extends ColumnCompiler_MySQL {
+  // MariaDB does not accept a named CHECK constraint inline in a column
+  // definition
+  _check(checkPredicate, constraintName) {
+    if (constraintName && this.columnBuilder._method !== 'alter') {
+      this._pushAlterCheckQuery(checkPredicate, constraintName);
+      return '';
+    }
+    return super._check(checkPredicate, constraintName);
+  }
+}
+
+module.exports = ColumnCompiler_MariaDB;

package/lib/dialects/mariadb/transaction.js

@@ -0,0 +1,44 @@
+const Transaction = require('../../execution/transaction');
+const debug = require('debug')('knex:tx');
+
+class Transaction_MariaDB extends Transaction {
+  query(conn, sql, status, value) {
+    const t = this;
+    const q = this.trxClient
+      .query(conn, sql)
+      .catch((err) => {
+        if (err.code === 'ER_SP_DOES_NOT_EXIST') {
+          this.trxClient.logger.warn(
+            'Transaction was implicitly committed, do not mix transactions and ' +
+              'DDL with MySQL (#805)'
+          );
+          return;
+        }
+
+        status = 2;
+        value = err;
+        t._completed = true;
+        debug('%s error running transaction query', t.txid);
+      })
+      .then(function (res) {
+        if (status === 1) t._resolver(value);
+        if (status === 2) {
+          if (value === undefined) {
+            if (t.doNotRejectOnRollback && /^ROLLBACK\b/i.test(sql)) {
+              t._resolver();
+              return;
+            }
+            value = new Error(`Transaction rejected with non-error: ${value}`);
+          }
+          t._rejecter(value);
+          return res;
+        }
+      });
+    if (status === 1 || status === 2) {
+      t._completed = true;
+    }
+    return q;
+  }
+}
+
+module.exports = Transaction_MariaDB;

package/lib/dialects/mssql/index.js

@@ -46,6 +46,7 @@ class Client_MSSQL extends Client {
           clientSecret: settings.clientSecret,
           tenantId: settings.tenantId,
           msiEndpoint: settings.msiEndpoint,
+          credential: settings.credential,
         },
       },
       server: settings.server || settings.host,
@@ -493,6 +494,8 @@ Object.assign(Client_MSSQL.prototype, {
   dialect: 'mssql',
 
   driverName: 'mssql',
+
+  _packageName: 'tedious',
 });
 
 module.exports = Client_MSSQL;

package/lib/dialects/mssql/query/mssql-querycompiler.js

@@ -179,8 +179,8 @@ class QueryCompiler_MSSQL extends QueryCompiler {
   }
 
   updateWithTriggers() {
-    const top = this.top();
     const withSQL = this.with();
+    const top = this.top();
     const updates = this._prepUpdate(this.single.update);
     const join = this.join();
     const where = this.where();
@@ -221,8 +221,8 @@ class QueryCompiler_MSSQL extends QueryCompiler {
   }
 
   standardUpdate() {
-    const top = this.top();
     const withSQL = this.with();
+    const top = this.top();
     const updates = this._prepUpdate(this.single.update);
     const join = this.join();
     const where = this.where();
@@ -261,8 +261,8 @@ class QueryCompiler_MSSQL extends QueryCompiler {
     // Make sure tableName is processed by the formatter first.
     const withSQL = this.with();
     const { tableName } = this;
-    const wheres = this.where();
     const joins = this.join();
+    const wheres = this.where();
     const { returning } = this.single;
     const returningStr = returning
       ? ` ${this._returning('del', returning, true)}`
@@ -288,8 +288,8 @@ class QueryCompiler_MSSQL extends QueryCompiler {
     // Make sure tableName is processed by the formatter first.
     const withSQL = this.with();
     const { tableName } = this;
-    const wheres = this.where();
     const joins = this.join();
+    const wheres = this.where();
     const { returning } = this.single;
     const returningStr = returning
       ? ` ${this._returning('del', returning)}`

package/lib/dialects/mysql/index.js

@@ -2,6 +2,7 @@
 // -------
 const defer = require('lodash/defer');
 const map = require('lodash/map');
+const uniqueId = require('lodash/uniqueId');
 const { promisify } = require('util');
 const Client = require('../../client');
 
@@ -109,6 +110,47 @@ class Client_MySQL extends Client {
     );
   }
 
+  // Wraps a native mysql pool with the interface knex expects from this.pool.
+  /**
+   * @param {import('mysql').Pool | import('mysql2').Pool} nativePool
+   */
+  wrapNativePool(nativePool) {
+    return {
+      acquire() {
+        return {
+          promise: new Promise((resolve, reject) => {
+            nativePool.getConnection((err, connection) => {
+              if (err) return reject(err);
+              connection.__knexUid = uniqueId('__knexUid');
+              resolve(connection);
+            });
+          }),
+        };
+      },
+      /**
+       * @param {import('mysql').Connection | import('mysql2').Connection} connection
+       */
+      release(connection) {
+        if (connection.__knex__disposed) {
+          // Disposed connection — remove from pool without sending COM_QUIT
+          if (typeof connection.destroy === 'function') {
+            connection.destroy();
+          }
+          return true;
+        }
+        if (typeof connection.release === 'function') {
+          connection.release();
+          return true;
+        }
+        return false;
+      },
+      destroy() {
+        // No-op: knex does not own the native pool
+        return Promise.resolve();
+      },
+    };
+  }
+
   // Grab a connection, run the query via the MySQL streaming interface,
   // and pass that through to the stream we've sent back to the client.
   _stream(connection, obj, stream, options) {

package/lib/dialects/mysql/query/mysql-querycompiler.js

@@ -17,16 +17,10 @@ const isPlainObjectOrArray = (value) =>
 class QueryCompiler_MySQL extends QueryCompiler {
   constructor(client, builder, formatter) {
     super(client, builder, formatter);
-
-    const { returning } = this.single;
-    if (returning) {
-      this.client.logger.warn(
-        '.returning() is not supported by mysql and will not have any effect.'
-      );
-    }
-
+    this._returningCheck();
     this._emptyInsertValue = '() values ()';
   }
+
   // Compiles a `delete` query, allowing comments and LIMIT.
   del() {
     const sql = super.del();
@@ -288,6 +282,15 @@ class QueryCompiler_MySQL extends QueryCompiler {
   onJsonPathEquals(clause) {
     return this._onJsonPathEquals('json_extract', clause);
   }
+
+  _returningCheck() {
+    const { returning } = this.single;
+    if (returning) {
+      this.client.logger.warn(
+        '.returning() is not supported by mysql and will not have any effect.'
+      );
+    }
+  }
 }
 
 // MySQL supports LIMIT on single-table DELETE statements.

package/lib/dialects/mysql2/index.js

@@ -34,6 +34,13 @@ class Client_MySQL2 extends Client_MySQL {
     }
   }
 
+  // Support both mysql2.createPool() and mysql2/promise.createPool().
+  // The promise variant wraps a callback pool and exposes it as .pool.
+  wrapNativePool(nativePool) {
+    const callbackPool = nativePool.pool || nativePool;
+    return super.wrapNativePool(callbackPool);
+  }
+
   validateConnection(connection) {
     return (
       connection &&