Skip to content

public / sequelize

Go to a project

不要怂，就是干，撸起袖子干！

Commit 8dbeb6c9 by Sushant
Options

docs: update upgrade guide

1 parent ab1c1e34
Inline Side-by-side
Showing with 81 additions and 81 deletions
docs/upgrade-to-v4.md
# Upgrade to V4
Sequelize V4 is a major release and it introduces new features and breaking changes. Majority of sequelize codebase has been refactored to use ES2015 features. The following guide lists some of the changes to upgrade from v3 to v4. See the [Changelog](https://github.com/sequelize/sequelize/blob/b49f936e9aa316cf4a13bade76585acf4d5d8b04/changelog.md) for full list of changes.
Sequelize v4 is the current release and it introduces some breaking changes. Majority of sequelize codebase has been refactored to use ES2015 features. The following guide lists some of the changes to upgrade from v3 to v4.
### Breaking Changes
## Changelog
- Node version: To use new ES2015 features, we now require at least Node 4. From now on, we will support all current LTS versions of Node.
- The counter cache plugin, and consequently the counterCache option for associations has been removed. The same behaviour can be achieved using `afterCreate` and `afterDelete` hooks.
- Removed MariaDB dialect. This was just a thin wrapper around MySQL, so using `dialect: 'mysql'` instead should work with no further changes
- Removed default `REPEATABLE_READ` transaction isolation. The isolation level now defaults to that of the database. Explicitly pass the required isolation level when initiating the transaction.
- Removed support for `pool: false`. To use a single connection, set `pool.max` to 1.
- Removed support for old connection pooling configuration keys. Instead of
Full [Changelog](https://github.com/sequelize/sequelize/blob/b49f936e9aa316cf4a13bade76585acf4d5d8b04/changelog.md) for v4 release.
## Breaking Changes
### Node
To use new ES2015 features, Sequelize v4 requires at least Node v4 or above.
### General
* Counter Cache plugin and consequently the ```counterCache``` option for associations has been removed.
* MariaDB dialect now removed. This was just a thin wrapper around MySQL. You can set ``dialect: 'mysql'`` an d Sequelize should be able to work with MariaDB server.
* `Model.Instance` and `instance.Model` are removed. To access the Model from an instance, simply use [`instance.constructor`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor). The Instance class (`Model.Instance`) is now the Model itself.
* Sequelize now uses an independent copy of bluebird library.
* Promises returned by sequelize are now instances of `Sequelize.Promise` instead of global bluebird `Promise`.
* Pooling library was updated to `v3`, now you will need to call `sequelize.close()` to shutdown the pool.
### Config / Options
* Removed support for old connection pooling configuration keys. Instead of
**Old**
```js
pool: {
maxIdleTime: 30000,
......@@ -18,8 +34,7 @@ Sequelize V4 is a major release and it introduces new features and breaking chan
}
```
use
**New**
```js
pool: {
idle: 30000,
......@@ -27,25 +42,19 @@ Sequelize V4 is a major release and it introduces new features and breaking chan
max: 30
}
```
- (MySQL) BIGINT now gets converted to string when number is too big
- (MySQL) `DECIMAL` and `NEWDECIMAL` types now returned as String unless
```js
dialectOptions: {
decimalNumbers: true
}
```
is specified.
- Removed support for referencesKey, use a references object
* Removed support for `pool: false`. To use a single connection, set `pool.max` to 1.
* Removed support for ``referencesKey``, use a references object
```js
references: {
key: '',
model: ''
}
```
- `classMethods` and `instanceMethods` are removed.
* Removed `classMethods` and `instanceMethods` options from `sequelize.define`. Sequelize models
are now ES6 classes. You can set class / instance level methods like this
**Old**
Previous:
```js
const Model = sequelize.define('Model', {
...
......@@ -59,7 +68,7 @@ Sequelize V4 is a major release and it introduces new features and breaking chan
});
```
New:
**New**
```js
const Model = sequelize.define('Model', {
......@@ -74,52 +83,70 @@ Sequelize V4 is a major release and it introduces new features and breaking chan
// Instance Method
Model.prototype.someMethod = function () {..}
```
- `Model.Instance` and `instance.Model` are removed. To access the Model from an instance, simply use [`instance.constructor`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor). The Instance class (`Model.Instance`) is now the Model itself.
- Sequelize now uses an independent copy of bluebird library.
- Promises returned by sequelize are now instances of `Sequelize.Promise` instead of global bluebird `Promise`.
- The CLS patch does not affect global bluebird promise. Transaction will not automatically get passed to methods when used with `Promise.all` and other bluebird methods. Explicitly patch your bluebird instance to get CLS to work with bluebird methods.
* `options.order` now only accepts values with type of array or Sequelize method. Support for string values (ie `{order: 'name DESC'}`) has been deprecated.
* With `BelongsToMany` relationships `add/set/create` setters now set through attributes by passing them as `options.through` (previously second argument was used as through attributes, now it's considered options with `through` being a sub option)
* Raw options for where, order and group like `where: { $raw: '..', order: [{ raw: '..' }], group: [{ raw: '..' }] }` have been removed to prevent SQL injection attacks.
**Old**
```js
user.addProject(project, { status: 'started' });
```
**New**
```js
user.addProject(project, { through: { status: 'started' } });
```
### Data Types
* (MySQL/Postgres) `BIGINT` now returned as string.
* (MySQL/Postgres) `DECIMAL` and `NEWDECIMAL` types now returned as string.
* (MSSQL) `DataTypes.DATE` now uses `DATETIMEOFFSET` instead of `DATETIME2` sql datatype in case of MSSQL to record timezone. To migrate existing `DATETIME2` columns into `DATETIMEOFFSET`, see [#7201](https://github.com/sequelize/sequelize/pull/7201#issuecomment-278899803).
* `DATEONLY` now returns string in `YYYY-MM-DD` format rather than `Date` type
### Transactions / CLS
* Removed `autocommit: true` default, set this option explicitly to have transactions auto commit.
* Removed default `REPEATABLE_READ` transaction isolation. The isolation level now defaults to that of the database. Explicitly pass the required isolation level when initiating the transaction.
* The CLS patch does not affect global bluebird promise. Transaction will not automatically get passed to methods when used with `Promise.all` and other bluebird methods. Explicitly patch your bluebird instance to get CLS to work with bluebird methods.
```bash
$ npm install --save cls-bluebird
```
```js
const Promise = require('bluebird');
const Sequelize = require('sequelize');
const Promise = require('bluebird');
const clsBluebird = require('cls-bluebird');
const cls = require('continuation-local-storage');
const ns = cls.createNamespace('transaction-namespace');
const clsBluebird = require('cls-bluebird');
clsBluebird(ns, Promise);
Sequelize.useCLS(ns);
```
- `Sequelize.Validator` is now an independent copy of `validator` library
- `DataTypes.DECIMAL` returns string for MySQL and Postgres.
- `DataTypes.DATE` now uses `DATETIMEOFFSET` instead of `DATETIME2` sql datatype in case of MSSQL to record timezone. To migrate existing `DATETIME2` columns into `DATETIMEOFFSET`, see [#7201](https://github.com/sequelize/sequelize/pull/7201#issuecomment-278899803).
- `options.order` now only accepts values with type of array or Sequelize method. Support for string values (ie `{order: 'name DESC'}`) has been deprecated.
- With `BelongsToMany` relationships `add/set/create` setters now set through attributes by passing them as `options.through` (previously second argument was used as through attributes, now it's considered options with `through` being a sub option)
Previous:
```js
user.addProject(project, { status: 'started' })
```
### Raw Queries
New:
```js
user.addProject(project, { through: { status: 'started' }})
```
* Sequelize now supports bind parameters for all dialects. In v3 `bind` option would fallback to `replacements` if dialect didn't supported binding. This could be a breaking change for MySQL / MSSQL where now queries will actually use bind parameters instead of replacements fallback.
- `DATEONLY` now returns string in `YYYY-MM-DD` format rather than `Date` type
- `Model.validate` instance method now runs validation hooks by default. Previously you needed to pass `{ hooks: true }`. You can override this behavior by passing `{ hooks: false }`
- The resulting promise from the `Model.validate` instance method will be rejected when validation fails. It will fulfill when validation succeeds.
- Raw options for where, order and group like `where: { $raw: '..', order: [{ raw: '..' }], group: [{ raw: '..' }] }` have been removed to prevent SQL injection attacks.
- `Sequelize.Utils` is not longer part of the public API, use it at your own risk
- `Hooks` should return Promises now. Callbacks are deprecated.
- `required` inside include does not propagate up the include chain.
### Others
* `Sequelize.Validator` is now an independent copy of `validator` library.
* `Model.validate` instance method now runs validation hooks by default. Previously you needed to pass `{ hooks: true }`. You can override this behavior by passing `{ hooks: false }`.
* The resulting promise from the `Model.validate` instance method will be rejected when validation fails. It will fulfill when validation succeeds.
* `Sequelize.Utils` is not longer part of the public API, use it at your own risk.
* `Hooks` should return Promises now. Callbacks are deprecated.
* Getters wont run with `instance.get({ raw: true })`, use `instance.get({ plain: true })`
* `required` inside include does not propagate up the include chain.
To get v3 compatible results you'll need to either set `required` on the containing include.
Previous:
**Old**
```js
user.findOne({
include: {
......@@ -132,7 +159,8 @@ Sequelize V4 is a major release and it introduces new features and breaking chan
});
```
New:
**New**
```js
User.findOne({
include: {
......@@ -151,13 +179,14 @@ Sequelize V4 is a major release and it introduces new features and breaking chan
required: true,
include: {
model: Task,
where: {type: 'important'} //where cause required to default to true
where: { type: 'important' } //where cause required to default to true
}
}
});
```
Optionally you can add a `beforeFind` hook to get v3 compatible behavior -
```js
function propagateRequired(modelDescriptor) {
let include = modelDescriptor.include;
......@@ -183,32 +212,3 @@ Sequelize V4 is a major release and it introduces new features and breaking chan
}
});
```
### New features
- Initial version of `sequelize.sync({ alter: true })` has been added and uses `ALTER TABLE` commands to sync tables. [Migrations](http://docs.sequelizejs.com/manual/tutorial/migrations.html) are still preferred and should be used in production.
- Adding and removing database contraints are now supported. Existing primary, foreignKey and other contraints can now be added/removed using migrations - [See more](http://docs.sequelizejs.com/manual/tutorial/migrations.html#addconstraint-tablename-attributes-options-).
- Instances (database rows) are now instances of the model, instead of being an instance of a separate class. This means you can replace `User.build()` with `new User()` and `sequelize.define(attributes, options)` with
```js
class User extends Sequelize.Model {}
User.init(attributes, options)
```
You can then define custom methods, class methods and getters/setter directly in the class.
This also enables more usage patterns, for example with [decorators](https://www.npmjs.com/package/sequelize-decorators).
- Added `DEBUG` support. You can now use `DEBUG=sequelize* node app.js` to enable logging for all sequelize operations. To filter logged queries, use `DEBUG=sequelize:sql:mssql sequelize:connection*` to log generated SQL queries, connection info etc.
- `JSON` datatype support has been added for `SQLite`
- `UPSERT` is now supported on `MSSQL` using `MERGE` statement.
- Transactions are now fully supported on `MSSQL`.
- Filtered indexes are now supported on `MSSQL` dialect.
```js
queryInterface.addIndex(
'Person',
['firstname', 'lastname'],
{
where: {
lastname: {
$ne: null
}
}
}
)
```
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!