Fearlessly upgrading your SashiDo app from Parse Server v2 to v3

Preface

Not so long ago a new major version of Parse Server was released. Version 3 includes some pretty rough breaking changes when it comes to the Cloud Code and the JavaScript SDK -

• Version 2 of the Parse JavaScript SDK that is used in the Cloud Code lacks some methods on the ParsePromise type, as described here. Luckily, replacing these methods should be fairly easy since the native Promises are supported in all Parse Server versions on SashiDo. In fact, these should be one of the first changes to perform before upgrading your Parse Server version.
• Cloud Code handlers have a new interface based on promises.
• response.success / response.error are removed in Cloud Code

In short this means that the following code that works on version 2.x.x will no longer work:

Parse.Cloud.define('fetch_data', (req, res) => {
    externalService.fetch()
      .then(data => res.success(data))
      .catch(err => res.error(err));
});

And will have to be replaced with the following code:

Parse.Cloud.define('fetch_data', req => externalService.fetch());

The problems

Something is bugging you with the above? Let me reiterate, so we are on the same page... Breaking change means that you will have to change your whole cloud code and redeploy it, at the same time you need to change the version of your Parse Server to match the new cloud code and all of this without interrupting your backend's ability to serve your app’s users. That's why SashiDo has something special in store for its customers, keep reading!

We, at SashiDo also recognize that the version(2.3.3) of your SashiDo applications is not quite up to date and a smooth transition will be required. Since no software is perfect and incompatibilities are always in the realm of possibilities when changing versions, we would like to reduce the risks during the transition as much as we can. That's why we are releasing a total of 3 versions alongside 2.3.3 so you can incrementally upgrade your app. The versions are:

• 2.8.4
• 3.0.0
• 3.1.3

The way ahead

So, you want to upgrade your Parse Server to the latest version? Great! Here's what we recommend you to do.

First and foremost, we highly recommend for any production apps to be tested on a development version of themselves before upgrading. To do that, we recommend effectively cloning your existing application, which consists of the following steps:

1. Create a new application from the Sashido Dashboard.
2. Export the database from your production application and import it into the database of your newly created application. Here's a useful video on how to do that: Database import & export
3. Start the new app's Cloud Code and copy it over from your production application's GitHub repo to the new one. Optionally, you can also add your new app's GitHub repo as a new remote to your local repo, for easier development. More info on the topic here Git Basics - Working with Remotes.
4. Push the changes to GitHub.

Now that you have a clone of your application, select it in the Dashboard, go to Runtime -> Parse Server Version and set your version to 2.8.4. After your application has been rebuilt, make sure that everything is running okay. Check the logs for errors, run cloud code requests, run Parse queries, whatever defines your application as operational.

At this point, you have not modified your Cloud Code. Now would be the right moment, to verify that your Parse Server is working as expected with version 2.8.4. After the extensive testing is done and you are sure that 2.8.4 looks good, you can switch your production application to it as well.

Fearless upgrades

Alright, so we established that version 3.x of the Parse Server brings some breaking changes, we also mentioned that SashiDo has put some sort of compatibility layer for you. Let me explain that real quick.

In the latest version of the Parse Server, the Cloud Function handlers don't receive a second argument when called. The second argument was holding the success and error functions which would signal that a certain function invocation has either succeeded or failed at a given point in time, maybe immediately, maybe in 5 seconds. We should now use promises and async/await to handle asynchronous functions, such as the following example, taken from the Parse Docs:

// The new way
Parse.Cloud.define("averageStars", async (request) => {
  const query = new Parse.Query("Review");
  query.equalTo("movie", request.params.movie);
  const results = await query.find();
  let sum = 0;
  for (let i = 0; i < results.length; ++i) {
    sum += results[i].get("stars");
  }
  return sum / results.length;
});

This is great, it truly is. async/await makes JavaScript code much more readable and easier to reason about. Moreover, unhandled exceptions will now be caught and returned to the caller properly, without requiring explicit error handling in 100% of the cases. However, if you have 1500 lines of Cloud Code, upgrading it all in one go is probably not something you eagerly look forward to. That's why, in SashiDo you can have Cloud Code written in both styles - the new one (example above) and the old one:

// The old way
Parse.Cloud.define("averageStars_old", (request, response) => {
  const query = new Parse.Query("Review");
  query.equalTo("movie", request.params.movie);
    query.find()
    .then(results => {
        let sum = 0;
        for (let i = 0; i < results.length; ++i) {
          sum += results[i].get("stars");
        }
        response.success(sum / results.length);    
      })
      .catch(err => response.error(err));
});

Basically, all apps in SashiDo will have a compatibility layer injected into their Cloud Code for versions after 3.x. Which will eliminate the breaking changes, allowing you to migrate your Cloud Code at a steady and comfortable pace. At the end of the day, you get all the new features and in return, it doesn't cost a full application rewrite. That's a win in my book!

Final steps

Remember the routine we went through to verify that our application worked on version 2.8.4? Yeah, me neither, refresh your memory here. When upgrading from 2.8.4 to 3.0.0 and 3.1.3 you need to follow the same steps. Only this time, after making sure that your application is operational you should start rewriting your Cloud Code functions one by one. We strongly recommend you do that since we can't guarantee the compatibility layer will allow you to take full advantage of all the Parse Server features in its next releases.

The End

That's it. You should now be fully prepared to upgrade your SashiDo applications!

Cheers and enjoy! :)