Back4App

Migrate your Parse App to Back4App using CLI

Introduction

In this guide, you will learn how to migrate your Parse App to Back4App using the migration CLI.

The migration process consists of transferring the Database, cloud functions, and files from your current Parse App to a Back4App App. The CLI migration tool will help you with the Database and files migration. 

It will pick a copy of your MongoDB (a dump file) and restore the data in your Back4App App. Then will pick your files from a local folder and upload them to Back4App S3 Bucket. The Cloud Code migration is not covered for this CLI migration tool but you can use the Back4App CLI (other CLI) to migrate them or do it manually using the Dashboard.

Prerequisites

To begin with this tutorial, you will need:

Step 1 - Install our CLI Tool

First of all, it’s ncessary to install @back4app/m2b4a in your machine. As described below:

npm install -g @back4app/m2b4a

Step 2 - Start the Parse App migration

You will now migrate your Database. Go to your current Parse App and download a copy of your Database (you can use a mongodump command for that). Then go to the folder which contains your dump files and run:

migrate-to-back4app

Step 3 - Access your Account

You can sign up or log in into your account and choose if you want to save your session. Then, the next time you use this tool you won’t need to put your account credentials again.

Step 4 - Choose a Back4App App

You can migrate your Parse App to an existing app or to a new one.

If you decide to use an existing app, be careful, it’s possible to decide if you’ll overwrite the existing data or just insert new objects.

For new apps, you must set a name and press ENTER.

Step 5 - Restore your data

Once you’re already in the folder where your dump files are, you just need to press ENTER.

Step 6 - Migrate your Parse Files

In case you have Parse Files, browse in the folder where your files are, and press ENTER to continue. The files will be automatically associated with your Parse Objects.

Otherwise, just type n to skip this step and start the restoration process.

Here’s how the end of the migration will look like:

Never share these credentials to anyone. You can add collaborators in your project and they can get these keys here.

Step 7 - Test your cloud code

Check this guide to know how to deploy your cloud code files.

Here are some pieces of information you must know:

1 - Back4App uses 2 main folders: public/ to public files, like html, css, etc. and cloud/ to private cloud code.

2 - Inside cloud/ Back4App import 2 files. One named app.js for your custom api (app.get(‘/my-custom-api’) for ex.) and main.js for Parse.Cloud functions and jobs.

3 - VERY IMPORTANT! app (the express.js instance) and Parse variables are global. Do not install them on your package.json or require them in your cloud code.

4 - Do not use require('express') or require('parse/node'), just use app and Parse variables.

Step 8 - Connect your current API to your new MongoDB database at Back4App

Once you finished all App tests, it’s time to point your current Parse Server to use the Back4App Database. You have two possibilities here. The first is to point Parse Server to Back4App Database and then make an incremental Database restore (as described in Step5). The second is to turn off your Parse Server, make a complete database restore and then turn it on again, pointing to Back4App Database. Our suggestion here is the first step, which will avoid downtime to your App.

To proceed with the first option, copy your Back4App Connection String at Server Settings > Settings > Core Settings > MongoDB Database URI and paste in your old Parse App settings.

Now you need to make a new dump of your data and restore them again in your application (step 5), but, instead of creating a new app, choose YES, I want to update one of them! and NO! Only insert new ids, afterward. It will help to prevent data inconsistency to your users.

After concluding this step, your users will be using the Back4App Database instead of the old one.

Step 9 - Updating your frontend

Now, you need to update your frontend to connect to the Back4App App. You can get your app ID, keys, and API Address in the core settings section at Server Settings > Settings > Core Settings. Update your frontend/App connection (pointing to Back4App now) and release a new application version to your users.

Now you have a new app pointing to Back4App API and database and an old app pointing to the previous Parse API but using the Back4App database.

Step 10 - Finishing the process

We recommend only turning off your old Parse API when most of your users are using the new App version (pointing to Back4App API). Once you turn off the old API, users who use the old version will lose access to the backend.

It’s done!

Now you know how to migrate your Parse App to the Back4App using the CLI. In case you need any help or a link doesn’t work, please contact our team!