## 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'
})
```