knex 0.95.0 → 0.95.4

package/CHANGELOG.md

@@ -1,7 +1,59 @@
 # Master (Unreleased)
 
+# 0.95.4 - 26 March, 2021
+
+### Typings:
+
+- Fix mistyping of stream #4400
+
+# 0.95.3 - 25 March, 2021
+
+### New features:
+
+- PostgreSQL: Add "same" as operator #4372
+- MSSQL: Improve an estimate of the max comment length #4362
+- Throw an error if negative offset is provided #4361
+
+### Bug fixes:
+
+- Fix timeout method #4324
+- SQLite: prevent dropForeign from being silently ignored #4376
+
+### Typings:
+
+- Allow config.client to be non-client instance #4367
+- Add dropForeign arg type for single column #4363
+- Update typings for TypePreservingAggregation and stream #4377
+
+# 0.95.2 - 11 March, 2021
+
+### New features:
+
+- Improve ESM import support #4350
+
+### Bug fixes:
+
+- CLI: update ts.stub files to new TypeScript namespace #4344
+- CLI: fix TypeScript migration stub after 0.95.0 changes #4366
+
+### Typings:
+
+- Move QueryBuilder and KnexTimeoutError into knex namespace #4358
+
+### Test / internal changes:
+
+- Unify db test helpers #4356
+
+# 0.95.1 - 04 March, 2021
+
+### Bug fixes:
+
+- CLI: fix `knex init` not finding default knexfile #4339
+
 # 0.95.0 - 03 March, 2021
 
+Note: there are many breaking changes in this version, particularly in TypeScript support. Please see `UPGRADING.md` for details.
+
 ### New features:
 
 - Add transaction isolation support #4185
@@ -41,6 +93,7 @@
 
 ### Typings:
 
+- TypeScript 4.1+ is now required
 - Add missing onConflict overrides #4182
 - Introduce the "infamous triplet" export #4181
 - Fix type definition of Transaction #4172

package/CONTRIBUTING.md

@@ -103,7 +103,7 @@ One easy way to setup database for your reproduction is to use database from kne
 
 By default, Knex runs tests against sqlite3, postgresql, mysql, mysql2, mssql and oracledb drivers. All databases can be initialized and ran with docker.
 
-Docker databases can be started and initialized and started with:
+Docker databases can be started and initialized with:
 
 ```bash
 npm run db:start

package/README.md

@@ -116,3 +116,33 @@ try {
   // error handling
 }
 ```
+
+## Usage as ESM module
+
+If you are launching your Node application with `--experimental-modules`, `knex.mjs` should be picked up automatically and named ESM import should work out-of-the-box.
+Otherwise, if you want to use named imports, you'll have to import knex like this:
+```js
+import { knex } from 'knex/knex.mjs'
+```
+
+You can also just do the default import:
+```js
+import knex from 'knex'
+```
+
+If you are not using TypeScript and would like the IntelliSense of your IDE to work correctly, it is recommended to set the type explicitly:
+```js
+/**
+ * @type {Knex}
+ */
+const database = knex({
+    client: 'mysql',
+    connection: {
+      host : '127.0.0.1',
+      user : 'your_database_user',
+      password : 'your_database_password',
+      database : 'myapp_test'
+    }
+  });
+database.migrate.latest();
+```

package/UPGRADING.md

@@ -3,7 +3,7 @@
 ### Upgrading to version 0.95.0+
 
 * TypeScript type exports changed significantly. While `import Knex from 'knex';` used to import the knex instantiation function, the namespace and the interface for the knex instantiation function/object, there is now a clear distinction between them:
-```
+```typescript
 import { knex } from 'knex' // this is a function that you call to instantiate knex
 import { Knex } from 'knex' // this is a namespace, and a type of a knex object
 import KnexTimeoutError = Knex.KnexTimeoutError; // this is a class from the Knex namespace
