Announcing Azure DocumentDB Support (Experimental)

You can now use Azure DocumentDB (formerly Azure Cosmos DB for MongoDB vCore) as a source database for PowerSync, available in an experimental release. It's intended for early testing against your use cases, and your feedback will shape the direction of this integration 🫡

PowerSync adds offline-first behavior and highly responsive UX to apps: they read and write against a local SQLite database, so they don't have to wait on the network, and keep working when the connection is slow or absent. With this release, apps built on DocumentDB can now get these benefits.

How it works

DocumentDB support uses PowerSync's MongoDB connector, which has been generally available for over a year: link your DocumentDB connection string and PowerSync detects DocumentDB automatically.

DocumentDB is not fully MongoDB-compatible, and PowerSync's replication depends on some of the features where the two differ, like change stream behavior. The PowerSync Service applies workarounds for these differences when DocumentDB is detected. The main one: DocumentDB change stream events don't carry the cluster timestamps PowerSync normally uses to order replication checkpoints, so the Service instead writes its own checkpoint documents and matches them by content as they come back through the change stream. For the full design, see the LSN and sentinel checkpoints notes in the powersync-service repository.

Which Cosmos DB products are supported

"Cosmos DB" spans several Microsoft products that are not interchangeable for replication. PowerSync supports only the vCore engine:

• Supported: Azure DocumentDB, previously named Azure Cosmos DB for MongoDB vCore

• Not supported: Azure Cosmos DB for MongoDB (RU-based), Azure Cosmos DB for NoSQL, and the self-hosted open-source documentdb-local engine

The RU-based model is a different engine with a different change stream implementation. To use it with PowerSync, migrate it to Azure DocumentDB first. A source that doesn't report as DocumentDB is treated as standard MongoDB and is unaffected.

How to get started

PowerSync Cloud: add your DocumentDB connection string under the MongoDB tab in the PowerSync Dashboard, the same way you would connect a MongoDB database. See Connect PowerSync to your Database.

Self-hosted PowerSync: add a mongodb connection pointing at your DocumentDB connection string. Requires PowerSync Service v1.23.3 or later.

One setting differs from a standard MongoDB source: leave Post Images set to Off (post_images: off, the default). The auto_configure and read_only modes fail on DocumentDB. This doesn't reduce correctness: DocumentDB always includes the full current document on update events, so updates and deletes still replicate correctly.

Current limitations

• Source database only. DocumentDB is supported as a source database, not as PowerSync’s storage database (especially relevant if you are self-hosting PowerSync). We don’t currently plan to support it for storage.

• Post-images are not supported. As mentioned above, set Post Images to Off (post_images: off, the default); the auto_configure and read_only modes fail (but this does not reduce data integrity).

• Collection drop and rename are not replicated. Already-synced rows remain in PowerSync storage under the old name. To recover, redeploy your Sync Streams to trigger a resync. Regular inserts, updates, and deletes are unaffected.

• Large initial snapshots may not complete on legacy storage. DocumentDB retains only a limited amount of change-feed history. On storage versions 1 and 2, a large or busy source can age its resume position out of that window before the initial snapshot finishes, and replication restarts from scratch. Use Storage Version 3 or later, which consumes the change stream while the snapshot is still running.

• Rows of 15 MiB or larger are not synced. Such rows are dropped with a logged error. This is a general PowerSync limit, not DocumentDB-specific, but it is more reachable on DocumentDB because the source permits documents up to 16 MiB and every change event carries the full document.

• Large documents replicate very slowly. DocumentDB delivers large change events much more slowly than standard MongoDB. The document still replicates correctly, but latency spikes around large documents (including updates that change only a small field), and a single large event delays every change behind it. If your workload includes large documents, validate replication latency against your cluster.

• Streaming updates can be delayed by up to roughly 1 second after an idle period. DocumentDB does not currently support reliable long-polling on its change stream, so PowerSync adds a short, capped delay between polls when the stream is idle. This is a temporary workaround and is expected to be resolved in an upcoming Azure DocumentDB release.

For full details, see the DocumentDB limitations notes in the powersync-service repository.

Feedback and help

DocumentDB support is released as an experimental feature. Behavior may still change, and we can't yet guarantee continued support or long-term stability. This release is intended for early testing and to invite feedback.

Please join us in Discord or open an issue on GitHub to share your feedback or get help.