Skip to content

Commit 9dd8074

Browse files
cahofmeyrcahofmeyr
authored
MongoDB updates: mention CC as backend option, and other minor updates/corrections (#95)
1 parent d536b06 commit 9dd8074

File tree

4 files changed

+59
-44
lines changed

4 files changed

+59
-44
lines changed

‎installation/app-backend-setup.mdx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,7 @@ See [Authentication Setup](/installation/authentication-setup) for details.
2626
See our [Example Projects](/resources/demo-apps-example-projects#custom-backend-examples) page for examples of custom backend implementations (e.g. Django, Node.js, etc.)
2727

2828
For Postgres developers, using [Supabase](/integration-guides/supabase-+-powersync) is an easy alternative to a custom backend. Several of our demo apps demonstrate how to use [Supabase](https://supabase.com/) as the Postgres backend.
29+
30+
### Hosted/Managed Option for MongoDB
31+
32+
<Tip>For users using MongoDB as a source backend database, an alternative option to running your own backend is to use CloudCode, a serverless cloud functions environment provided by us. We have a template that you can use as a turnkey starting point. See our [documentation here](/usage/tools/cloudcode).</Tip>

‎installation/database-connection.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,8 +139,8 @@ PowerSync deploys and configures an isolated cloud environment for you, which ca
139139
**Note**: PowerSync automatically selects the "Beta" version of the Service when adding a MongoDB connection while MongoDB support is in a beta release, as updates may be made against this version more frequently.
140140

141141
Also see:
142-
- [MongoDB Atlas Migration Guide](/migration-guides/mongodb-atlas)
143-
- [MongoDB Setup](/installation/database-setup#mongodb-alpha)
142+
- [MongoDB Atlas Device Sync Migration Guide](/migration-guides/mongodb-atlas)
143+
- [MongoDB Setup](/installation/database-setup#mongodb-beta)
144144

145145
## <Icon icon="dolphin" iconType="solid" size="24"/> MySQL (Alpha) Specifics
146146

‎installation/database-setup.mdx

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -331,19 +331,16 @@ Notably, some "serverless Postgres" providers do not support logical replication
331331

332332
### Status of MongoDB support in PowerSync
333333

334-
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 (learn more about feature states [here](/resources/feature-status)).
334+
#### Beta Released — December 2024
335335

336-
#### Alpha (Completed)
336+
Our MongoDB connector is [in Beta](https://www.powersync.com/blog/powersync-mongodb-connector-module-now-in-beta) as of December 2024 and is supported for use in production environments. See the [full release notes](https://releases.powersync.com/announcements/mongodb-as-a-backend-database-now-in-beta).
337337

338-
#### Beta (Completed)
338+
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 (learn more about feature states [here](/resources/feature-status)).
339339

340-
MongoDB is now supported for use in production environments.
341340

342-
See [https://releases.powersync.com/announcements/mongodb-as-a-backend-database-now-in-beta](https://releases.powersync.com/announcements/mongodb-as-a-backend-database-now-in-beta) for the full release notes.
341+
#### V1 (In Progress — ETA 2025Q1)
343342

344-
#### V1 (In Progress — ETA 2025H1)
345-
346-
Our roadmap to V1 remains flexible and is strongly guided by customer feedback. Our focus includes enhancing usability, improving documentation such as migration guides, developing reference/demo applications, and exploring support for sharded MongoDB clusters and Atlas Private Endpoints. If you’d like to see any of these features, please visit our product roadmap and upvote/submit ideas.&#x20;
343+
Our roadmap to V1 remains flexible and is strongly guided by customer feedback. Our focus includes enhancing usability, improving documentation such as migration guides, developing reference/demo applications, and exploring support for sharded MongoDB clusters. If you’d like to see any of these features, please visit our product roadmap and upvote/submit ideas.
347344

348345
### Permissions required - MongoDB Atlas
349346

@@ -403,7 +400,17 @@ db.runCommand( {
403400
db.getCollectionInfos().filter(c => c.options?.changeStreamPreAndPostImages?.enabled)
404401
```
405402
406-
Post-images can be configured for PowerSync Cloud instances under the connection settings in the Dashboard (right-click on your instance to edit it). For self-hosted PowerSync instances, configure post-images in the config.yaml file; see an example [here](https://github.com/powersync-ja/self-host-demo/blob/main/demos/nodejs-mongodb/config/powersync.yaml).
403+
Post-images can be configured for PowerSync Cloud instances under the connection settings in the Dashboard (right-click on your instance to edit it). For self-hosted PowerSync instances, configure post-images in the `config.yaml` file; see an example [here](https://github.com/powersync-ja/self-host-demo/blob/main/demos/nodejs-mongodb/config/powersync.yaml).
404+
405+
### MongoDB Atlas private endpoints using AWS PrivateLink
406+
407+
If you need to use private endpoints with MongoDB Atlas, see [Private Endpoints](/installation/database-setup/private-endpoints).
408+
409+
410+
### Migrating from MongoDB Atlas Device Sync
411+
412+
For more information on migrating from Atlas Device Sync to PowerSync, see our [migration guide](/migration-guides/mongodb-atlas) and [this post](https://www.powersync.com/blog/migrating-a-mongodb-atlas-device-sync-app-to-powersync) on our blog.
413+
407414
408415
## <Icon icon="dolphin" iconType="solid" size="24" /> MySQL (Alpha)
409416

‎migration-guides/mongodb-atlas.mdx

Lines changed: 37 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
---
2-
title: "MongoDB Atlas Migration Guide"
3-
description: "This page was last updated on 2024-12-27"
2+
title: "MongoDB Atlas Device Sync Migration Guide"
43
---
54

5+
<Info>We are currently working on a more detailed migration guide. In the meantime, the below guide provides high-level migration information.</Info>
6+
67
## MongoDB Atlas deprecation
78

89
In September 2024, MongoDB [deprecated](https://www.mongodb.com/docs/atlas/app-services/deprecation/#std-label-app-services-deprecation) the following services:
@@ -18,54 +19,53 @@ If you have MongoDB Atlas Device Sync deployed today, at a high level your archi
1819

1920
## PowerSync beta support for MongoDB
2021

21-
As of December 2024, support for MongoDB as a backend database source is available in a beta release. This means that MongoDB replication is considered ready for production-use, provided that you have adequately tested your use cases.
22+
As of December 2024, support for MongoDB as a backend database source in PowerSync is available in [a Beta release](https://www.powersync.com/blog/powersync-mongodb-connector-module-now-in-beta). This means that MongoDB replication is considered ready for production-use, provided that you have adequately tested your use cases.
2223

23-
It is currently available for testing in hosted or self-hosted environments:
24+
It is currently available in [PowerSync Cloud](https://www.powersync.com/pricing) and self-hosted environments:
2425

25-
* Hosted by us: Refer to [Database Connection](/installation/database-connection#mongodb-beta-specifics)
26-
* Self-hosted using Docker Compose: An end-to-end demo app is [available here](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-mongodb). Please refer to its README for further instructions.
26+
* **PowerSync Cloud**: Refer to [Database Connection](/installation/database-connection#mongodb-beta-specifics)
27+
* **Self-hosted**: An end-to-end demo app using Docker Compose is [available here](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-mongodb). Please refer to its README for further instructions.
2728

28-
Migrating to PowerSync's MongoDB module would take you to this: (new components in green)
29+
Migrating to PowerSync would take you to this: (new components in green)
2930

3031
<Frame>
3132
<img src="/images/resources-2.png"/>
3233
</Frame>
3334

34-
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.
35-
36-
### Notable comments on the architecture
35+
### Explanation of the migrated architecture
3736

38-
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.
39-
1. Reads are partitioned using [Sync Rules](/usage/sync-rules)
40-
1. Sync Rules are more flexible than MongoDB Realm Flexible Sync, but are defined server-side and not client-side.
41-
2. Writes are queued locally on the device and sent to the backend sequentially.
42-
1. The backend can be a very thin API layer or can contain significant amounts of logic — [it is up to the developer](/installation/app-backend-setup/writing-client-changes)
37+
1. PowerSync handles writes differently from reads.
38+
* **Reads:** The PowerSync Service connects to your MongoDB database and replicates data in real-time to PowerSync clients. Reads are partitioned using PowerSync's [Sync Rules](/usage/sync-rules)
39+
* Sync Rules are more flexible than MongoDB Realm Flexible Sync, but are defined server-side and not client-side.
40+
* **Writes:** The client-side application can perform writes directly on the local SQLite database. The writes are also automatically placed into an upload queue by the PowerSync client SDK. The SDK then uses a developer-defined `uploadData()` function to manage the uploading of those writes sequentially to the backend. In the `uploadData()` function, the developer calls their backend API.
41+
* The backend can be a very thin API layer or can contain significant amounts of logic — [it is up to the developer](/installation/app-backend-setup/writing-client-changes)
4342
2. The PowerSync Service is generally [available](https://powersync.com/pricing) as a cloud-hosted service (PowerSync Cloud), or you can self-host using our Open Edition.
44-
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.
45-
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.
46-
2. Client-side queries are typically written in SQL. [ORM support](https://www.powersync.com/blog/using-orms-with-powersync) is available for our JavaScript ([React Native](/client-sdk-references/javascript-web/javascript-orm/overview) and [web](/client-sdk-references/javascript-web/javascript-orm/overview)) and Flutter/[Dart](/client-sdk-references/flutter/flutter-orm-support) Client SDKs.
43+
3. The PowerSync Client SDKs use **SQLite** under the hood. Even though MongoDB is a "NoSQL" document database, PowerSync's use of SQLite works well with MongoDB, since the [PowerSync protocol](/architecture/powersync-protocol) is schemaless (it syncs schemaless JSON data) and we dynamically apply a [client-side schema](/installation/client-side-setup/define-your-schema) to the data in SQLite using SQLite views.
44+
* The client-side will most likely be where the bulk of migration work takes place for customers migrating from Atlas Device Sync to PowerSync. See [this post on our blog](https://www.powersync.com/blog/migrating-a-mongodb-atlas-device-sync-app-to-powersync) for a migration example.
45+
* Client-side queries are typically written in SQL. [ORM support](https://www.powersync.com/blog/using-orms-with-powersync) is available for our JavaScript ([React Native](/client-sdk-references/javascript-web/javascript-orm/overview) and [web](/client-sdk-references/javascript-web/javascript-orm/overview)) and Flutter/[Dart](/client-sdk-references/flutter/flutter-orm-support) Client SDKs.
4746
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.
4847

4948
### Migration steps
5049

5150
<Tip>The blog post [Migrating a MongoDB Atlas Device Sync App to PowerSync](https://www.powersync.com/blog/migrating-a-mongodb-atlas-device-sync-app-to-powersync) can serve as a handy guide through the migration process.</Tip>
5251

5352
1. Connect your database to an instance of the PowerSync Service:
54-
1. Using PowerSync Cloud (hosted by us): See [Database Connection](/installation/database-connection#mongodb-alpha-specifics)
55-
2. Using PowerSync Open Edition (self-hosted): Refer to our end-to-end demo app [available here](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-mongodb)
53+
1. **PowerSync Cloud**: See [Database Connection](/installation/database-connection#mongodb-alpha-specifics)
54+
2. **Self-hosted**: Refer to our end-to-end demo app [available here](https://github.com/powersync-ja/self-host-demo/tree/main/demos/nodejs-mongodb)
5655
2. Define [Sync Rules](/usage/sync-rules) in PowerSync — this enables dynamic partial replication so that you don't need to sync your entire MongoDB database to devices.
5756
1. We recommend starting with one or two simple [Global Data](/usage/sync-rules/example-global-data) queries
5857
3. Generate a [Development Token](/installation/authentication-setup/development-tokens)
5958
4. Use our [Diagnostics App](https://diagnostics-app.powersync.com/) to validate that MongoDB is syncing into SQLite as expected.
60-
5. Implement an app using one of our Client SDKs
61-
1. You can continue using your Development Token for a start
62-
2. Implement a "Hello World" app to get a feel, **or** jump straight into pulling the Client SDK into your existing app.
63-
3. Verify that downloads from MongoDB are working.
59+
5. Implement an app using one of our [Client SDKs](/client-sdk-references/introduction)
60+
1. You can continue using your _Development Token_ for authentication as a start.
61+
2. We recommend implementing a "Hello World" app to get a feel for how PowerSync works, _or_ you can jump straight into pulling the Client SDK into your existing app.
62+
3. Verify that syncing from MongoDB is working.
6463
6. Implement [authentication](/installation/authentication-setup/custom)
65-
7. Implement your backend app to accept writes.
66-
1. We have Node.js, Django and Rails demos available [here](/resources/demo-apps-example-projects#custom-backend-examples).
64+
7. Implement your backend app to accept writes. There are currently two options:
65+
1. **Custom self-hosted backend:** If you already have a backend application as part of your stack, you should use your existing backend. Alternatively, we have Node.js, Django and Rails example implementations available [here](/resources/demo-apps-example-projects#custom-backend-examples).
66+
2. **CloudCode hosted/managed backend:** An alternative option is to use CloudCode, a serverless cloud functions environment provided by us. We provide a template that you can use as a turnkey starting point. See our [documentation here](/usage/tools/cloudcode).
6767

68-
### Implementation notes
68+
### Additional notes
6969

7070
#### PowerSync Service
7171

@@ -75,24 +75,28 @@ To [self-host](https://github.com/powersync-ja/powersync-service?tab=readme-ov-f
7575

7676
#### PowerSync Client SDKs
7777

78-
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:
78+
We are constantly adding additional [PowerSync Client SDKs](/client-sdk-references/introduction) and some of them are under very active development. Below are the release status for each language/platform:
7979

80-
| Flavor | Status | ETA |
80+
| Client SDK | Status | Release ETA |
8181
| ------------------------------------------------------------------- | ----------- | ---------------- |
8282
| [JavaScript/Web](/client-sdk-references/javascript-web) | Stable | N/A |
83-
| [React Native](/client-sdk-references/react-native-and-expo) & Expo | Stable | N/A |
83+
| [React Native & Expo](/client-sdk-references/react-native-and-expo) | Stable | N/A |
8484
| [Flutter/Dart](/client-sdk-references/flutter) | Stable | N/A |
8585
| [Kotlin Multiplatform](/client-sdk-references/kotlin-multiplatform) | Beta | V1 ETA 2025Q1 |
8686
| [Swift](/client-sdk-references/swift) | Beta | V1 ETA 2025Q1 |
8787
| Node.js | PoC | Alpha ETA 2025Q1 |
88-
| .NET | Not Started | Alpha ETA 2025Q1 |
88+
| .NET | In Progress | Alpha ETA 2025Q1 |
8989

9090
<Info>
9191
We've had customers inquire about the availability of a Rust/C++ SDK. The PowerSync core SQLite extension is implemented in Rust and we can work with customers to integrate PowerSync into their C++ applications. Please reach out to us at hello@powersync.com or [schedule a call](https://www.powersync.com/contact) with us
9292
</Info>
9393

9494
#### App Backend
9595

96-
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.
96+
Your app backend needs to expose an API endpoint to write changes from the PowerSync client to the backend MongoDB database.
97+
98+
As noted above, there are currently two options:
99+
1. **Custom self-hosted backend:** If you already have a backend application as part of your stack, you should use your existing backend. If you don't yet have one: We have Node.js, Django and Rails example implementations available [here](/resources/demo-apps-example-projects#custom-backend-examples).
100+
2. **CloudCode hosted/managed backend:** An alternative option is to use CloudCode, a serverless cloud functions environment provided by us. We provide a template that you can use as a turnkey starting point. See our [documentation here](/usage/tools/cloudcode).
97101

98-
Additional implementation notes are available [here](/installation/app-backend-setup/writing-client-changes).
102+
Additional backend implementation details are available here: [Writing Client Changes](/installation/app-backend-setup/writing-client-changes).

0 commit comments

Comments
 (0)