migration.jade

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 are 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
  :markdown
    - are now [strict](./guide.html#strict) by default.
    - 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)