Pages 8

Clone this wiki locally

Beginning with this release, the Mongoose project has moved to a release versioning approach similar to the MongoDB and Node.js projects. All odd numbered minor versions are to be considered unstable where you should expect larger, potentially breaking changes to occur during iteration towards the next even numbered (stable) release.

We feel this approach provides a cleaner, more consistent way to describe and iterate on new code branches than tagging pre-releases as "beta0", "beta1", etc.

Summary:

X.OddNumber.X is an unstable release

X.EvenNumber.X is a stable release

For example: 3.7.0, 3.7.1 and 4.11.398 are unstable, whereas 3.8.0, 3.8.1, and 3.20.1 are stable.

For more information on this versioning scheme, please see the MongoDB example.

The nitty-gritty

Mongoose 3.7 brings with it some significant changes and improvements under the hood:

mquery

mquery is a fluent query building library for MongoDB. It's API is very similar to Mongoose's old query syntax, but it does have some improvements and is much more standardized. Any query you can construct with mquery, can now be constructed with Mongoose using the same syntax. At the same time, all old Mongoose syntax that mquery does not support should still be available (with 2 notable exceptions, see below). If any old syntax (that was using public APIs-- we do not guarantee support for any internal APIs used, and they have changed) does not work, please submit a report.

This change reduces the size of the Mongoose code base by a couple thousand lines. Additionally, it allows for you to integrate your own query engine should you desire.

geoWithin changes

If you are running a version of MongoDB < 2.4 this affects you.

In MongoDB 2.4, $within was deprecated and $geoWithin was introduced which is 100% backward compatible with $within. For .within() queries, we now internally use $geoWithin by default. However, you can change this to remain backward compatible with old releases of MongoDB and force Mongoose to continue using $within by setting a flag. To toggle this flag, simply change the use$geoWithin property on the Query object.

Supported Operations

Links

model.aggregate arguments

The Model.aggregate() argument signature has changed; now no longer accepting an options argument. Now that we are wrapping the driver's aggregate method, we can provide a cleaner, less error prone approach through the use of the new aggregation builders read method.

{PATH} is replaced with the invalid document path
{VALUE} is replaced with the invalid value
{TYPE} is replaced with the validator type such as "regexp", "min", or "user defined"
{MIN} is replaced with the declared min value for the Number.min validator
{MAX} is replaced with the declared max value for the Number.max validator

One change to be aware of for custom validators is that in previous versions, the error message was assigned to the type property of the ValidationError. Going forward, the type property is assigned the value user defined.

GeoJSON Support for query.near()

query.remove() behavior change

In Mongoose < 3.7.1, Query#remove() always executed the operation and did not accept query conditions. To be consistent with other Query operations, query conditions and/or callback are now accepted. The operation is executed only if the callback is passed.

child schemas transform options now respected

subdoc and populated docs toJSON options now respected

Before version 3.7.3, subdocuments and populated child documents toJSON options were ignored when calling parent.toJSON() and the parents toJSON options were used instead. This behavior has now been corrected.

disabling safe mode now also disables versioning support

When { w: 0 } or safe: false is used in your schema to force non-acknowledged writes (rare but some people use this), no response is received from MongoDB causing an error to occur in the versioning handler. Because mongoose doesn't know if the write was successful under these conditions, versioning must be disabled as well. In 3.7 we now disable it automatically when using non-acknowledged writes.

pluralization optional

Mongoose has historically pluralized collection names. While some feel its a nice feature it often has lead to confusion when later exploring the database in the MongoDB shell. This release includes optionally disabling pluralization of collection names.

connection pool sharing

For example, an application working with 5 databases in a 3 node replica-set previously required creating 5 separate mongoose connection instances. Since each mongoose connection instance opens 6 internal connections (by default) to each node of your replica set, a total of 90 (635) connections were opened. Now, utilizing connection.useDb(dbname), we are able to just reuse the existing 18 (6*3) connections.

model.update() now supports overwrite

You can now pass the overwrite option to a model in order to override default update semantics.

overwrite is passed in via setOptions

var q = Model.where({ _id: id }).setOptions({ overwrite:true });

This will cause the update to ignore the built-in protections in Mongoose and simply send the update as-is. This means that passing {} to update with overwrite will result in an empty document. This feature is useful when you need to override the default $set update behavior.

awaitdata support

Query#update and Query#remove only executes with callback or explicit true

Previously, update() and remove() would execute an unsafe update/delete if no callback was passed. This has been changed in this release. You now must either pass a callback or explicitly tell Mongoose to execute the query in an unsafe manner. This can be done by passing true for the callback value to the query.