Skip to content

Commit d78b045

Browse files
committed
Notes on how to upgrade to 2.3.0 safely
1 parent eaa9dd5 commit d78b045

File tree

1 file changed

+75
-0
lines changed

1 file changed

+75
-0
lines changed

2.3.0.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Upgrading Parse Server to version 2.3.0
2+
3+
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.
4+
5+
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.
6+
7+
```js
8+
// Select the database that your Parse App uses
9+
use parse;
10+
11+
// Select the collection your Parse App uses for users. For migrated apps, this probably include a collectionPrefix.
12+
var coll = db['your_prefix:_User'];
13+
14+
// You can check if the indexes already exists by running coll.getIndexes()
15+
coll.getIndexes();
16+
17+
// The indexes you want should look like this. If they already exists, you can skip creating them.
18+
/*
19+
{
20+
"v" : 1,
21+
"unique" : true,
22+
"key" : {
23+
"username" : 1
24+
},
25+
"name" : "username_1",
26+
"ns" : "parse.your_prefix:_User",
27+
"background" : true,
28+
"sparse" : true
29+
}
30+
31+
{
32+
"v" : 1,
33+
"unique" : true,
34+
"key" : {
35+
"email" : 1
36+
},
37+
"name" : "email_1",
38+
"ns" : "parse.your_prefix:_User",
39+
"background" : true,
40+
"sparse" : true
41+
}
42+
*/
43+
44+
// Create the username index.
45+
// "background: true" is mandatory and avoids downtime while the index builds.
46+
// "sparse: true" is also mandatory because Parse Server uses sparse indexes.
47+
coll.ensureIndex({ username: 1 }, { background: true, unique: true, sparse: true });
48+
49+
// Create the email index.
50+
// "background: true" is still mandatory.
51+
// "sparse: true" is also mandatory both because Parse Server uses sparse indexes, and because email addresses are not required by the Parse API.
52+
coll.ensureIndex({ email: 1 }, { background: true, unique: true, sparse: true });
53+
```
54+
55+
There are some issues you may run into during this process:
56+
57+
## Mongo complains that the index already exists, but with different options
58+
59+
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.
60+
61+
## There is already non-unique data in the username or email field
62+
63+
This is possible if you have explicitly set some user's emails to null. These null emails can be removed with this command:
64+
65+
```js
66+
coll.update({ email: { $exists: true, $eq: null } }, { $unset: { email: '' } }, { multi: true })
67+
```
68+
69+
## There is already non-unique data in the username or email field, and it's not nulls
70+
71+
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.
72+
73+
## My app depends on emails set to null behaving differently from emails set to undefined
74+
75+
You will need to update your app before executing the previous steps.

0 commit comments

Comments
 (0)