#
Mongoose

- home
- plugins
- change log
- support
- fork
- guide
  - schemas
    - schematypes
  - documents
    - sub docs
  - models
  - queries
  - plugins
  - middleware
  - validation
  - populate
  - migrating from 2.x
  - contributing
- api docs
- quick start
- contributors
- prior releases

## Migrating from 2.x to 3.x

Migrating from Mongoose 2.x to 3.x brings with it several changes to be aware of:

### Query clean-up

Many methods of the Query API were nothing but aliases and have been removed in an effort to keep Mongoose clean and focused on there being as close to one way of doing things as possible. If you really love all that extra noise, you can bring most of it back with this module.

Here are the removed methods are their still existing aliases:

Removed | Alternative
--- | ---
`query.run` | `query.exec`
`query.$or` | `query.or`
`query.$nor` | `query.nor`
`query.$gt` | `query.gt`
`query.$gte` | `query.gte`
`query.$lt` | `query.lt`
`query.$lte` | `query.lte`
`query.$ne` | `query.ne`
`query.$in` | `query.in`
`query.$nin` | `query.nin`
`query.$all` | `query.all`
`query.$regex` | `query.regex`
`query.$size` | `query.size`
`query.$maxDistance` | `query.maxDistance`
`query.$mod` | `query.mod`
`query.$near` | `query.near`
`query.$exists` | `query.exists`
`query.$elemMatch` | `query.elemMatch`
`query.$within` | `query.within`
`query.$box` | `query.box`
`query.$center` | `query.center`
`query.$centerSphere` | `query.centerSphere`
`query.$slice` | `query.slice`
`query.notEqualTo` | `query.ne`
`query.wherein` | `query.within`
`query.asc` | `query.sort *`
`query.desc` | `query.sort *`
`query.fields` | `query.select *`

#### query#asc

The `asc` method of Query has been removed in favor of sort. The `sort` method accepts slightly different arguments so read the docs to make sure your application is all set.

#### query#desc

The `desc` method of Query has been removed in favor of sort. The `sort` method accepts slightly different arguments so read the docs to make sure your application is all set.

#### query#fields

The `fields` method of Query has been removed, it being mostly an alias for the select method anyway. The `select` method has slightly different arguments so read the docs to make sure your application is all set.

Because of the change to the `fields` method, the field selection argument for model methods like findById, find, etc, is slightly different as well (no longer accepts arrays for example), so read the docs to make sure your application is all set.

### Connecting to ReplicaSets

To connect to a ReplicaSet you no longer use the separate `connectSet` or `createSetConnection` methods. Both mongoose.connect and 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.

### Schemas

- are now strict by default.
- Arrays of object literal now creates document arrays instead of arrays of Mixed.
- Indexes are now created in background by default.
- Index errors are now emitted on their model instead of the connection. See issue #984.

### Arrays

- pop is now fixed causing a $set of the entire array.
- $pop is now fixed and behaves just as MongoDB $pop does, removing at most the last element of the array.
- shift is now fixed causing a $set of the entire array.
- $shift is now fixed and behaves just as a MongoDB $pop -1 does, removing at most the first element of array.
- `$unshift` was removed, use unshift instead.
- `$addToSet` was removed, use addToSet instead.
- `$pushAll` was removed, use push instead.
- `$pull` was removed, use pull instead.
- `$pullAll` was removed, use pull instead.
- `doAtomics` was changed to the hasAtomics private method

### Number type

The custom subclassed Number type Mongoose used to use for all numbers is now gone. It caused too many problems 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 module in your project.

A good alternative is to start using the new findAndModify helpers. Say we have an inventory of 10 products and a customer purchases 7 of them. In Mongoose v2 you could have depended on MongooseNumber:

    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
      });
    });

With MongooseNumber out of the picture, we'll instead use the Account.findByIdAndUpdate helper:

    Inventory.findByIdAndUpdate(id, { $inc: { productCount: -7 }}, function (err, inventory) {
      if (err) return handleError(err);
      res.send(inventory.productCount); // 3
    });

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.

### Documents

- `doc#commit` is now removed, use doc.markModified instead
- doc#modifiedPaths is now a method not a getter
- `doc.modified` is now removed, use doc.isModified instead

#### getter casting

Getters no longer apply casting. Casting happens at set time. Useful in situations where you desire formatted responses like currency. See issue #820 and pull #924.

#### setter order

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 changes allows more flexible processing of values in setters. See issue #665 and pull #924.

### Subdocuments

- `subdoc.parent` was changed from a property to a method. See issue #928.
- `subdoc.parentArray` was changed from a property to a method. See issue #928.

### String match validator

The String SchemaType match validator no longer checks against null, undefined, or ''. If you need to validate against these values, enable the required validator as well. See issue #934 and pull request #935.

### Versioning

Documents are now transparently versioned. Read the in depth details here.