knex 3.2.9 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knex",
-  "version": "3.2.9",
+  "version": "3.3.0",
   "description": "A batteries-included SQL query & schema builder for PostgresSQL, MySQL, CockroachDB, MSSQL and SQLite3",
   "main": "knex.js",
   "types": "types/index.d.ts",
@@ -25,11 +25,12 @@
     "test:unit-only": "mocha --exit -t 10000 --config test/mocha-unit-config-test.js",
     "test:db": "mocha --exit -t 10000 --config test/mocha-integration-config-test.js",
     "test:db:coverage": "nyc mocha --exit --check-leaks -t 10000 --config test/mocha-integration-config-test.js && npm run test:tape",
-    "test:db:no-oracle": "cross-env DB=\"mssql mysql mysql2 postgres sqlite3\" mocha --exit -t 10000 --config test/mocha-integration-config-test.js && npm run test:tape",
+    "test:db:no-oracle": "cross-env DB=\"mssql mysql mysql2 mariadb postgres sqlite3\" mocha --exit -t 10000 --config test/mocha-integration-config-test.js && npm run test:tape",
     "test": "mocha --exit -t 10000 --config test/mocha-all-config-test.js && npm run test:tape && npm run test:cli",
     "test:coverage": "nyc mocha --exit --check-leaks -t 10000 --config test/mocha-all-config-test.js && npm run test:tape && npm run test:cli",
     "test:everything": "npm run lint:everything && npm run test:coverage",
     "test:mssql": "cross-env DB=mssql npm run test:db",
+    "test:mariadb": "cross-env DB=mariadb npm run test:db",
     "test:mysql": "cross-env DB=mysql npm run test:db",
     "test:mysql2": "cross-env DB=mysql2 npm run test:db",
     "test:oracledb": "cross-env DB=oracledb npm run test:db",
@@ -40,8 +41,8 @@
     "test:pgnative": "cross-env DB=pgnative npm run test:db",
     "test:tape": "node test/tape/index.js | faucet",
     "test:cli": "cross-env KNEX_PATH=../knex.js KNEX=bin/cli.js jake -f test/jake/Jakefile && mocha --exit -t 10000 test/cli-tests-suite.js",
-    "db:start": "docker compose -f scripts/docker-compose.yml up --build -d mysql oracledb postgres mssql cockroachdb pgnative && docker compose -f scripts/docker-compose.yml up waitmssql waitmysql waitpostgres waitoracledb",
-    "db:start:no-oracle": "docker compose -f scripts/docker-compose.yml up --build -d mysql postgres mssql cockroachdb pgnative && docker compose -f scripts/docker-compose.yml up waitmssql waitmysql waitpostgres",
+    "db:start": "docker compose -f scripts/docker-compose.yml up --build -d mysql oracledb postgres mssql mariadb cockroachdb pgnative && docker compose -f scripts/docker-compose.yml up waitmssql waitmysql waitmariadb waitpostgres waitoracledb",
+    "db:start:no-oracle": "docker compose -f scripts/docker-compose.yml up --build -d mysql postgres mssql mariadb cockroachdb pgnative && docker compose -f scripts/docker-compose.yml up waitmssql waitmysql waitmariadb waitpostgres",
     "db:stop": "docker compose -f scripts/docker-compose.yml down",
     "db:start:postgres": "docker compose -f scripts/docker-compose.yml up --build -d postgres && docker compose -f scripts/docker-compose.yml up waitpostgres",
     "db:stop:postgres": "docker compose -f scripts/docker-compose.yml down",
@@ -49,6 +50,8 @@
     "db:stop:pgnative": "docker compose -f scripts/docker-compose.yml down",
     "db:start:mysql": "docker compose -f scripts/docker-compose.yml up --build -d mysql && docker compose -f scripts/docker-compose.yml up waitmysql",
     "db:stop:mysql": "docker compose -f scripts/docker-compose.yml down",
