/
migration.html
40 lines (32 loc) · 15.7 KB
/
migration.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
<!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.3.1</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><a href="./models.html">models</a></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="./queries.html">queries</a></li><li><a href="./validation.html">validation</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./populate.html">population</a></li><li><a href="./connections.html">connections</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="https://github.com/LearnBoost/mongoose/blob/master/CONTRIBUTING.md">contributing</a></li><li><a href="./migration.html">migrating from 2.x</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'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 change 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 ''. 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><h3 id="moreinfo">More Info</h3><p>Related blog posts:</p>
<ul><li><a href="http://aaronheckmann.posterous.com/mongoose-v3-released">Mongoose v3 released</a></li><li><a href="http://aaronheckmann.posterous.com/mongoose-v3-part-3-api-changes">API changes</a></li><li><a href="http://aaronheckmann.posterous.com/mongoose-v3-part-2-findandmodify">FindAndModify</a></li></ul></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>