knex 2.5.0 → 3.0.0

package/UPGRADING.md

@@ -1,233 +1,245 @@
-## Upgrading to new knex.js versions
-
-### Upgrading to version 2.0.0+
-
-* Since `sqlite3` is maintained again, we switched back to it. If you are using `@vscode/sqlite3` driver dependency, please replace it with `sqlite3` in your `package.json`;
-
-### Upgrading to version 1.0.0+
-
-* Node.js older than 12 is no longer supported, make sure to update your environment;
-* If you are using `sqlite3` driver dependency, please replace it with `@vscode/sqlite3` in your `package.json`;
-* `RETURNING` operations now always return an object with column names;
-* Migrator now returns list of migrations as objects.
-
-### 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
-
-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('*')
-```
-
-* IDE autocomplete may stop working if you are using JavaScript (not TypeScript). There are reports for autocomplete still working correctly if knex is used this way:
-```js
-  const knex = require('knex').knex({
-    //connection parameters
-  });
-```
-
-It also works when using ESM imports:
-```js
-  import { knex } from 'knex'
-
-  const kn = knex({
-    //connection parameters
-  })
-```
-
-For usage as param it can be addressed like this:
-```js
-  /**
-   * @param {import("knex").Knex} db
-   */
-  function up(db) {
-    // Your code
-  }
-```
-
-* 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.
-
-* Transaction rollback does not trigger a promise rejection for transactions with specified handler. If you want to preserve previous behavior, pass `config` object with `doNotRejectOnRollback: false`:
-```js
-  await knex.transaction(async trx => {
-    const ids = await trx('catalogues')
-      .insert({
-        name: 'Old Books'
-      }, 'id')
-  }, { doNotRejectOnRollback: false });
-```
-
-* Connection url parsing changed from legacy [url.parse](https://nodejs.org/docs/latest-v10.x/api/url.html#url_legacy_url_api) to [WHATWG URL](https://nodejs.org/docs/latest-v10.x/api/url.html#url_the_whatwg_url_api). If you have symbols, unusual for a URL (not A-z, not digits, not dot, not dash) - check [Node.js docs](https://nodejs.org/docs/latest-v10.x/api/url.html#url_percent_encoding_in_urls) for details
-
-* Global static `Knex.raw` support dropped, use instance `knex.raw` instead. (`require('knex').raw()` won't work anymore)
-
-* v8 flags are no longer supported in cli. To pass these flags use [`NODE_OPTIONS` environment variable](https://nodejs.org/api/cli.html#cli_node_options_options).
-  For example `NODE_OPTIONS="--max-old-space-size=1536" npm run knex`
-
-* Clients are now classes instead of new-able functions. Please migrate your custom clients to classes.
-
-```js
-const Client = require('knex')
-const {inherits} = require('util')
-
-// old
-function CustomClient(config) {
-  Client.call(this, config);
-  // construction logic
-}
-inherits(CustomClient, Client);
-CustomClient.prototype.methodOverride = function () {
-  // logic
-}
-
-// new
-class CustomClient extends Client {
-  // node 12+
-  driverName = 'abcd';
-  constructor(config) {
-    super(config);
-    this.driverName = 'abcd'; // bad way, will not work
-    // construction logic
-  }
-  methodOverride() {
-    // logic
-  }
-}
-// alternative to declare driverName
-CustomClient.prototype.driverName = 'abcd';
-```
-
-* There was a major internal restructuring and renaming effort. Most dialect-specific compilers/builder have dialect name as a prefix now. Also some files were moved. Make sure to make adjustments accordingly if you were referencing specific knex library files directly from your code.
-
-* "first" and "pluck" can no longer be both chained on the same operation. Previously only the last one chained was used, now this would throw an error. 
-
-* Trying to execute an operation resulting in an empty query such as inserting an empty array, will now throw an error on all database drivers.
-
-### Upgrading to version 0.21.0+
-
-* Node.js older than 10 is no longer supported, make sure to update your environment; 
-
-### Upgrading to version 0.19.0+
-
-* Passing unknown properties to connection pool configuration now throws errors (see https://github.com/Vincit/tarn.js/issues/19 for details);
-* `beforeDestroy` pool configuration option was removed. You should use tarn.js event handlers if you still need similar functionality.
-
-### Upgrading to version 0.18.0+
-
-* Node.js older than 8 is no longer supported, make sure to update your environment;
-* Knex returns native promises instead of bluebird ones now. You will need to update your code not to rely on bluebird-specific functionality;
-* Knex.Promise was removed, use native promises;
-* Promise is no longer passed to migrations and seeds, use native one;
-* If you are using TypeScript, make sure to include 'es6' in compilerOptions.lib, otherwise you may get errors for methods `.catch()` and `then()` not being recognized.
-
-### Upgrading to version 0.17.0+
-
-* Generic support was implemented for TypeScript bindings, which may break TS builds in some edge cases. Please refer to https://knexjs.org/#typescript-support for more elaborate documentation.
-
-### Upgrading to version 0.16.0+
-
-* MSSQL: DB versions older than 2008 are no longer supported, make sure to update your DB;
-* PostgreSQL|MySQL: it is recommended to use options object for `table.datetime` and `table.timestamp` methods instead of argument options. See documentation for these methods for more details; 
-* Node 6: There are known issues with duplicate event listeners when using knex.js with Node.js 6 (resulting in MaxListenersExceededWarning under certain use-cases (such as reusing single knex instance to run migrations or seeds multiple times)). Please upgrade to Node.js 8+ as soon as possible (knex 0.17.0 will be dropping Node.js 6 support altogether);
-
-### Upgrading to version 0.15.0+
-
-* Node.js older than 6 is no longer supported, make sure to update your environment;
-
-* MSSQL: Creating a unique index on the table targeted by stored procedures that were created with QUOTED_IDENTIFIER = OFF fails.
-
-You can use this query to identify all affected stored procedures:
-
-```
-SELECT name = OBJECT_NAME([object_id]), uses_quoted_identifier
-FROM sys.sql_modules
-WHERE uses_quoted_identifier = 0;
-```
-
-The only known solution is to recreate all stored procedures with QUOTED_IDENTIFIER = OFF
-
-* MariaDB: `mariadb` dialect is no longer supported;
-
-Instead, use "mysql" or "mysql2" dialects.
-
-### Upgrading to version 0.14.4+
-
-* Including schema in tableName parameter in migrations no longer works, so this is invalid:
-
-```js
-await knex.migrate.latest({
-    directory: 'src/services/orders/database/migrations',
-    tableName: 'orders.orders_migrations'
-})
-```
-
-Instead, starting from 0.14.5 you should use new parameter schemaName:
-
-```js
-await knex.migrate.latest({
-    directory: 'src/services/orders/database/migrations',
-    tableName: 'orders_migrations',
-    schemaName: 'orders'
-})
-```
-
+## Upgrading to new knex.js versions
+
+### Upgrading to version 2.0.0+
+
+- Since `sqlite3` is maintained again, we switched back to it. If you are using `@vscode/sqlite3` driver dependency, please replace it with `sqlite3` in your `package.json`;
+
+### Upgrading to version 1.0.0+
+
+- Node.js older than 12 is no longer supported, make sure to update your environment;
+- If you are using `sqlite3` driver dependency, please replace it with `@vscode/sqlite3` in your `package.json`;
+- `RETURNING` operations now always return an object with column names;
+- Migrator now returns list of migrations as objects.
+
+### 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
+
+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('*');
+```
+
+- IDE autocomplete may stop working if you are using JavaScript (not TypeScript). There are reports for autocomplete still working correctly if knex is used this way:
+
+```js
+const knex = require('knex').knex({
+  //connection parameters
+});
+```
+
+It also works when using ESM imports:
+
+```js
+import { knex } from 'knex';
+
+const kn = knex({
+  //connection parameters
+});
+```
+
+For usage as param it can be addressed like this:
+
+```js
+/**
+ * @param {import("knex").Knex} db
+ */
+function up(db) {
+  // Your code
+}
+```
+
+- 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.
+
+- Transaction rollback does not trigger a promise rejection for transactions with specified handler. If you want to preserve previous behavior, pass `config` object with `doNotRejectOnRollback: false`:
+
+```js
+await knex.transaction(
+  async (trx) => {
+    const ids = await trx('catalogues').insert({ name: 'Old Books' }, 'id');
+  },
+  { doNotRejectOnRollback: false }
+);
+```
+
+- Connection url parsing changed from legacy [url.parse](https://nodejs.org/docs/latest-v10.x/api/url.html#url_legacy_url_api) to [WHATWG URL](https://nodejs.org/docs/latest-v10.x/api/url.html#url_the_whatwg_url_api). If you have symbols, unusual for a URL (not A-z, not digits, not dot, not dash) - check [Node.js docs](https://nodejs.org/docs/latest-v10.x/api/url.html#url_percent_encoding_in_urls) for details
+
+- Global static `Knex.raw` support dropped, use instance `knex.raw` instead. (`require('knex').raw()` won't work anymore)
+
+- v8 flags are no longer supported in cli. To pass these flags use [`NODE_OPTIONS` environment variable](https://nodejs.org/api/cli.html#cli_node_options_options).
+  For example `NODE_OPTIONS="--max-old-space-size=1536" npm run knex`
+
+- Clients are now classes instead of new-able functions. Please migrate your custom clients to classes.
+
+```js
+const Client = require('knex');
+const { inherits } = require('util');
+
+// old
+function CustomClient(config) {
+  Client.call(this, config);
+  // construction logic
+}
+inherits(CustomClient, Client);
+CustomClient.prototype.methodOverride = function () {
+  // logic
+};
+
+// new
+class CustomClient extends Client {
+  // node 12+
+  driverName = 'abcd';
+  constructor(config) {
+    super(config);
+    this.driverName = 'abcd'; // bad way, will not work
+    // construction logic
+  }
+  methodOverride() {
+    // logic
+  }
+}
+// alternative to declare driverName
+CustomClient.prototype.driverName = 'abcd';
+```
+
+- There was a major internal restructuring and renaming effort. Most dialect-specific compilers/builder have dialect name as a prefix now. Also some files were moved. Make sure to make adjustments accordingly if you were referencing specific knex library files directly from your code.
+
+- "first" and "pluck" can no longer be both chained on the same operation. Previously only the last one chained was used, now this would throw an error.
+
+- Trying to execute an operation resulting in an empty query such as inserting an empty array, will now throw an error on all database drivers.
+
+### Upgrading to version 0.21.0+
+
+- Node.js older than 10 is no longer supported, make sure to update your environment;
+
+### Upgrading to version 0.19.0+
+
+- Passing unknown properties to connection pool configuration now throws errors (see https://github.com/Vincit/tarn.js/issues/19 for details);
+- `beforeDestroy` pool configuration option was removed. You should use tarn.js event handlers if you still need similar functionality.
+
+### Upgrading to version 0.18.0+
+
+- Node.js older than 8 is no longer supported, make sure to update your environment;
+- Knex returns native promises instead of bluebird ones now. You will need to update your code not to rely on bluebird-specific functionality;
+- Knex.Promise was removed, use native promises;
+- Promise is no longer passed to migrations and seeds, use native one;
+- If you are using TypeScript, make sure to include 'es6' in compilerOptions.lib, otherwise you may get errors for methods `.catch()` and `then()` not being recognized.
+
+### Upgrading to version 0.17.0+
+
+- Generic support was implemented for TypeScript bindings, which may break TS builds in some edge cases. Please refer to https://knexjs.org/#typescript-support for more elaborate documentation.
+
+### Upgrading to version 0.16.0+
+
+- MSSQL: DB versions older than 2008 are no longer supported, make sure to update your DB;
+- PostgreSQL|MySQL: it is recommended to use options object for `table.datetime` and `table.timestamp` methods instead of argument options. See documentation for these methods for more details;
+- Node 6: There are known issues with duplicate event listeners when using knex.js with Node.js 6 (resulting in MaxListenersExceededWarning under certain use-cases (such as reusing single knex instance to run migrations or seeds multiple times)). Please upgrade to Node.js 8+ as soon as possible (knex 0.17.0 will be dropping Node.js 6 support altogether);
+
+### Upgrading to version 0.15.0+
+
+- Node.js older than 6 is no longer supported, make sure to update your environment;
+
+- MSSQL: Creating a unique index on the table targeted by stored procedures that were created with QUOTED_IDENTIFIER = OFF fails.
+
+You can use this query to identify all affected stored procedures:
+
+```
+SELECT name = OBJECT_NAME([object_id]), uses_quoted_identifier
+FROM sys.sql_modules
+WHERE uses_quoted_identifier = 0;
+```
+
+The only known solution is to recreate all stored procedures with QUOTED_IDENTIFIER = OFF
+
+- MariaDB: `mariadb` dialect is no longer supported;
+
+Instead, use "mysql" or "mysql2" dialects.
+
+### Upgrading to version 0.14.4+
+
+- Including schema in tableName parameter in migrations no longer works, so this is invalid:
+
+```js
+await knex.migrate.latest({
+  directory: 'src/services/orders/database/migrations',
+  tableName: 'orders.orders_migrations',
+});
+```
+
+Instead, starting from 0.14.5 you should use new parameter schemaName:
+
+```js
+await knex.migrate.latest({
+  directory: 'src/services/orders/database/migrations',
+  tableName: 'orders_migrations',
+  schemaName: 'orders',
+});
+```