+    "db:start:mariadb": "docker compose -f scripts/docker-compose.yml up --build -d mariadb && docker compose -f scripts/docker-compose.yml up waitmariadb",
+    "db:stop:mariadb": "docker compose -f scripts/docker-compose.yml down",
     "db:start:mssql": "docker compose -f scripts/docker-compose.yml up --build -d mssql && docker compose -f scripts/docker-compose.yml up waitmssql",
     "db:stop:mssql": "docker compose -f scripts/docker-compose.yml down",
     "db:start:cockroachdb": "docker compose -f scripts/docker-compose.yml up --build -d cockroachdb && docker compose -f scripts/docker-compose.yml up waitcockroachdb",
@@ -68,11 +71,11 @@
     "get-package-type": "^0.1.0",
     "getopts": "2.3.0",
     "interpret": "^2.2.0",
-    "lodash": "^4.17.21",
+    "lodash": "^4.18.1",
     "pg-connection-string": "2.6.2",
     "rechoir": "^0.8.0",
     "resolve-from": "^5.0.0",
-    "tarn": "^3.0.2",
+    "tarn": "^3.1.0",
     "tildify": "2.0.0"
   },
   "peerDependencies": {
@@ -82,6 +85,9 @@
     "tedious": {
       "optional": true
     },
+    "mariadb": {
+      "optional": true
+    },
     "mysql": {
       "optional": true
     },
@@ -131,6 +137,7 @@
     "jake": "^10.8.5",
     "JSONStream": "^1.3.5",
     "lint-staged": "^16.2.7",
+    "mariadb": "^3.5.2",
     "mocha": "^10.0.0",
     "mock-fs": "^5.1.4",
     "mysql": "^2.18.1",
@@ -164,7 +171,7 @@
     "type": "git",
     "url": "git://github.com/knex/knex.git"
   },
