234 lines
8.6 KiB
Markdown
234 lines
8.6 KiB
Markdown
|
## 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'
|
||
|
})
|
||
|
```
|
||
|
|