Notes on how to upgrade to 2.3.0 safely

Author: drew-gross

2.3.0.md

@@ -0,0 +1,75 @@
+# Upgrading Parse Server to version 2.3.0
+
+Parse Server version 2.3.0 begins using unique indexes to ensure User's username and email are unique. This is not a backwards incompatable change, but it may in some cases cause a significant performance regression until the index finishes building. Building the unique index before upgrading your Parse Server version will eliminate the performance impact, and is a recommended step before upgrading any app to Parse Server 2.3.0. New apps starting with version 2.3.0 do not need to take any steps before beginning their project.
+
+If you are using MongoDB in Cluster or Replica Set mode, we recommend reading Mongo's [documentation on index building](https://docs.mongodb.com/v3.0/tutorial/build-indexes-on-replica-sets/) first. If you are not using these features, you can execute the following commands from the Mongo shell to build the unique index. You may also want to create a backup first.
+
+```js
+// Select the database that your Parse App uses
+use parse;
+
+// Select the collection your Parse App uses for users. For migrated apps, this probably include a collectionPrefix.
+var coll = db['your_prefix:_User'];
+
+// You can check if the indexes already exists by running coll.getIndexes()
+coll.getIndexes();
+
+// The indexes you want should look like this. If they already exists, you can skip creating them.
+/*
+{
+  "v" : 1,
+  "unique" : true,
+  "key" : {
+    "username" : 1
+  },
+  "name" : "username_1",
+  "ns" : "parse.your_prefix:_User",
+  "background" : true,
+  "sparse" : true
+}
+
+{
+  "v" : 1,
+  "unique" : true,
+  "key" : {
+    "email" : 1
+  },
+  "name" : "email_1",
+  "ns" : "parse.your_prefix:_User",
+  "background" : true,
+  "sparse" : true
+}
+*/
+
+// Create the username index.
+// "background: true" is mandatory and avoids downtime while the index builds.
+// "sparse: true" is also mandatory because Parse Server uses sparse indexes.
+coll.ensureIndex({ username: 1 }, { background: true, unique: true, sparse: true });
+
+// Create the email index.
+// "background: true" is still mandatory.
+// "sparse: true" is also mandatory both because Parse Server uses sparse indexes, and because email addresses are not required by the Parse API.
+coll.ensureIndex({ email: 1 }, { background: true, unique: true, sparse: true });
+```
+
+There are some issues you may run into during this process:
+
+## Mongo complains that the index already exists, but with different options
+
+In this case, you will need to create the unique index using a different index name, and/or remove the incorrect index. Avoid downtime or a temporary performance regression in your app by building the new index before removing the old one.
+
+## There is already non-unique data in the username or email field
+
+This is possible if you have explicitly set some user's emails to null. These null emails can be removed with this command:
+
+```js
+coll.update({ email: { $exists: true, $eq: null } }, { $unset: { email: '' } }, { multi: true })
+```
+
+## There is already non-unique data in the username or email field, and it's not nulls
+
+This is possible due to a race condition in previous versions of Parse Server. If you have this problem, it is unlikely that you have a lot of rows with duplicate data. We recommend you clean up the data manually, by removing or modifying the offending rows.
+
+## My app depends on emails set to null behaving differently from emails set to undefined
+
+You will need to update your app before executing the previous steps.