-  "homepage": "https://knex.github.io/documentation/",
+  "homepage": "https://knexjs.org/",
   "keywords": [
     "sql",
     "query",
@@ -213,6 +220,7 @@
     "./lib/bin/cli.js": "./lib/util/noop.js",
     "./lib/migrations/seed/Seeder.js": "./lib/util/noop.js",
     "tedious": false,
+    "mariadb": false,
     "mysql": false,
     "mysql2": false,
     "pg": false,

package/types/index.d.ts

@@ -9,6 +9,7 @@
 import type { EventEmitter } from 'events';
 import type { Duplex, PassThrough, Stream } from 'stream';
 import type { Pool } from 'tarn';
+import type { PoolOptions } from 'tarn/dist/Pool';
 import type { ConnectionOptions } from 'tls';
 
 import type { Registry } from './result';
@@ -482,6 +483,10 @@ declare namespace knex {
 
   export class KnexTimeoutError extends Error {}
 
+  export class KnexPool<T = any> extends Pool<T> {
+    constructor(config: PoolOptions<T>);
+  }
+
   export const Client: typeof Knex.Client;
 }
 
@@ -1704,7 +1709,10 @@ declare namespace Knex {
       TResult
     >;
 
-    (object: Readonly<Record<string, any>>): QueryBuilder<TRecord, TResult>;
+    // note: `Object` is intentional here: its mapped members preserve excess-property
+    // checking so `.where({ unknownColumn })` stays a compile error, while still
+    // accepting pre-typed dynamic objects, see #6452
+    (object: Readonly<Object>): QueryBuilder<TRecord, TResult>;
 
     <T extends keyof ResolveTableType<TRecord>>(
       columnName: T,
@@ -2757,6 +2765,14 @@ declare namespace Knex {
     jsonbSupport?: boolean;
     version?: string;
     connection?: string | StaticConnectionConfig | ConnectionConfigProvider;
+    /**
+     * An external pool to use instead of knex creating its own.
+     * Accepts a KnexPool, tarn Pool, or a native driver pool (pg.Pool,
+     * mysql.createPool(), oracledb.createPool()).
+     * Mutually exclusive with `connection` — knex does not own the pool
+     * lifecycle; call pool.end() / pool.close() yourself when done.
+     */
+    connectionPool?: ConnectionPool;
     pool?: PoolConfig;
     migrations?: MigratorConfig;
     postProcessResponse?: (result: any, queryContext: any) => any;
@@ -2817,7 +2833,8 @@ declare namespace Knex {
     | 'azure-active-directory-access-token'
     | 'azure-active-directory-msi-vm'
     | 'azure-active-directory-msi-app-service'
-    | 'azure-active-directory-service-principal-secret';
+    | 'azure-active-directory-service-principal-secret'
+    | 'token-credential';
 
   interface MsSqlDefaultAuthenticationConfig extends MsSqlConnectionConfigBase {
     type?: 'default' | never;
@@ -2895,6 +2912,19 @@ declare namespace Knex {
     tenantId: string;
   }
 
+  interface MsSqlTokenCredential {
+    getToken(
+      scopes: string | string[],
+      options?: unknown
+    ): Promise<{ token: string; expiresOnTimestamp: number } | null>;
+  }
+
+  interface MsSqlTokenCredentialAuthenticationConfig
+    extends MsSqlConnectionConfigBase {
+    type: 'token-credential';
+    credential: MsSqlTokenCredential;
+  }
+
   interface MsSqlNtlmAuthenticationConfig extends MsSqlConnectionConfigBase {
     type: 'ntlm';
     /**
@@ -2914,7 +2944,8 @@ declare namespace Knex {
     | MsSqlAzureActiveDirectoryMsiAppServiceAuthenticationConfig
     | MsSqlAzureActiveDirectoryMsiVmAuthenticationConfig
     | MsSqlAzureActiveDirectoryPasswordAuthenticationConfig
-    | MsSqlAzureActiveDirectoryServicePrincipalSecretConfig;
+    | MsSqlAzureActiveDirectoryServicePrincipalSecretConfig
+    | MsSqlTokenCredentialAuthenticationConfig;
 
   // Config object for tedious: see http://tediousjs.github.io/tedious/api-connection.html
   interface MsSqlConnectionConfigBase {
@@ -3124,6 +3155,46 @@ declare namespace Knex {
     expirationChecker?(): boolean;
   }
 
+  // Pool-like interfaces matching the shapes of native driver pools.
+  // These allow `connectionPool` to accept pools from pg, mysql/mysql2,
+  // oracledb, or any tarn-compatible pool without importing driver types.
+
+  /** Matches the pg.Pool interface */
+  interface PgPoolLike {
+    connect(): Promise<any>;
+    end(): Promise<void>;
+    totalCount: number;
+    idleCount: number;
+    waitingCount: number;
+  }
+
+  /** Matches the mysql / mysql2 pool interface */
+  interface MySQLPoolLike {
+    getConnection(cb: (err: Error | null, connection: any) => void): void;
+    end(cb?: (err?: Error) => void): void;
+  }
+
+  /** Matches the oracledb pool interface */
+  interface OraclePoolLike {
+    getConnection(): Promise<any>;
+    close(drainTime?: number): Promise<void>;
+  }
+
+  /** Any tarn-compatible pool (including KnexPool) */
+  interface TarnPoolLike {
+    acquire(): { promise: Promise<any> };
+    release(resource: any): boolean;
+    destroy(): Promise<void>;
+  }
+
+  /** Types accepted by the `connectionPool` config option */
+  type ConnectionPool =
+    | Pool<any>
+    | TarnPoolLike
+    | PgPoolLike
+    | MySQLPoolLike
+    | OraclePoolLike;
+
   interface PoolConfig {
     name?: string;
     afterCreate?: Function;
@@ -3209,6 +3280,8 @@ declare namespace Knex {
     list(config?: MigratorConfig): Promise<any>;
     up(config?: MigratorConfigWithLifecycleHooks): Promise<any>;
     down(config?: MigratorConfigWithLifecycleHooks): Promise<any>;
+    to(config?: MigratorConfigWithLifecycleHooks): Promise<any>;
+    before(config?: MigratorConfigWithLifecycleHooks): Promise<any>;
     forceFreeMigrationsLock(config?: MigratorConfig): Promise<any>;
   }
 
@@ -3310,7 +3383,8 @@ declare namespace Knex {
     };
     getPoolSettings(poolConfig: any): any;
     initializePool(config?: {}): void;
-    pool: Pool<any> | undefined;
+    initializeExternalPool(externalPool: ConnectionPool): void;
+    pool: Pool<any> | TarnPoolLike | undefined;
     acquireConnection(): any;
     releaseConnection(connection: any): any;
     destroy(callback: any): any;