MongoDB Sync Connector
Bi-directional Data Sync with MongoDB - on-premise and to the cloud
Last updated
Was this helpful?
Bi-directional Data Sync with MongoDB - on-premise and to the cloud
Last updated
Was this helpful?
ObjectBox Data Sync syncs data with MongoDB using the integrated MongoDB Sync Connector. Changes made on ObjectBox clients are synchronized in real-time to MongoDB and vice versa.
ObjectBox Sync brings your data in MongoDB to the edge (e.g. mobile and IoT devices, big and small servers) and synchronizes changes back to MongoDB. By using ObjectBox Sync, you can make your MongoDB data always available: continue to work offline and sync in real-time when online.
Do not connect to your MongoDB production instance! Use a separate instance for testing purposes.
Configuring the MongoDB Sync Connector involves the following steps:
Run the ObjectBox Sync Server without MongoDB Sync Connector and validate it actually syncs data. See the Sync Server configuration for details.
Ensure that your MongoDB instance is a replica set. This is required for the MongoDB Sync Connector to work.
Provide the MongoDB configuration, e.g. the connection URL, to the Sync Server and restart it. This can be done via CLI arguments or the JSON configuration file (see below).
Verify the MongoDB connection using the Admin UI.
In general, the ObjectBox Sync server requires a data model to be provided (a JSON file, see ObjectBox Sync Server). This data model is also used by the MongoDB Sync Connector to map data between ObjectBox and MongoDB. On how this works, see the chapter on data mapping below.
Only a MongoDB replica set instance provides the necessary features for the MongoDB Sync Connector to work (e.g. MongoDB's change streams). Note that all MongoDB Atlas clusters are already replica sets, so you are good to go with them.
A local standalone MongoDB instance (MongoDB Community Edition is fine) can be converted to a replica set. You can do this either by following the official MongoDB documentation, or by following these simplified steps (tested on Ubuntu Linux) for a single node setup:
Stop the MongoDB service: sudo systemctl stop mongod
Edit the MongoDB configuration file: sudo vi /etc/mongod.conf
Add the following lines to the configuration file:
Start the MongoDB service: sudo systemctl start mongod
Connect to the MongoDB shell: mongosh
Initialize the replica set via the MongoDB shell: rs.initiate()
To configure the ObjectBox MongoDB Sync Connector via CLI arguments, you can use the following options:
--mongo-url: The MongoDB connection string (URL or URI). This can be an empty string for the default 127.0.0.1:27017 host.
--mongo-db: The primary MongoDB database name; the "database" containing the collections used for sync. By default this is "objectbox_sync".
For the JSON configuration, ensure that the server version's date is 2024-10-07 or higher. Before that, you can use {"mongoUrl": "1.2.3.4"} without the mongoDb config node.
If you prefer doing this via sync-server-config.json, you need to add a new mongoDb config node, which contains key/value pairs for MongoDB specific configuration attributes:
ObjectBox and MongoDB have many similarities. Nevertheless, it's important to understand the differences in terminology and concepts between the two databases. The following table illustrates these differences. It serves as background information on how to map things between the two systems:
Database containing the data
A store, grouped into types (data classes).
A database, grouped into collections.
What your application "opens"
Using a name or directory a single store (database) is opened locally on device. (In the case of Sync, this is the "client database".) Multiple stores can be opened, which are strictly separate.
A client is used to connect to a MongoDB server. All databases can be accessed on the server remotely.
Arranging data in a database (e.g. data sets)
A box holds all objects of the same type. A type typically matches a data class in programming languages. It's part of a strict schema (data model) that is enforced. The type definition consists of a fixed set of properties.
Collections are used to group documents together. By default, no strict rules are imposed (schema-less).
Data record
An object is an instance of a type. It can have data values for the properties defined in the type.
A document is a set of data values called fields. It's very similar to a JSON file.
Modelling related data
Objects can have to-one and to-many relationships to other objects. Relationships are bidirectional. Data is typically normalized.
Typically, a document embeds all "related data" into itself resulting in larger documents. Data is typically not normalized. Alternatively, one can also choose to use references, which is more similar to relationships.
Nested data records
Nested data is supported by flex properties. E.g. these allow maps, which can contain nested data structures (JSON-like).
Documents contain nested data by default.
Identifiers (IDs)
IDs are 64-bit integers. They are unique within its box and database instance.
Typically, Mongo's Object ID (OID) consists of 12 bytes. Other ID types are supported. OIDs are considered globally unique.
The data model used by ObjectBox defines types, which are mapped to MongoDB collections. Similarly, the properties of a type are mapped to keys inside a MongoDB document. Thus, you should ensure that the ObjectBox data model matches the MongoDB schema. E.g. if you have an existing MongoDB database, ensure to match the names when you create the ObjectBox model.
When you compare the data structure of simple data elements, the difference is not big. Without nested data, the main difference you will note is the ID type.
Note: nested documents are supported via the ObjectBox "Flex" property type, which can hold a map-like (JSON-like) structure. We are also considering alternatives to this, so let us know if you have specific requirements.
ObjectBox automatically maps IDs when syncing with an external system like MongoDB. This way, both systems continue to work with their native ID types. This means that by default, the MongoDB ID is not present in ObjectBox objects and vice versa. Note that ObjectBox Sync also applies internal ID mapping on each ObjectBox device.
ID mapping also happens for relations (starting with version Alpha 3 of MongoDB Sync Connector). Consider ObjectBox to-one relations, which have a single relation property pointing to another object using a 64-bit integer ID. This will become a reference field in MongoDB's document containing the MongoDB object ID (OID). See the following illustration for an example:
ObjectBox IDs are only valid on their local device. Do not store them manually apart from relations, e.g. as a custom list or vector, when you want to sync to other devices.
