Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

283 lines (260 sloc) 11.882 kB
extends layout
block append style
style.
table td {
padding-right: 15px;
}
block content
h2 Migrating from 2.x to 3.x
:markdown
Migrating from Mongoose 2.x to 3.x brings with it [several changes](https://github.com/LearnBoost/mongoose/blob/master/History.md) to be aware of:
h3 Query clean-up
:markdown
Many methods of the [Query](./api.html#query-js) API were nothing but aliases and have been [removed](https://github.com/LearnBoost/mongoose/commit/1149804c) in an effort to keep Mongoose clean and focused on there being as close to [one way](http://www.python.org/dev/peps/pep-0020/) of doing things as possible. If you really love all that extra noise, you can bring most of it back with [this module](https://github.com/aheckmann/mongoose-v2-compat).
Here are the removed methods and their still existing aliases:
table
thead
tr(style='text-align:left')
th Removed
th Alternative
tbody
tr
td
code query.run
td
code query.exec
tr
td
code query.$or
td
code query.or
tr
td
code query.$nor
td
code query.nor
tr
td
code query.$gt
td
code query.gt
tr
td
code query.$gte
td
code query.gte
tr
td
code query.$lt
td
code query.lt
tr
td
code query.$lte
td
code query.lte
tr
td
code query.$ne
td
code query.ne
tr
td
code query.$in
td
code query.in
tr
td
code query.$nin
td
code query.nin
tr
td
code query.$all
td
code query.all
tr
td
code query.$regex
td
code query.regex
tr
td
code query.$size
td
code query.size
tr
td
code query.$maxDistance
td
code query.maxDistance
tr
td
code query.$mod
td
code query.mod
tr
td
code query.$near
td
code query.near
tr
td
code query.$exists
td
code query.exists
tr
td
code query.$elemMatch
td
code query.elemMatch
tr
td
code query.$within
td
code query.within
tr
td
code query.$box
td
code query.box
tr
td
code query.$center
td
code query.center
tr
td
code query.$centerSphere
td
code query.centerSphere
tr
td
code query.$slice
td
code query.slice
tr
td
code query.notEqualTo
td
code query.ne
tr
td
code query.wherein
td
code query.within
tr
td
code query.asc
td
code
| query.sort
a(href="#asc") *
tr
td
code query.desc
td
code
| query.sort
a(href="#desc") *
tr
td
code query.fields
td
code
| query.select
a(href="#fields") *
h4#asc query#asc
:markdown
The `asc` method of [Query](./api.html#query-js) has been removed in favor of [sort](./api.html#query_Query-sort). The `sort` method accepts slightly different arguments so read the [docs](./api.html#query_Query-sort) to make sure your application is all set.
h4#desc query#desc
:markdown
The `desc` method of [Query](./api.html#query-js) has been removed in favor of [sort](./api.html#query_Query-sort). The `sort` method accepts slightly different arguments so read the [docs](./api.html#query_Query-sort) to make sure your application is all set.
h4#sort query#sort
:markdown
The [sort](./api.html#query_Query-sort) method of [Queries](./api.html#query-js) now accepts slightly different arguments. Read the [docs](./api.html#query_Query-sort) to make sure your application is all set.
h4#fields query#fields
:markdown
The `fields` method of [Query](./api.html#query-js) has been removed, it being mostly an alias for the [select](./api.html#query_Query-select) method anyway. The `select` method has slightly different arguments so read the [docs](./api.html#query_Query-select) to make sure your application is all set.
Because of the change to the `fields` method, the field selection argument for [query.populate](./api.html#query_Query-populate) and model methods like [findById](./api.html#model_Model-findById), [find](./api.html#model_Model-find), etc, is slightly different as well (no longer accepts arrays for example), so read the [docs](./api.html#query_Query-select) to make sure your application is all set.
h3 Connecting to ReplicaSets
:markdown
To connect to a [ReplicaSet](http://www.mongodb.org/display/DOCS/Replica+Sets) you no longer use the separate `connectSet` or `createSetConnection` methods. Both [mongoose.connect](./api.html#index_Mongoose-connect) and [mongoose.createConnection](./api.html#index_Mongoose-createConnection) are now smart enough to just do the right thing with your connection string. If you really want to bring `connectSet` and `createSetConnection` back use [this module](https://github.com/aheckmann/mongoose-v2-compat).
h3 Schemas
.important
:markdown
Schemas are now [strict](./guide.html#strict) by default. This means that if you depended on saving fields not defined in the schema, you may lose data unless you set this back to false.
:markdown
- Arrays of [object literal](./subdocs.html#altsyntax) now creates document arrays instead of arrays of [Mixed](./schematypes.html#mixed).
- Indexes are now created in [background](./guide.html#autoIndex) by default.
- Index errors are now emitted on their model instead of the connection. See issue [#984](https://github.com/LearnBoost/mongoose/issues/984).
h3#arrays Arrays
:markdown
- [pop](./api.html#types_array_MongooseArray-pop) is now fixed causing a $set of the entire array.
- [$pop](./api.html#types_array_MongooseArray-%24pop) is now fixed and behaves just as MongoDB [$pop](http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop) does, removing at most the last element of the array.
- [shift](./api.html#types_array_MongooseArray-shift) is now fixed causing a $set of the entire array.
- [$shift](./api.html#types_array_MongooseArray-%24shift) is now fixed and behaves just as a [MongoDB $pop -1](http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop) does, removing at most the first element of array.
- `$unshift` was removed, use [unshift](./api.html#types_array_MongooseArray-unshift) instead.
- `$addToSet` was removed, use [addToSet](./api.html#types_array_MongooseArray-addToSet) instead.
- `$pushAll` was removed, use [push](./api.html#types_array_MongooseArray-push) instead.
- `$pull` was removed, use [pull](./api.html#types_array_MongooseArray-pull) instead.
- `$pullAll` was removed, use [pull](./api.html#types_array_MongooseArray-pull) instead.
- `doAtomics` was changed to the [hasAtomics](./api.html#types_array_MongooseArray-hasAtomics) private method
h3#mongoosenumber Number type
:markdown
The custom subclassed Number type Mongoose used to use for all numbers is now gone. It caused [too many problems](https://groups.google.com/d/msg/mongoose-orm/syKlN2xL1EE/FfRFhEFj4KcJ) when doing comparisons and had other bad side-effects.
With it out of the picture, the following helper methods of MongooseNumbers are now also gone:
- $inc
- $increment
- $decrement
If you really want this behavior back, include the [mongoose-number](https://github.com/aheckmann/mongoose-number) module in your project.
A good alternative is to start using the new [findAndModify](./api.html#model_Model-findOneAndUpdate) [helpers](./api.html#model_Model-findOneAndRemove).
Say we have an inventory of 10 products and a customer purchases 7 of them. In Mongoose v2 you could have depended on MongooseNumber:
:js
var inventorySchema = new Schema({ productCount: Number });
...
Inventory.findById(id, function (err, inventory) {
if (err) return handleError(err);
inventory.productCount.$decrement(7);
inventory.save(function (err) {
// sends Inventory.update({ _id: id }, { $inc: { balance: -7 }}, callback);
if (err) return handleError(err);
res.send(inventory.productCount); // 3
});
});
:markdown
With MongooseNumber out of the picture, we'll instead use the [Account.findByIdAndUpdate](./api.html#model_Model-findByIdAndUpdate) helper:
:js
Inventory.findByIdAndUpdate(id, { $inc: { productCount: -7 }}, function (err, inventory) {
if (err) return handleError(err);
res.send(inventory.productCount); // 3
});
:markdown
The `findByIdAndUpdate` helper not only finds the document but updates it as well before responding with the altered document. The findAndModify helpers are a great addition for many use cases.
h3#documents Documents
:markdown
- `doc#commit` is now removed, use [doc.markModified](./api.html#document_Document-markModified) instead
- [doc#modifiedPaths](./api.html#document_Document-modifiedPaths) is now a method not a getter
- `doc.modified` is now removed, use [doc.isModified](./api.html#document_Document-isModified) instead
h4#gettercasting getter casting
:markdown
Getters no longer apply casting. Casting happens at set time. Useful in situations where you desire formatted responses like currency. See issue [#820](https://github.com/LearnBoost/mongoose/issues/820) and pull [#924](https://github.com/LearnBoost/mongoose/pull/924).
h4#setterorder setter order
:markdown
Values being set no longer cast until _after_ all setters have been applied. Previously the value returned from each setter was cast _before_ passing it on to the next setter. This change allows more flexible processing of values in setters. See issue [#665](https://github.com/learnboost/mongoose/issues/665) and pull [#924](https://github.com/LearnBoost/mongoose/pull/924).
h3#subdocs Subdocuments
:markdown
- `subdoc.parent` was changed from a property to a [method](./api.html#types_embedded_EmbeddedDocument-parent). See issue [#928](https://github.com/LearnBoost/mongoose/issues/928).
- `subdoc.parentArray` was changed from a property to a [method](./api.html#types_embedded_EmbeddedDocument-parentArray). See issue [#928](https://github.com/LearnBoost/mongoose/issues/928).
h3#stringmatch String match validator
:markdown
The String SchemaType [match](./api.html#schema_string_SchemaString-match) validator no longer checks against null, undefined, or ''. If you need to validate against these values, enable the [required](./api.html#schematype_SchemaType-required) validator as well. See issue [#934](https://github.com/LearnBoost/mongoose/issues/934) and pull request [#935](https://github.com/LearnBoost/mongoose/pull/935).
h3#version Versioning
:markdown
Documents are now transparently versioned. Read the in depth details [here](http://aaronheckmann.posterous.com/tag/versioning).
h3#moreinfo More Info
:markdown
Related blog posts:
- [Mongoose v3 released](http://aaronheckmann.posterous.com/mongoose-v3-released)
- [API changes](http://aaronheckmann.posterous.com/mongoose-v3-part-3-api-changes)
- [FindAndModify](http://aaronheckmann.posterous.com/mongoose-v3-part-2-findandmodify)
Jump to Line
Something went wrong with that request. Please try again.