The developer community has expressed significant concern following MongoDB Atlas’s deprecation announcement of their edge and mobile capabilities. In an earlier post, we explored why Couchbase Mobile is a strong alternative for supporting your offline-first data sync requirements.

In this post, we’ll offer a technical overview of what a typical migration from MongoDB Atlas Device Sync to Couchbase looks like. While we’ll be focusing on Capella, our fully managed DBaaS solution, the concepts discussed will apply just as well to self-managed deployments of Couchbase Server and Couchbase Mobile.

Migration considerations

When planning to migrate your MongoDB Device Sync (Realm) application to Capella App Services, it’s important to take a holistic approach, considering both the cloud server-side components and the mobile application aspects.

NOTE: The items listed below are not intended to be prescriptive but represent common considerations. Each application is unique, so the migration process must be customized to meet the specific requirements of the application. 

You can begin with Couchbase Capella’s Free Tier, which includes Capella App Services—our hosted data sync solution. Once you’ve validated your migration and are ready for production deployment, you can upgrade to one of our paid tiers.

1. Data modeling

MongoDB and Couchbase are both document databases and store data in JSON format. However, MongoDB represents JSON documents in binary-encoded format called BSON using extended JSON specification. So while Couchbase can work with  documents in extended JSON format as you will see later, it will be simpler to work with regular JSON documents. 

Use this opportunity to determine the right data model for your migrated application and how you can organize it with buckets, scopes and collections. For instance, you may decide to skip or rename properties, which is fairly trivial to do with Couchbase Eventing Service functions. 

2. Configure Capella cluster

Deploy your Capella cluster and configure it per your application needs. The configuration would minimally include installation of the relevant services such as Query, Search etc., setting up cluster access credentials and setting up an IP Address allow list. Setting up an allowed IP address is typically necessary only for testing or evaluation purposes. In a production environment, you will likely configure cluster access via private networks, such as VPC Peering or Private Links. 

3. Data migration

To migrate data from a MongoDB Atlas cluster to a Capella cluster, you have several options. Your choice will depend on whether you’re performing a one-time, offline data migration or opting for a more complex online data migration. The online data migration typically requires bi-directional data synchronization between the MongoDB Atlas and Couchbase Capella clusters, especially if both are actively serving applications during the transition.

Here are a few common options:

Use export/import utilities – Export your MongoDB collections and import them into Capella using the cbimport tool. If your data is in extended JSON format, you’ll need to perform data transformation using Eventing service functions during the import process. Even if the data is in JSON, you may need to run data transformation if your target data model is not identical to the source. This approach is ideal for a one-time data migration.

Use enterprise data migration tools – Leverage enterprise-grade tools like MOLO7’s GlueSync for Couchbase to migrate data. A tool like GlueSync offers robust, scalable support for data migrations including hot and cold migrations. Check out this video for an overview of its capabilities and how it can assist in migration.

Open source tooling – You can try our open source community supported Couchbase utility, cbmigrate, to migrate data over. This works well for simple data migrations. The tool is integrated into popular Couchbase IDE extensions for VSCode and JetBrains. So if you are a developer who is building applications using these IDEs, then you should consider this option. 

Once data is migrated, you may have to create suitable indexes on your Capella cluster.

4. Configure Capella App Services

App Services is the managed backend service responsible for offline-first data sync. After setting up your cluster, you’ll need to deploy App Services to connect it to the configured cluster. The setup of App Services will vary significantly based on the specific requirements of your application.

Take the time to assess your application’s requirements and ensure it is configured properly. 

There isn’t an auto-migration tool available for this step. But we’ve got you covered. Refer to the simple getting started guide, which covers important configuration aspects using a sample dataset. This guide will help you get acquainted with the core concepts and you can adapt that for your application.

Deploy App Endpoints 

An App Endpoint is a representation of your application within Capella App Services. It represents the endpoint with which your mobile application will sync data. You must configure at least one App Endpoint on your App Services cluster. Each App Endpoint is associated with a bucket, a scope and a unique subset of collections within that scope.

Configure App Endpoints 

Setup Authentication Mechanism – By default, all App endpoints are protected using Basic Authentication. You have the option to set up advanced authentication mechanisms.

Configure Mobile App Users (& Roles) – Configure one or more application users and optionally roles. These are the users who are authenticated to sync data with App Services. In a production app, you are likely going to use Admin REST API for configuring users, or use the auto-register user capabilities if you have configured Open ID Connect (OIDC) for authentication.

Setup Access Control – This is one of the most crucial elements of the App Endpoint configuration. Here, you define the user’s level of access (read/write) by specifying a JavaScript function. Access control is made possible through a unique and powerful concept known as “channels.” By default, all documents within a collection are associated with a channel that shares the same name as the collection. As a result, a user who is granted access to a channel with the collection’s name automatically gains read access to all documents in that collection. Check out our docs to learn more about Access control and Validation.

Once you have configured your App Endpoint, you are ready to connect to it and sync data from your Couchbase Lite enabled application.

5. Migrate your Realm application

Now that your backend is set up, it’s time to migrate your Realm SDK application to Couchbase Lite. Realm is an object-oriented database, whereas MongoDB is a JSON document store, which requires transforming BSON documents into Realm objects. In contrast, Couchbase Lite is a full-featured embedded JSON document store that eliminates the need for transformation.

Migrating your Realm app will involve rewriting your application’s model layer (or Data Access Layer) to use Couchbase Lite’s SDK in the corresponding language.

Check out our comparison guide that compares MongoDB Device Sync SDK with Couchbase Lite. Here are some language specific guides:

6. Migrate your server-side SDK applications

If you have one or more backend or server-side applications, you’ll need to migrate them as well. We provide SDKs that support a variety of programming languages, offering modern, idiomatic APIs that make it easier for your backend applications to connect and interact with your cluster. During the migration, you’ll have the opportunity to significantly simplify your original queries written in MongoDB Query Language (MQL) by converting them to SQL++! 

While SQL++ should be very familiar to anyone with a database background, we have made it even simpler with CapellaIQ, our AI-assistant that will help to generate queries from natural language (NLP).

If you want to work with Capella from within your IDE environment, you can leverage our IDE plugins.

7. Setup integrations with your ecosystem

Couchbase provides various connectors and tools that enable integration with other subsystems and services in your environment, such as monitoring tools, pub-sub systems, and more. Therefore, if your MongoDB application interacts with other subsystems, you will need to reconfigure those connections when transitioning to Couchbase.

Sample migration: Realm to App Services

But wait…there’s more! The proof is in the pudding.

We took the Todo sample Realm mobile application and migrated that to Capella App Services. In the process, we provide a detailed step-by-step guide of how Couchbase Lite can provide equivalent functionality as supported by the Realm app. Additionally, we guide you through the process of setting up Capella cluster and App Services with the necessary configuration so  you have an end-to-end working system.

Here are links to migration steps for sample app in three popular languages: 

Resources

We’d love to hear from you on your migration experience. If you have any questions or feedback, please leave a comment below or reach out to us via Discord or forums.

Here are direct links to some of the helpful resources referenced in this post:

Acknowledgements

Thanks to Aaron Labeau for his contributions to SDK comparison guides and for sample apps.

Author

Posted by Priya Rajagopal, Senior Director, Product Management

Priya Rajagopal is a Senior Director of Product Management at Couchbase responsible for developer platforms for the cloud and the edge. She has been professionally developing software for over 20 years in several technical and product leadership positions, with 10+ years focused on mobile technologies. As a TISPAN IPTV standards delegate, she was a key contributor to the IPTV standards specifications. She has 22 patents in the areas of networking and platform security.

All Posts

Leave a reply