Checklist for successful Parse migration by SashiDo

Peruna Keremidchieva

Time flies fast. It’s been 10 months since Parse announced the future retirement of their hosted service.
Many of you still feel uncertain about starting the migration process. We do understand your reasons - you need more time to see how the situation is going to develop, which new path to choose - self hosted backend or third party provider, you still wonder how stable are the fresh Parse Server providers. The actual migration also may scare you - you’ve probably have read the long official Parse documentation on the process and feel confused whether you'll manage to do it on your own.

Don't worry! We did our best by providing the easiest and fastest possible migration. It's fully automated and takes minutes (depending on your DB size). You can read more in our tutorial - Parse Migration in a Click.

In addition to this information we'd like to share with you the most appropriate order of steps to do your migration on SashiDo along with few tricky moments you need to know. If you follow them we guarantee you’ll experience troubleless migration and fully functioning features of your apps.

Here’s the short list of the recommended migration steps:

  1. Migrate your database
  2. Update your SDK-s
  3. Set up the Cloud Code
  4. Activate your Background Jobs
  5. Upload your Certificates for Push Notifications and switch to FCM /for Android/
  6. Check Global config, Sender Email and e-mail templates, Webhooks
  7. Set up your Host Name (CNAME)
  8. Migrate your files
  9. Prepare your app for IPv6 networks /iOS/

So let’s get started :)

Migrate your database

There’s plenty of options to transfer your DB from Parse - manually or with supporting tools. We chose to help you in any way possible, so we offer fully automated database migration. Although it's completely safe and trustworthy, it’s always good practice to check if everything has moved successfully. You can easily do this with MongoDB’s diagnostic commands or see it in SashiDo’s Dashboard under Core > Browser and if there’s a problem - just reach us at support@sashido.io and we’d love to check what could be the problem. Keep in mind that if you don’t finalize your migration on Parse’s Dashboard in the next 24 hours, your application will be using your old database. You can read more information in our migration tutorial.

If you don’t finalize your migration in 24 hours, you can restart the database migration only manually. For this you would need to clean up the database from any collections. Then to start a manual migration you have to go to SashiDo dashboard > Application Settings > Security & Keys > Copy the Database URI.
Then go to the Parse.com dashboard > App Settings > General and click the button "migrate" (Migrate to external database) and paste the URI there. After that you have another 24 hours to finalize the process.

Upgrade to the latest SDKs

Parse Server uses the latest SDKs- so make sure you update them before you start testing your application in order for your Cloud Code to work properly. Here’s a list of what you might need:

Keep in mind that non revocable sessions are not supported by the open source Parse Server and may need to be migrated

If your application is using old style sessions you will need to migrate these too due to the fact that this functionality is not supported by the open source Parse Server. There is a tutorial on how to do this and it is not hard at all! You can check this link for more detailed information about session migration

Set up the Cloud Code

Mentioning Cloud Code - the popular Javascript SDK for a server-side environment, was changed in the Parse Server.

1. Parse.User.current() is not safe to use

In the open source Parse Server it is not safe to use Parse.User.current() and this needs to be changed a bit. You will have to pass the session token taken from the request variable. Here is an example code we will quickly migrate:

And this is how it should look after the changes:

Here we get the user from the request variable and we can pass the token to future query and cloud code invocations. We will save it in a variable just to make our life easier and pass it as part of the options argument to the find function. Remember you will need to pass it to other find, delete, save, etc functions as well. You will also need to pass it to other calls to your cloud code functions.

2. Parse.Cloud.useMasterKey() may lead to security issues

You should not rely on Parse.Cloud.useMasterKey() as it may lead to security issues, instead you should to the same as what we have done with the user’s session token and pass it as part of the options object. Here is an example:

And here is the result of the new migrated cloud code:

As you can see we have Parse.Cloud.useMasterKey() is now commented out and useMasterKey is passed to the count function. As previously if you need to bypass ACLs or CLPs and need master you will have to pass this to other functions and cloud code calls.

3. Parse native Cloud Code modules are not available anymore

Parse native Cloud Code modules are not available anymore, now you need to use their official npm modules. This actually is a great news, because before you were restricted to only Parse Cloud Code modules and now you can use any npm module you want to. We did a short tutorial on how to use Twilio - the principle is the same with all packages.

Here is a list of the modules and their npm counterparts:

  • App Links: There is no direct replacement, but it is relatively easy to generate these tags yourself.
  • Buffer: This is included natively with Node. Remove any require('buffer') calls.
  • Mailgun: Use the official npm module mailgun-js
  • Mandrill: Use the official npm module mandrill-api
  • Moment:
    Use the official npm module moment
  • SendGrid: Use the official npm module sendgrid
  • Stripe: Use the official npm module stripe
  • Twilio: Use the official npm module twilio
  • Underscore: Use the official npm module underscore
  • Parse Image: We recommend using another image manipulation library, like the imagemagick wrapper module

Note: In-app purchases are not yet supported by the open source Parse Server.

Activate your Background Jobs

Background Jobs is an useful tool, allowing you to use long-running, repeating tasks. They’re part of the Cloud Code and migrate with it, jobs are not active as they may conflict with your currently running jobs on parse.com and you need to activate them after the migration. Just go in SashiDo’s Dashboard > Core > Jobs > Scheduled Jobs > Activate. After they are activated you will be able to change the schedule and edit them. Bear in mind that jobs will be running on parse.com too and you may need to stop them from running there. If you don’t know how to create Background Jobs and haven’t used them before you can take a look at our tutorial - Getting started with Background Jobs on SashiDo.

