|
| 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