• Stitch >
• MongoDB Mobile

Mobile Overview

Deprecation

MongoDB has deprecated MongoDB Mobile. We are focusing our efforts on Realm, the most popular database for mobile devices.

Stay up to date and see what we have planned.

Introduction

Modern applications and IoT systems rely on local (on-device) storage to deliver high-quality experiences, especially in the case of intermittent connectivity.

As an app developer, you are typically faced with constructing separate logic for storing data both in the cloud and on the device. Just as MongoDB Stitch simplifies much of the backend logic for you, it also provides a unified SDK for storing data in both Atlas and on the device, using MongoDB Mobile. With MongoDB Mobile, you use a single query language for local and remote data access. MongoDB Mobile also provides native connection to MongoDB Stitch, giving simple access to a full application backend from devices.

For complete tutorials showing how to use MongoDB Mobile, see the To-do App Tutorial.

Overview

MongoDB Mobile comprises two core pieces:

• A mobile-optimized version of the MongoDB database that runs locally on the device, enabling offline access to data.
• Native Java (Android) and Swift (iOS) SDKs that manage the lower-level database operations and provide methods to interact with MongoDB Mobile and the Stitch backend.

The Stitch SDKs provide two separate clients for interacting with MongoDB Mobile:

• Local: The MongoDB Stitch SDK’s local MongoDB client provides access to MongoDB Mobile (MongoDB running locally on the device) only. The SDKs support most CRUD, aggregation, and operational commands supported by MongoDB drivers. Use the local service only if you want a local database that does not sync with Atlas.

• Remote: The SDK’s remote client provides access to both MongoDB Atlas and MongoDB Mobile and provides syncing of data between Atlas and MongoDB Mobile. Use the remote service any time you want access to both Atlas and MongoDB Mobile and you want to ensure your data is kept in sync.

  Note

  Your application can use either the remote service (which provides access to both MongoDB Mobile and Atlas) or the local service, but not both at the same time.

Mobile Sync (Beta)

The remote service enables syncing data changes between MongoDB Mobile and MongoDB Atlas. Your client code specifies which documents it wants to track and how to handle any conflicts and errors that arise. You specify the ConflictHandler, ErrorListener, and ChangeEventListener handlers that Sync will call. Stitch then uses change streams to watch for changes and notify registered clients when a change occurs.

Change Stream Limitations

Stitch opens a single change stream for each synced collection and limits the total number of open change streams on each linked cluster across all Stitch apps based on the cluster’s size. See change stream limitations for more information.

Sync maintains a collection of document IDs for the documents that it synchronizes. Document IDs are added to this sync collection either implicitly or explicitly:

• Document IDs are added to the sync collection implicitly when you insert a document using either the sync().insertOne() or sync().insertMany() method.
• You can identify existing document(s) that you want to synchronize by passing the document ID(s) to either the sync().syncOne() or sync().syncMany() method.

You can remove documents from the synchronization collection by calling either the sync().desyncOne() or sync().desyncMany() method.

Documents that have been marked for synchronization are always available offline for querying and modification using the common MongoDB CRUD operators.

Sync Behavior

Documents that are marked for synchronization include a __stitch_sync_version field, which Stitch uses to manage document versions during merges. When a local document is modified, Stitch increments a field in the __stitch_sync_version.v object, and then synchronizes the changes according to the following Local-to-Remote process:

1. The changes (inserts, updates, replacements, deletes) are applied locally and Sync emits a local change event and marks the document as uncommitted (hasUncommittedWrites == true).
2. The changes are then applied to the remote database immediately, or when the application is back online.
3. If there have been no conflicting changes on the remote database, the change is applied and your ChangeEventListener receives a change event marked as committed. If there is a conflict, Sync records the conflict and passes both the local and remote versions of the document to the ConflictHandler that you specified.
4. If an error occurs that is not a conflict, the error is returned to the ErrorListener and the document is paused and must be fixed by the user before it can be synchronized.

As remote changes occur to documents that you are listening to, they are synchronized locally according to the following Remote-to-Local behavior:

1. For each unprocessed remote change, MongoDB Stitch finds the corresponding local document.
2. If the local document does not yet have the change applied, and there are no conflicts, then MongoDB Stitch applies the change and sends a change event to the ChangeEventListener.
3. If there are conflicts, then MongoDB Stitch passes both the local and remote versions of the document to the ConflictHandler that you specified.

Sync States

At any given time, Sync is in one of the following states:

• Online - Sync will run each time there are pending local changes, and change events will be emitted for any local changes and for any remote changes that do no conflict, or were resolved.
• Offline - All local changes are queued in Sync. Change events are emitted for any local changes.

Likewise, any tracked document may be in a paused state: if there is an error during the synchronization of a document, the user is notified via the ErrorListener that you specified, and the document is paused; this is, it will no longer be marked for sync until the user makes the necessary changes (updates it or deletes it).

External Data Changes

If changes are made on the remote dataset from a non-Stitch application, you must ensure that you handle the Stitch versioning correctly, or else the changes will not be synchronized to the client(s) correctly. There are two ways you can approach this:

• Increment the value of the v field within the __stitch_sync_version object with the next 64-bit integer (NumberLong):

  

• Delete or $unset the __stitch_sync_version field prior to making other changes to the document. When Sync next runs, it will consider the changes as a new version.

Usage Guides

Guide	Description
Set up a MongoDB Mobile Project	Learn how to install the MongoDB Mobile libraries and set up a project.
Build a Mobile App with Sync	Learn how to build an app that uses on-device storage.
Build a Local-Only Mobile App	Learn how to build an app that uses on-device storage.

Tutorials

To-do App Tutorial

A tutorial that builds a complete To-do App, including on-device data storage.

Reference Documentation

Subject	Description
MongoDB Mobile Features	Includes differences between MongoDB 4.0 and MongoDB Mobile.
Stitch Java SDK	The SDK documentation for Android app development.
Stitch Swift (iOS) SDK	The SDK documentation for iOS app development.

←   GraphQL Types, Resolvers, and Operators Set up a MongoDB Mobile Project  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.