Connect to MongoDB Data Sources

On this page

Overview

Read, Write, and Aggregate Data
Secure and Validate Data
Automatically Sync Data
React to Changing Data
Link a Data Source
Navigate to the Data Source Management Screen
Link a New Data Source
Save the Linked Data Source
Pull the Latest Version of Your App
Create a Data Source Configuration Directory
Add a Data Source Configuration File
Deploy the Data Source Configuration
Data Source Limitations
Atlas Data Federation
Serverless Instances

Realm is now Atlas Device SDK – Learn More

Overview

A data source represents a MongoDB Atlas instance in the same project as your app. You use data sources to store and retrieve your application's data.

Most apps connect to a single data source, but you can configure multiple data sources if your data is spread across instances. You define a unique name for each data source linked to your application and use the name to refer to the data source throughout your app.

Requests to data sources are routed through Atlas App Services. Because of this, App Services automatically opens and closes database connections. This means you don't need to worry about calling db.close() when using a data source.

Read, Write, and Aggregate Data

You can read and write data in a data source from a server-side function or connect from a client application. You write queries using standard MongoDB query syntax.

exports = async function() {
   const mongodb = context.services.get("mongodb-atlas");
   return mongodb
      .db("myDatabase")
      .collection("myCollection")
      .findOne()
}

To learn how to work with a data source in an Atlas Function, refer to the following guides:

To learn how to work with a data source from a Realm SDK, refer to Query Atlas from Client Apps.

Note

Linked data sources do not support all MongoDB CRUD and Aggregation operations. Some operations are not available when you query MongoDB as a specific user due to overhead from schema validation and data access rules. You can bypass some limitations by querying MongoDB as the system user instead.

For more information on which operations are supported, see CRUD & Aggregation APIs.

Secure and Validate Data

Data sources allow you to define access rules and document schemas for the data they contain. Rules dynamically authorize users to read and write subsets of your data and schemas control the shape and contents of each document.

Read and write operations on a linked data source are secure by default. A user cannot read or write any data unless a rule explicitly allows them to. Any data inserted or modified by an authorized user must conform to the corresponding schema.

If you do not define rules for a collection, queries on the collection will fail. This means that you can safely expose a properly configured data source interface in client applications without risking data corruption or leaks.

Automatically Sync Data

Atlas Device Sync applications store data and sync data changes to a linked cluster, called the synced cluster. The sync protocol ensures that your data is eventually consistent across all sync clients and the synced cluster.

To learn more about Atlas Device Sync and how it interacts with your app's data sources, see Atlas Device Sync.

Note

Version 4.4 Required for Sync

In order to use Atlas Device Sync, your cluster must run MongoDB version 4.4 or newer.

React to Changing Data

You can create database triggers that run functions automatically in response to changing data. Triggers use MongoDB change streams to observe the data source and execute a function whenever a change event matches the trigger configuration. A trigger function can run arbitrary code and can access a change event for detailed information about the change that caused it to run.

To learn more about how triggers work and how to define your own, see Database Triggers.

Important

Triggers are only available for data sources that support change streams. You cannot define triggers on a Federated database instance or serverless Atlas instance.

Link a Data Source

A configured data source in your app is linked to the underlying instance in Atlas. You can link multiple instances to your app and even create multiple data sources that link to the same underlying instance.

You can configure a new linked data source in the App Services UI or by defining and pushing a configuration file with Realm CLI or GitHub deployment:

Data Source Limitations

A linked data source can represent one of several instance MongoDB Atlas instance types. Depending on the type of the underlying instance, not all functionality is supported.

Once you've linked a data source, you cannot change the underlying instance type. Instead, you can link a new data source with another instance type.

Atlas Data Federation

You can link a Federated database instance to your app as a MongoDB data source. However, there are some caveats to keep in mind when working with Atlas Data Federation:

Federated data sources do not support write operations.
You can only access a Federated data source from a system function.
You cannot connect to a Federated data source via the wire protocol.
You cannot define roles and permissions for a Federated data source.
You cannot set a read preference for a Federated data source.
You cannot create a database trigger on a Federated data source.
You cannot use a Federated data source as your app's Device Sync cluster.

Serverless Instances

You can link a serverless instance to your app as a MongoDB data source. However, serverless instances do not currently support change streams, so the following features are limited:

You cannot create a database trigger on a serverless instance.
You cannot use a serverless instance as your app's Device Sync cluster.
You cannot watch collections for changes data sources that are serverless MongoDB Atlas instances.

← Okta JWT Authentication (Custom JWT)CRUD & Aggregation APIs →