Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

38 lines (31 sloc) 15.573 kb
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Migration Guide v3.0.2</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"><style>table td {
padding-right: 15px;
}
</style></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="faq"><a href="./faq.html">FAQ</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./models.html">models</a></li><li><a href="./queries.html">queries</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./validation.html">validation</a></li><li><a href="./populate.html">populate</a></li><li><a href="./migration.html">migrating from 2.x</a></li><li><a href="./contributing.html">contributing</a></li></ul></li><li class="api"><a href="./api.html">api docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Migrating from 2.x to 3.x</h2><p>Migrating from Mongoose 2.x to 3.x brings with it <a href="https://github.com/LearnBoost/mongoose/blob/master/History.md">several changes</a> to be aware of:</p><h3>Query clean-up</h3><p>Many methods of the <a href="./api.html#query-js">Query</a> API were nothing but aliases and have been <a href="https://github.com/LearnBoost/mongoose/commit/1149804c">removed</a> in an effort to keep Mongoose clean and focused on there being as close to <a href="http://www.python.org/dev/peps/pep-0020/">one way</a> of doing things as possible. If you really love all that extra noise, you can bring most of it back with <a href="https://github.com/aheckmann/mongoose-v2-compat">this module</a>.</p>
<p>Here are the removed methods are their still existing aliases:</p><table><thead><tr style="text-align:left"><th>Removed</th><th>Alternative</th></tr></thead><tbody><tr><td><code>query.run</code></td><td><code>query.exec</code></td></tr><tr><td><code>query.$or</code></td><td><code>query.or</code></td></tr><tr><td><code>query.$nor</code></td><td><code>query.nor</code></td></tr><tr><td><code>query.$gt</code></td><td><code>query.gt</code></td></tr><tr><td><code>query.$gte</code></td><td><code>query.gte</code></td></tr><tr><td><code>query.$lt</code></td><td><code>query.lt</code></td></tr><tr><td><code>query.$lte</code></td><td><code>query.lte</code></td></tr><tr><td><code>query.$ne</code></td><td><code>query.ne</code></td></tr><tr><td><code>query.$in</code></td><td><code>query.in</code></td></tr><tr><td><code>query.$nin</code></td><td><code>query.nin</code></td></tr><tr><td><code>query.$all</code></td><td><code>query.all</code></td></tr><tr><td><code>query.$regex</code></td><td><code>query.regex</code></td></tr><tr><td><code>query.$size</code></td><td><code>query.size</code></td></tr><tr><td><code>query.$maxDistance</code></td><td><code>query.maxDistance</code></td></tr><tr><td><code>query.$mod</code></td><td><code>query.mod</code></td></tr><tr><td><code>query.$near</code></td><td><code>query.near</code></td></tr><tr><td><code>query.$exists</code></td><td><code>query.exists</code></td></tr><tr><td><code>query.$elemMatch</code></td><td><code>query.elemMatch</code></td></tr><tr><td><code>query.$within</code></td><td><code>query.within</code></td></tr><tr><td><code>query.$box</code></td><td><code>query.box</code></td></tr><tr><td><code>query.$center</code></td><td><code>query.center</code></td></tr><tr><td><code>query.$centerSphere</code></td><td><code>query.centerSphere</code></td></tr><tr><td><code>query.$slice</code></td><td><code>query.slice</code></td></tr><tr><td><code>query.notEqualTo</code></td><td><code>query.ne</code></td></tr><tr><td><code>query.wherein</code></td><td><code>query.within</code></td></tr><tr><td><code>query.asc</code></td><td><code>query.sort <a href="#asc">*</a></code></td></tr><tr><td><code>query.desc</code></td><td><code>query.sort <a href="#desc">*</a></code></td></tr><tr><td><code>query.fields</code></td><td><code>query.select <a href="#fields">*</a></code></td></tr></tbody></table><h4 id="asc">query#asc</h4><p>The <code>asc</code> method of <a href="./api.html#query-js">Query</a> has been removed in favor of <a href="./api.html#query_Query-sort">sort</a>. The <code>sort</code> method accepts slightly different arguments so read the <a href="./api.html#query_Query-sort">docs</a> to make sure your application is all set.</p><h4 id="desc">query#desc</h4><p>The <code>desc</code> method of <a href="./api.html#query-js">Query</a> has been removed in favor of <a href="./api.html#query_Query-sort">sort</a>. The <code>sort</code> method accepts slightly different arguments so read the <a href="./api.html#query_Query-sort">docs</a> to make sure your application is all set.</p><h4 id="sort">query#sort</h4><p>The <a href="./api.html#query_Query-sort">sort</a> method of <a href="./api.html#query-js">Queries</a> now accepts slightly different arguments. Read the <a href="./api.html#query_Query-sort">docs</a> to make sure your application is all set.</p><h4 id="fields">query#fields</h4><p>The <code>fields</code> method of <a href="./api.html#query-js">Query</a> has been removed, it being mostly an alias for the <a href="./api.html#query_Query-select">select</a> method anyway. The <code>select</code> method has slightly different arguments so read the <a href="./api.html#query_Query-select">docs</a> to make sure your application is all set.</p>
<p>Because of the change to the <code>fields</code> method, the field selection argument for <a href="./api.html#query_Query-populate">query.populate</a> and model methods like <a href="./api.html#model_Model-findById">findById</a>, <a href="./api.html#model_Model-find">find</a>, etc, is slightly different as well (no longer accepts arrays for example), so read the <a href="./api.html#query_Query-select">docs</a> to make sure your application is all set.</p><h3>Connecting to ReplicaSets</h3><p>To connect to a <a href="http://www.mongodb.org/display/DOCS/Replica+Sets">ReplicaSet</a> you no longer use the separate <code>connectSet</code> or <code>createSetConnection</code> methods. Both <a href="./api.html#index_Mongoose-connect">mongoose.connect</a> and <a href="./api.html#index_Mongoose-createConnection">mongoose.createConnection</a> are now smart enough to just do the right thing with your connection string. If you really want to bring <code>connectSet</code> and <code>createSetConnection</code> back use <a href="https://github.com/aheckmann/mongoose-v2-compat">this module</a>.</p><h3>Schemas</h3><ul><li>are now <a href="./guide.html#strict">strict</a> by default.</li><li>Arrays of <a href="./subdocs.html#altsyntax">object literal</a> now creates document arrays instead of arrays of <a href="./schematypes.html#mixed">Mixed</a>.</li><li>Indexes are now created in <a href="./guide.html#autoIndex">background</a> by default.</li><li>Index errors are now emitted on their model instead of the connection. See issue <a href="https://github.com/LearnBoost/mongoose/issues/984">#984</a>.</li></ul><h3 id="arrays">Arrays</h3><ul><li><a href="./api.html#types_array_MongooseArray-pop">pop</a> is now fixed causing a $set of the entire array.</li><li><a href="./api.html#types_array_MongooseArray-%24pop">$pop</a> is now fixed and behaves just as MongoDB <a href="http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop">$pop</a> does, removing at most the last element of the array.</li><li><a href="./api.html#types_array_MongooseArray-shift">shift</a> is now fixed causing a $set of the entire array.</li><li><a href="./api.html#types_array_MongooseArray-%24shift">$shift</a> is now fixed and behaves just as a <a href="http://www.mongodb.org/display/DOCS/Updating#Updating-%24pop">MongoDB $pop -1</a> does, removing at most the first element of array.</li><li><code>$unshift</code> was removed, use <a href="./api.html#types_array_MongooseArray-unshift">unshift</a> instead.</li><li><code>$addToSet</code> was removed, use <a href="./api.html#types_array_MongooseArray-addToSet">addToSet</a> instead.</li><li><code>$pushAll</code> was removed, use <a href="./api.html#types_array_MongooseArray-push">push</a> instead.</li><li><code>$pull</code> was removed, use <a href="./api.html#types_array_MongooseArray-pull">pull</a> instead.</li><li><code>$pullAll</code> was removed, use <a href="./api.html#types_array_MongooseArray-pull">pull</a> instead.</li><li><code>doAtomics</code> was changed to the <a href="./api.html#types_array_MongooseArray-hasAtomics">hasAtomics</a> private method</li></ul><h3 id="mongoosenumber">Number type</h3><p>The custom subclassed Number type Mongoose used to use for all numbers is now gone. It caused <a href="https://groups.google.com/d/msg/mongoose-orm/syKlN2xL1EE/FfRFhEFj4KcJ">too many problems</a> when doing comparisons and had other bad side-effects.</p>
<p>With it out of the picture, the following helper methods of MongooseNumbers are now also gone:</p>
<ul><li>$inc</li><li>$increment</li><li>$decrement</li></ul>
<p>If you really want this behavior back, include the <a href="https://github.com/aheckmann/mongoose-number">mongoose-number</a> module in your project.</p>
<p>A good alternative is to start using the new <a href="./api.html#model_Model-findOneAndUpdate">findAndModify</a> <a href="./api.html#model_Model-findOneAndRemove">helpers</a>.
Say we have an inventory of 10 products and a customer purchases 7 of them. In Mongoose v2 you could have depended on MongooseNumber:</p><pre><code class="javascript"><span class="keyword">var</span> inventorySchema = <span class="keyword">new</span> Schema({ productCount: Number });
...
Inventory.findById(id, <span class="function"><span class="keyword">function</span> <span class="params">(err, inventory)</span> {</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
inventory.productCount.$decrement(<span class="number">7</span>);
inventory.save(<span class="function"><span class="keyword">function</span> <span class="params">(err)</span> {</span>
<span class="comment">// sends Inventory.update({ _id: id }, { $inc: { balance: -7 }}, callback);</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
res.send(inventory.productCount); <span class="comment">// 3</span>
});
});</code></pre><p>With MongooseNumber out of the picture, we&#39;ll instead use the <a href="./api.html#model_Model-findByIdAndUpdate">Account.findByIdAndUpdate</a> helper:</p><pre><code class="javascript">Inventory.findByIdAndUpdate(id, { $inc: { productCount: -<span class="number">7</span> }}, <span class="function"><span class="keyword">function</span> <span class="params">(err, inventory)</span> {</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
res.send(inventory.productCount); <span class="comment">// 3</span>
});</code></pre><p>The <code>findByIdAndUpdate</code> 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.</p><h3 id="documents">Documents</h3><ul><li><code>doc#commit</code> is now removed, use <a href="./api.html#document_Document-markModified">doc.markModified</a> instead</li><li><a href="./api.html#document_Document-modifiedPaths">doc#modifiedPaths</a> is now a method not a getter</li><li><code>doc.modified</code> is now removed, use <a href="./api.html#document_Document-isModified">doc.isModified</a> instead</li></ul><h4 id="gettercasting">getter casting</h4><p>Getters no longer apply casting. Casting happens at set time. Useful in situations where you desire formatted responses like currency. See issue <a href="https://github.com/LearnBoost/mongoose/issues/820">#820</a> and pull <a href="https://github.com/LearnBoost/mongoose/pull/924">#924</a>.</p><h4 id="setterorder">setter order</h4><p>Values being set no longer cast until <em>after</em> all setters have been applied. Previously the value returned from each setter was cast <em>before</em> passing it on to the next setter. This changes allows more flexible processing of values in setters. See issue <a href="https://github.com/learnboost/mongoose/issues/665">#665</a> and pull <a href="https://github.com/LearnBoost/mongoose/pull/924">#924</a>.</p><h3 id="subdocs">Subdocuments</h3><ul><li><code>subdoc.parent</code> was changed from a property to a <a href="./api.html#types_embedded_EmbeddedDocument-parent">method</a>. See issue <a href="https://github.com/LearnBoost/mongoose/issues/928">#928</a>.</li><li><code>subdoc.parentArray</code> was changed from a property to a <a href="./api.html#types_embedded_EmbeddedDocument-parentArray">method</a>. See issue <a href="https://github.com/LearnBoost/mongoose/issues/928">#928</a>.</li></ul><h3 id="stringmatch">String match validator</h3><p>The String SchemaType <a href="./api.html#schema_string_SchemaString-match">match</a> validator no longer checks against null, undefined, or &#39;&#39;. If you need to validate against these values, enable the <a href="./api.html#schematype_SchemaType-required">required</a> validator as well. See issue <a href="https://github.com/LearnBoost/mongoose/issues/934">#934</a> and pull request <a href="https://github.com/LearnBoost/mongoose/pull/935">#935</a>.</p><h3 id="version">Versioning</h3><p>Documents are now transparently versioned. Read the in depth details <a href="http://aaronheckmann.posterous.com/tag/versioning">here</a>.</p></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-1122274-9']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();</script></body></html>
Jump to Line
Something went wrong with that request. Please try again.