@@ -12,6 +12,60 @@ const config: Knex.Config = {} // this is a type from the Knex namespace
 const knexInstance: Knex = knex(config)
 ```
 
+If your code looked like this:
+```typescript
+import knex from 'knex'
+
+const config: knex.Config = {} // this is a type from the Knex namespace
+const knexInstance = knex(config)
+```
+
+Change it to
+```typescript
+import { knex, Knex } from 'knex'
+
+const config: Knex.Config = {} // this is a type from the Knex namespace
+const knexInstance = knex(config)
+```
+
+* If you were importing types such as `Config` or `QueryBuilder` directly, use `Knex` namespace instead.
+
+So change this:
+```ts
+import { QueryBuilder } from 'knex'
+
+const qb: QueryBuilder = knex('table').select('*')
+```
+
+to this:
+```ts
+import { Knex } from 'knex'
+
+const qb: Knex.QueryBuilder = knex('table').select('*')
+```
+
+* Syntax for QueryBuilder augmentation changed. Previously it looked like this:
+
+```ts
+declare module 'knex' {
+    interface QueryBuilder {
+      paginate<TResult = any[]>(params: IPaginateParams): KnexQB<any, IWithPagination<TResult>>;
+  }
+}
+```
+
+This should be changed into this:
+
+```ts
+declare module 'knex' {
+  namespace Knex {
+    interface QueryBuilder {
+      paginate<TResult = any[]>(params: IPaginateParams): KnexQB<any, IWithPagination<TResult>>;
+    }
+  }
+}
+```
+
 * TypeScript version 4.1+ is needed when using knex types now.
 
 * MSSQL driver was completely reworked in order to address the multitude of connection pool, error handling and performance issues. Since the new implementation uses `tedious` library directly instead of `mssql`, please replace `mssql` with `tedious` in your dependencies if you are using a MSSQL database.

package/bin/cli.js

@@ -178,7 +178,7 @@ function invoke() {
       const stubPath = `./knexfile.${type}`;
       readFile(
         path.dirname(env.modulePath) +
-          '/lib/migrate/stub/knexfile-' +
+          '/lib/migrations/migrate/stub/knexfile-' +
           type +
           '.stub'
       )

package/lib/constants.js

@@ -17,6 +17,16 @@ const SUPPORTED_CLIENTS = Object.freeze(
   ].concat(Object.keys(CLIENT_ALIASES))
 );
 
+const DRIVER_NAMES = Object.freeze({
+  MsSQL: 'mssql',
+  MySQL: 'mysql',
+  MySQL2: 'mysql2',
+  Oracle: 'oracledb',
+  PostgreSQL: 'pg',
+  Redshift: 'pg-redshift',
+  SQLite: 'sqlite3',
+});
+
 const POOL_CONFIG_OPTIONS = Object.freeze([
   'maxWaitingClients',
   'testOnBorrow',
@@ -41,4 +51,5 @@ module.exports = {
   SUPPORTED_CLIENTS,
   POOL_CONFIG_OPTIONS,
   COMMA_NO_PAREN_REGEX,
+  DRIVER_NAMES,
 };

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

@@ -93,9 +93,12 @@ class ColumnCompiler_MSSQL extends ColumnCompiler {
   }
 
   comment(comment) {
-    if (comment && comment.length > 255) {
+    // XXX: This is a byte limit, not character, so we cannot definitively say they'll exceed the limit without database collation info.
+    // (Yes, even if the column has its own collation, the sqlvariant still uses the database collation.)
+    // I'm not sure we even need to raise a warning, as MSSQL will return an error when the limit is exceeded itself.
+    if (comment && comment.length > 7500 / 2) {
       this.client.logger.warn(
-        'Your comment is longer than the max comment length for MSSQL'
+        'Your comment might be longer than the max comment length for MSSQL of 7,500 bytes.'
       );
     }
     return '';

package/lib/dialects/mssql/schema/mssql-tablecompiler.js

@@ -26,9 +26,10 @@ class TableCompiler_MSSQL extends TableCompiler {
 
     if (this.single.comment) {
       const { comment } = this.single;
-      if (comment.length > 60)
+      // XXX: This is a byte limit, not character, so we cannot definitively say they'll exceed the limit without database collation info.
+      if (comment.length > 7500 / 2)
         this.client.logger.warn(
-          'The max length for a table comment is 60 characters'
+          'Your comment might be longer than the max comment length for MSSQL of 7,500 bytes.'
         );
     }
 

package/lib/dialects/mysql/index.js

@@ -162,16 +162,18 @@ class Client_MySQL extends Client {
   }
 
   async cancelQuery(connectionToKill) {
-    const conn = await this.acquireConnection();
+    const conn = await this.acquireRawConnection();
     try {
-      return await this.query(conn, {
-        method: 'raw',
+      return await this._query(conn, {
         sql: 'KILL QUERY ?',
         bindings: [connectionToKill.threadId],
         options: {},
       });
     } finally {
-      await this.releaseConnection(conn);
+      await this.destroyRawConnection(conn);
+      if (conn.__knex__disposed) {
+        this.logger.warn(`Connection Error: ${conn.__knex__disposed}`);
+      }
     }
   }
 }

package/lib/dialects/postgres/index.js

@@ -237,24 +237,19 @@ class Client_PG extends Client {
   }
 
   async cancelQuery(connectionToKill) {
-    // Error out if we can't acquire connection in time.
-    // Purposely not putting timeout on `pg_cancel_backend` execution because erroring
-    // early there would release the `connectionToKill` back to the pool with
-    // a `KILL QUERY` command yet to finish.
-    const conn = await this.acquireConnection();
+    const conn = await this.acquireRawConnection();
 
     try {
       return await this._wrappedCancelQueryCall(conn, connectionToKill);
     } finally {
-      // NOT returning this promise because we want to release the connection
-      // in a non-blocking fashion
-      this.releaseConnection(conn);
+      await this.destroyRawConnection(conn).catch((err) => {
+        this.logger.warn(`Connection Error: ${err}`);
+      });
     }
   }
   _wrappedCancelQueryCall(conn, connectionToKill) {
-    return this.query(conn, {
-      method: 'raw',
-      sql: 'SELECT pg_cancel_backend(?);',
+    return this._query(conn, {
+      sql: 'SELECT pg_cancel_backend($1);',
       bindings: [connectionToKill.processID],
       options: {},
     });

package/lib/dialects/sqlite3/schema/ddl.js

@@ -334,49 +334,40 @@ class SQLite3_DDL {
     );
   }
 
-  async dropForeign(columns, indexName) {
+  async dropForeign(columns, foreignKeyName) {
     return this.client.transaction(
       async (trx) => {
         this.trx = trx;
 
         const { createTable, createIndices } = await this.getTableSql();
 
-        const oneLineSql = createTable.replace(/\s+/g, ' ');
-        const matched = oneLineSql.match(/^CREATE TABLE\s+(\S+)\s*\((.*)\)/);
-
-        const defs = matched[2];
+        const parsedTable = parseCreateTable(createTable);
 
-        if (!defs) {
-          throw new Error('No column definitions in this statement!');
+        if (!foreignKeyName) {
+          parsedTable.columns = parsedTable.columns.map((column) => ({
+            ...column,
+            references: columns.includes(column.name)
+              ? null
+              : column.references,
+          }));
         }
 
-        const updatedDefs = defs
-          .split(COMMA_NO_PAREN_REGEX)
-          .map((line) => line.trim())
-          .filter((defLine) => {
-            if (
-              defLine.toLowerCase().startsWith('constraint') === false &&
-              defLine.toLowerCase().includes('foreign key') === false
-            )
-              return true;
-
-            if (indexName) {
-              if (defLine.includes(indexName)) return false;
-              return true;
-            } else {
-              const matched = defLine.match(/\(`([^)]+)`\)/);
-              const columnNames = matched[1].split(', ');
-
-              const unknownColumnIncludedCheck = (col) =>
-                !columns.includes(col);
-              return columnNames.every(unknownColumnIncludedCheck) === false;
+        parsedTable.constraints = parsedTable.constraints.filter(
+          (constraint) => {
+            if (foreignKeyName) {
+              return constraint.name !== foreignKeyName;
             }
-          })
-          .join(', ');
 
-        const newSql = oneLineSql.replace(defs, updatedDefs);
+            return (
+              constraint.columns.some((column) => columns.includes(column)) ===
+              false
+            );
+          }
+        );
 
-        return this.alter(newSql, createIndices, (row) => {
+        const newTable = compileCreateTable(parsedTable, this.wrap);
+
+        return this.alter(newTable, createIndices, (row) => {
           return row;
         });
       },

package/lib/formatter/wrappingFormatter.js

@@ -34,6 +34,7 @@ const operators = transform(
     '<<',
     '>>',
     '~',
+    '~=',
     '~*',
     '!~',
     '!~*',

package/lib/knex-builder/Knex.js

@@ -6,7 +6,7 @@ const makeKnex = require('./make-knex');
 const { KnexTimeoutError } = require('../util/timeout');
 const { resolveConfig } = require('./internal/config-resolver');
 
-function Knex(config) {
+function knex(config) {
   const { resolvedConfig, Dialect } = resolveConfig(...arguments);
 
   const newKnex = makeKnex(new Dialect(resolvedConfig));
@@ -17,15 +17,15 @@ function Knex(config) {
 }
 
 // Expose Client on the main Knex namespace.
-Knex.Client = Client;
+knex.Client = Client;
 
-Knex.KnexTimeoutError = KnexTimeoutError;
+knex.KnexTimeoutError = KnexTimeoutError;
 
-Knex.QueryBuilder = {
+knex.QueryBuilder = {
   extend: function (methodName, fn) {
     QueryBuilder.extend(methodName, fn);
     QueryInterface.push(methodName);
   },
 };
 
-module.exports = Knex;
+module.exports = knex;

package/lib/knex-builder/internal/config-resolver.js

@@ -23,8 +23,7 @@ function resolveConfig(config) {
   }
   // If user provided Client constructor as a parameter, use it
   else if (
-    typeof parsedConfig.client === 'function' &&
-    parsedConfig.client.prototype instanceof Client
+    typeof parsedConfig.client === 'function'
   ) {
     Dialect = parsedConfig.client;
   }

package/lib/migrations/migrate/stub/ts.stub

@@ -1,8 +1,8 @@
-import * as Knex from "knex";
+import { Knex } from "knex";
 
 <% if (d.tableName) { %>
 export async function up(knex: Knex): Promise<Knex.SchemaBuilder> {
-    return knex.schema.createTable("<%= d.tableName %>", (t: Knex.AlterTableBuilder) => {
+    return knex.schema.createTable("<%= d.tableName %>", (t) => {
         t.increments();
         t.timestamps();
     });

package/lib/migrations/seed/stub/ts.stub

@@ -1,4 +1,4 @@
-import * as Knex from "knex";
+import { Knex } from "knex";
 
 export async function seed(knex: Knex): Promise<void> {
     // Deletes ALL existing entries

package/lib/query/querybuilder.js

@@ -908,6 +908,8 @@ class Builder extends EventEmitter {
       const val = parseInt(value, 10);
       if (isNaN(val)) {
         this.client.logger.warn('A valid integer must be provided to offset');
+      } else if (val < 0) {
+        throw new Error(`A non-negative integer must be provided to offset.`);
       } else {
         this._single.offset = val;
       }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "knex",
-  "version": "0.95.0",
+  "version": "0.95.4",
   "description": "A batteries-included SQL query & schema builder for Postgres, MySQL and SQLite3 and the Browser",
-  "main": "knex.js",
+  "main": "knex",
   "types": "types/index.d.ts",
   "engines": {
     "node": ">=10"
@@ -49,7 +49,7 @@
     "esm": "^3.2.25",
     "getopts": "2.2.5",
     "interpret": "^2.2.0",
-    "lodash": "^4.17.20",
+    "lodash": "^4.17.21",
     "pg-connection-string": "2.4.0",
     "rechoir": "^0.7.0",
     "resolve-from": "^5.0.0",
@@ -57,11 +57,11 @@
     "tildify": "2.0.0"
   },
   "peerDependencies": {
-    "tedious": "^11.0.3",
     "mysql": "^2.18.1",
     "mysql2": "^2.2.5",
     "pg": "^8.5.1",
-    "sqlite3": "^5.0.0"
+    "sqlite3": "^5.0.0",
+    "tedious": "^11.0.5"
   },
   "peerDependenciesMeta": {
     "tedious": {
@@ -88,19 +88,19 @@
   },
   "devDependencies": {
     "@types/node": "^14.14.28",
-    "JSONStream": "^1.3.5",
-    "chai": "^4.3.0",
+    "chai": "^4.3.3",
     "chai-as-promised": "^7.1.1",
     "chai-subset-in-order": "^2.1.4",
     "cli-testlab": "^2.2.0",
     "coveralls": "^3.1.0",
     "cross-env": "^7.0.3",
-    "dtslint": "4.0.7",
+    "dtslint": "4.0.8",
     "eslint": "^7.20.0",
     "eslint-config-prettier": "^8.1.0",
     "eslint-plugin-import": "^2.22.1",
     "husky": "^4.3.8",
     "jake": "^8.1.1",
+    "JSONStream": "^1.3.5",
     "lint-staged": "^10.5.4",
     "mocha": "^8.3.0",
     "mock-fs": "^4.13.0",
@@ -117,12 +117,12 @@
     "source-map-support": "^0.5.19",
     "sqlite3": "^5.0.1",
     "tap-spec": "^5.0.0",
-    "tape": "^5.1.1",
-    "tedious": "^11.0.3",
+    "tape": "^5.2.2",
+    "tedious": "^11.0.5",
     "toxiproxy-node-client": "^2.0.6",
     "ts-node": "^9.1.1",
     "tsd": "^0.14.0",
-    "typescript": "4.2.2"
+    "typescript": "4.2.3"
   },
   "buildDependencies": [
     "rimraf"

package/types/index.d.ts

@@ -397,6 +397,20 @@ export declare function knex<TRecord extends {} = any, TResult = unknown[]>(
   config: Knex.Config | string
 ): Knex<TRecord, TResult>;
 
+export declare namespace knex {
+  class QueryBuilder {
+    static extend(
+      methodName: string,
+      fn: <TRecord extends {} = any, TResult = unknown[]>(
+        this: Knex.QueryBuilder<TRecord, TResult>,
+        ...args: any[]
+      ) => Knex.QueryBuilder<TRecord, TResult>
+    ): void;
+  }
+
+  export class KnexTimeoutError extends Error {}
+}
+
 export declare namespace Knex {
   //
   // Utility Types
@@ -1403,6 +1417,16 @@ export declare namespace Knex {
   }
 
   interface TypePreservingAggregation<TRecord = any, TResult = unknown[], TValue = any> {
+    <
+      TKey extends keyof ResolveTableType<TRecord>,
+      TOptions extends { "as": string },
+      TResult2 = AggregationQueryResult<TResult, {
+        [k in TOptions["as"]]: ResolveTableType<TRecord>[TKey]
+      }>
+    >(
+      columnName: Readonly<TKey>,
+      options: Readonly<TOptions>
+    ): QueryBuilder<TRecord, TResult2>;
     <
       TKey extends keyof ResolveTableType<TRecord>,
       TResult2 = AggregationQueryResult<TResult, Dict<ResolveTableType<TRecord>[TKey]>>
@@ -1718,7 +1742,7 @@ export declare namespace Knex {
       options: Readonly<{ [key: string]: any }>,
       handler: (readable: stream.PassThrough) => any
     ): Promise<any>;
-    stream(options?: Readonly<{ [key: string]: any }>): stream.PassThrough;
+    stream(options?: Readonly<{ [key: string]: any }>): stream.PassThrough & AsyncIterable<ArrayMember<T>>;
     pipe<T extends NodeJS.WritableStream>(
       writable: T,
       options?: Readonly<{ [key: string]: any }>
@@ -1845,7 +1869,7 @@ export declare namespace Knex {
       columns: readonly string[],
       foreignKeyName?: string
     ): MultikeyForeignConstraintBuilder;
-    dropForeign(columnNames: readonly string[], foreignKeyName?: string): TableBuilder;
+    dropForeign(columnNames: string | readonly string[], foreignKeyName?: string): TableBuilder;
     dropUnique(columnNames: readonly (string | Raw)[], indexName?: string): TableBuilder;
     dropPrimary(constraintName?: string): TableBuilder;
     dropIndex(columnNames: string | readonly (string | Raw)[], indexName?: string): TableBuilder;
@@ -2350,10 +2374,6 @@ interface MsSqlConnectionConfigBase {
     constraintName?: string;
   }
 
-  //
-  // Clients
-  //
-
   class Client extends events.EventEmitter {
     constructor(config: Config);
     config: Config;
@@ -2408,18 +2428,6 @@ interface MsSqlConnectionConfigBase {
     assertCanCancelQuery(): void;
     cancelQuery(): void;
   }
-
-  class QueryBuilder {
-    static extend(
-      methodName: string,
-      fn: <TRecord extends {} = any, TResult = unknown[]>(
-        this: QueryBuilder<TRecord, TResult>,
-        ...args: any[]
-      ) => QueryBuilder<TRecord, TResult>
-    ): void;
-  }
-
-  export class KnexTimeoutError extends Error {}
 }
 
 export default knex;