MongoDB Atlas Migration Guide

​

MongoDB Atlas deprecation

In September 2024, MongoDB deprecated the following services:

• Atlas Device Sync
• Atlas Data API
• Atlas Device SDKs

If you have MongoDB Atlas Device Sync deployed today, at a high level your architecture probably looks something like this:

​

PowerSync alpha support for MongoDB

As of September 20, 2024, PowerSync has developed alpha support for MongoDB as a backend database source. PowerSync’s MongoDB module is not yet considered production-ready.

It is currently available for testing in hosted or self-hosted environments:

• Hosted by us: Refer to Database Connection
• Self-hosted using Docker Compose: An end-to-end demo app is available here. Please refer to its README for further instructions.

Migrating to PowerSync’s MongoDB module would take you to this: (new components in green)

As you can see, this is not a point-and-click migration, however it does enable you to stay on MongoDB and those are the customers we are primarily interested in working with and supporting.

​

Notable comments on the architecture

1. PowerSync handles writes differently from reads. This is because developers typically want to have some business logic running on an authoritative server before allowing a client device to change data in the backend database.
   1. Reads are partitioned using Sync Rules
      1. Sync Rules are more flexible than MongoDB Realm Flexible Sync, but are defined server-side and not client-side.
   2. Writes are queued locally on the device and sent to the backend sequentially.
      1. The backend can be a very thin API layer or can contain significant amounts of logic — it is up to the developer
2. The PowerSync Service is generally available as a cloud-hosted service (PowerSync Cloud), or you can self-host using our Open Edition.
3. The PowerSync Client SDKs use SQLite under the hood. While there is nothing on a protocol level preventing us from supporting Realm as a client-side database, we are waiting to see whether Realm becomes a community project or not before investing in it, since it would be a significant amount of work for us to support Realm on the client-side.
   1. The client-side will most likely be where the bulk of migration work takes place for customers migrating from Atlas Device Sync to PowerSync.
   2. Client-side queries are typically written in SQL. ORM support is available for our JavaScript (React Native and web) and Flutter/Dart Client SDKs.
4. PowerSync piggybacks off your existing authentication, however, it uses JWTs. If you were using Atlas Device SDKs for authentication, you will need to implement an authentication provider.

​

Migration steps

1. Connect your database to an instance of the PowerSync Service:
   1. Using PowerSync Cloud (hosted by us): See Database Connection
   2. Using PowerSync Open Edition (self-hosted): Refer to our end-to-end demo app available here
2. Define Sync Rules in PowerSync — this enables dynamic partial replication so that you don’t need to sync your entire MongoDB database to devices.
   1. We recommend starting with one or two simple Global Data queries
3. Generate a Development Token
4. Use our Diagnostics App to validate that MongoDB is syncing into SQLite as expected.
5. Implement an app using one of our Client SDKs
   1. You can continue using your Development Token for a start
   2. Implement a “Hello World” app to get a feel, or jump straight into pulling the Client SDK into your existing app.
   3. Verify that downloads from MongoDB are working.
6. Implement authentication
7. Implement your backend app to accept writes.
   1. We have Node.js, Django and Rails demos available here.

​

Implementation notes

​

PowerSync Service

The PowerSync Service can either be self-hosted or deployed using PowerSync Cloud.

To self-host, you need a Docker environment. Refer to our end-to-end demo app available here which uses Docker Compose.

​

PowerSync Client SDKs

We are constantly adding additional PowerSync Client SDKs and some of them are under very active development. Below are the release status for each language/platform:

​

App Backend

You will need to host a backend that can accept client writes if you do not already have one. The app backend needs to expose an API endpoint to write changes from the PowerSync client.

Additional implementation notes are available here.

​

Status of MongoDB support in PowerSync

In PowerSync nomenclature, Beta means the package is ready to be used for production given you have adequately tested your use case. We typically don’t make any breaking API changes when moving from Beta to V1. Alpha is a bit more unstable and could have breaking changes when moving to Beta, so we do not recommend using it in production.

​

Alpha (Completed)

Refer to the instructions above on how to use the current alpha support for MongoDB.

Known Issues (Alpha)

• FIXED: MongoDB -> PowerSync Service replication is not optimized for performance yet. We are targeting 2,000+ operations per second for the Beta.
• FIXED: Unhelpful “Something went wrong” error in the Dashboard when PowerSync IPs have not been allowed for Atlas users (Network Access -> IP Access List)
• FIXED: Unhelpful “Something went wrong” error in the Dashboard when mongodb:// is used for the URI scheme; mongodb+srv:// must be used
• FIXED: Consistency guarantees are currently eventually consistent — that is, operations can arrive out of order on the client. We are targeting to provide causal+ consistency using changeStreamPreAndPostImages. Update: Instances can now be configured to use Post Images to resolve consistency issues.

​

Beta (In Progress - ETA 2024Q4)

• Availability in PowerSync Cloud
• Fully functional diagnostics API
• Validate that TLS connections Just Work ™️ without any additional configuration
• Address all known issues in Known Issues

​

V1 (Not Started) — Estimated start 2025Q1