Upload your Certificates for Push Notifications and switch to FCM /for Android/

A common mistake is to forget to upload your certificates in order to use Push Notifications. They can’t be migrated because of security issues, but push audiences will be moved with your application. You need to upload your Apple Push Certificates and Android Push Credentials in your SashiDo Dashboard manually. Important news is that if you use GCM Credentials you’ll need to upgrade to FCM (Firebase Cloud Messaging), because some of the features of GCM are already depreciated and soon the whole GCM will be depreciated. You can read more information on how to upgrade to FCM.

Another important information regarding Android apps:
Parse.com owns the API Key of all default Sender IDs for each of their users. This means that the legacy FCM tokens can only be published via the hosted Parse.com API end point. If you use your SENDER_ID, generated by Parse, it will publish to all tokens - new and old, but after January 2017 you won’t be able to use it anymore. There’s no way to migrate the tokens, generated by Parse API, the only solution is to update the client SDK and register each user specifying your own SENDER_ID.

Global Config, E-mail templates, Webhooks

Global Config allows you to set up parameters that let you control the appearance or behavior of your app. It should migrate successfully with your application, but just check if everything is ok under Core > Config.

E-mail templates also migrate with your DB, just check them and do some tests if needed.

Reply-to email address: If you want your users to receive emails like forgotten password, auto reply etc. from a custom email address you have to make a small update. Go to SashiDo’s Dashboard and add your reply-to email address in the Settings > Hosting & Emails section. You will receive an email to verify the address, so make sure you check your inbox and do the necessary to complete the verification.

If you were using webhooks you will need to add them yourself. The interface is the same as in Parse.com and thus makes it fairly straight forward to add them in the dashboard.

Set up your Host Name (CNAME)

You can use static web hosting with SashiDo, you just need to set up your custom domain and CNAME in the Dashboard. Here's an article explaining how to use hosting on SashiDo.

Take care of your files

Parse stores your files in it’s own AWS S3 Bucket and Mongo database stores only references (URLs) to them. So after migrating the DB, the files don’t move with it and will be deleted after 28th of January 2017. Few months ago, this was a huge problem, but now there are file migration tools. SashiDo was the first to provide one, you can easily find the tool in SashiDo’s Dashboard: App Settings > File Migration. It’s completely free and can be used by all AWS clients, regardless if they use SashiDo or not.

One important note before you start the migration of your files: when the files are pointing to Parse.com’s S3 bucket they are visible to both api.parse.com and Parse Servers because of the way they are kept in the database Parse.com knows how to find them and provide a correct link. But after the files are being migrated they are no longer pointing to the Parse.com S3 and won’t be visible to Parse.com API end point. Also files uploaded from the Parse Server won't be visible to Parse.com API end point.

This means that file migration should be done after you have released a new build for you application and people start updating it.

Now to start a file migration you need to go to App Settings - choose File Migration and press Start File Migration.

App Store requires support of IPv6

In June this year Apple announced that after iOS 9 apps including, submitted to the App Store, must support IPv6 Network. Starting June 1, 2016 all apps submitted to the App Store must support IPv6-only networking. Most apps will not require any changes because IPv6 is already supported by NSURLSession and CFNetwork APIs, but in case your app uses IPv4-specific APIs or hard-coded IP addresses, you will need to make some changes. In order to meet the requirements your app needs to: work over IPv6 network connections and use DNS over IPv6. When you release the new version of your application on AppStore after migration make sure you meet these requirements.

In other words this IPv6 compatibility means to ensure that your apps work with IPv6 technology, you don’t have to make the endpoints running on IPv6 as DNS64/NAT64, translation technologies will facilitate the communications.

What you actually need to do is to make sure your application is ready for IPv6. This could involve things like not hard coding IPv4 in the app, not using a [short] fixed length string to store IP Address.

If you do use a string to store IP address it’s very important to make sure it has room to store at least 40 characters to accommodate IPv6 address format.

Here is a list of steps you need to take to ensure your application is ready for IPv6:

  • Use High-Level Networking Frameworks
  • Don not Use IP Address Literals
  • Connect Without Preflight
  • Use Appropriately Sized Storage Containers
  • Check Source Code for IPv6 DNS64/NAT64 Incompatibilities
  • Use System APIs to Synthesize IPv6 Addresses
  • Test for IPv6 DNS64/NAT64 Compatibility Regularly

We know migration can be challenging and problematic so make sure you give yourself enough time to check everything and leave enough time for live testing with the real users. In this way you’ll ensure the safe and smooth new journey of your apps. Keep in mind that in case you are not happy with your initial Parse.com alternative choice you will need time to find another provider and migrate there. In this line of thoughts our last tip is to make sure your provider doesn’t have vendor lock-in, this was one of the key strategic points in our policy as a company - users should feel free to make their decision based on the quality of the products, not because they feel trapped.

Don't be afraid of the migration, but also don't delay it too much, because there isn't a lot of time left.

If you have any questions regarding the migration - we'd love to help you with answers and we will be happy to receive feedback on your experience with the migration process.

In the meantime, happy coding :-)

Peruna Keremidchieva

SashiDo's community manager & customer happiness freak.

Find answers to all your questions

Our Frequently Asked Questions section is here to help.