Connect to MongoDB Data Sources

Atlas Device Sync, Data API, and HTTPS Endpoints are deprecated. Refer to the deprecation page for details.

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.

Note

Backend Encryption

All internal communication between App Services and Atlas is encrypted with x509 certificates.

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

Data Source Requirements for Device Sync

To enable Device Sync, your App Services App must have at least one linked data source that meets the following requirements:

A non-sharded MongoDB Atlas cluster running MongoDB 5.0 or later.
Cluster cannot be a serverless instance or Federated database instance. Refer to Data Source Limitations.

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 the App Services CLI or GitHub deployment:

Navigate to the Data Source Management Screen

In the App Services UI, click Linked Data Sources under Manage in the left navigation menu.

Link a New Data Source

Click Link a Data Source and provide the following configuration information on the Data Source Configuration screen:

Field

Description

Data Source

A MongoDB Atlas cluster or Federated database instance associated with the same project as your App.

App Services Service Name

A name for the App Services service that connects to the data source. You will use this name when referring to the data source in other parts of your application, such as when you instantiate a MongoDB service client.

Example

Consider a MongoDB cluster data source with the App Services Service Name myAtlasCluster. To create a service client in a function you would use the following code:

const myAtlasCluster = context.services.get("myAtlasCluster");

MongoDB Connection String

config.wireProtocolEnabled

Required for Atlas clusters. Not enabled for Federated database instances. A boolean indicating whether App Services should allow clients to connect to this cluster with a connection string over the wire protocol.

Read Preference

Required for Atlas clusters. Not available for Federated database instances. Specifies the read preference of the cluster. The default read preference (primary) should be sufficient for most use cases.

Save the Linked Data Source

Once you've selected and configured a MongoDB cluster or Federated database instance, click Save. App Services immediately begins the process of linking to the data source, which could take up to five minutes.

Pull the Latest Version of Your App

To link a MongoDB Atlas cluster or Federated database instance with the App Services CLI, you need a local copy of your application's configuration files.

To pull a local copy of the latest version of your app, run the following:

appservices pull --remote="<Your App ID>"

Tip

You can also download a copy of your application's configuration files from the Deploy > Export App screen in the App Services UI.

Create a Data Source Configuration Directory

Create a new subdirectory with the name that you'll use for the data source in /data_sources.

mkdir -p data_sources/<Data Source Name>

Add a Data Source Configuration File

Add a file named config.json to the data source subdirectory. The file can configure either a MongoDB Atlas cluster or a Federated database instance.

The configuration file should have the following general form:

/data_sources/<Service Name>/config.json

{
  "name": "<Service Name>",
  "type": "mongodb-atlas",
  "config": {
    "clusterName": "<Atlas Cluster Name>",
    "readPreference": "<Read Preference>",
    "wireProtocolEnabled": <Boolean>,
    "sync": <Sync Configuration>
  }
}

Note

For detailed information on the contents of a cluster configuration file, see Linked MongoDB Cluster Configuration.

/data_sources/<Service Name>/config.json

{
  "name": "<Service Name>",
  "type": "datalake",
  "config": {
     "dataLakeName": "<Federated database instance name>"
   }
}

Note

For more information, see Federated database instance Configuration.

Deploy the Data Source Configuration

Once you've defined and saved a config.json file for the data source, you can push the config to your remote app. App Services immediately begins the process of linking to the data source, which could take up to five minutes.

appservices push --remote="<Your App ID>"

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.

Back

Okta (Custom JWT)

CRUD & Aggregation APIs