Wire Protocol
On this page
- Overview
- Compatible Clients
- Connection Strings
- Credentials
- Parameters
- Enable Wire Protocol Connections
- Navigate to the Data Source Configuration Screen
- Enable Connection Strings for the Cluster
- Pull the Latest Version of Your App
- Enable Wire Protocol for the Cluster
- Deploy the Updated Data Source Configuration
- Connect Over the Wire Protocol
- Connect to Realm with a Connection String
- Read and Modify Data
- Call a Function
- Call a Service Action [DEPRECATED]
- Get the Logged In User's Data
Overview
MongoDB Realm natively implements a subset of the MongoDB wire protocol, which allows you to connect to a Realm app through one of its linked MongoDB Atlas data sources using standard MongoDB drivers and tools. Clients use a specialized MongoDB Realm connection string to connect and send requests. MongoDB Realm supports most client features over the wire protocol, including role-based data access rules, functions, and service actions.
This is a good choice for languages that do not currently have a Realm
SDK. The examples here are for Python, C++11, and the Mongo Shell. Any
MongoDB driver that supports the
appName
connection string parameter can use the wire protocol to
connect to MongoDB Realm.
Data Lake data sources do not support connections via the wire protocol.
Compatible Clients
You can use the following tools and drivers to communicate with MongoDB Realm using a connection string:
- Version 4.0+ of the mongo shell.
- Any MongoDB driver that supports the
appName
connection string parameter. All official MongoDB drivers support this parameter in their current releases.
Connections to MongoDB Realm over the wire protocol have access to the full functionality of the MongoDB Service. However, MongoDB Realm does not support all operations and features available in standard tools and clients. For details, see MongoDB Service Limitations.
Connection Strings
To connect to MongoDB Realm over the wire protocol, you must construct a
MongoDB connection string that
includes credentials for an application user and an
application-specific appName
query parameter.
You must URL encode connection strings before you can use them to connect to MongoDB Realm. Connection strings in the Realm UI are properly encoded by default.
MongoDB Realm connection strings have the following form:
mongodb://<credentials>@realm.mongodb.com:27020/?<parameters>
Credentials
All MongoDB Realm operations that you issue over the wire protocol run in the context of a specific application user that you specify in the connection string. The user must be registered with the Email/Password, API Key, or Custom JWT authentication provider.
The contents of connection string credentials depend on the authentication provider with which the user registered:
Parameters
MongoDB Realm requires specific connection string options that identify the application you want to connect to and the authentication provider associated with the credentials that you provide.
MongoDB Realm connection strings have the following query parameters:
Parameter | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
authMechanism | This parameter should always be set to PLAIN . | |||||||||
authSource | This parameter should always be set to $external . | |||||||||
appName | Uniquely identifies the application, MongoDB service, and authentication provider to which you want to connect. The
|
Enable Wire Protocol Connections
You must enable wire protocol connections for a linked clusters before you can connect to a Realm app with a connection string.
Connect Over the Wire Protocol
Connect to Realm with a Connection String
To connect to MongoDB Realm over the wire protocol, pass a URL-encoded MongoDB Realm connection string when you create a client, just as you would with a regular connection string.
Read and Modify Data
While connected to MongoDB Realm over the wire protocol you can use standard MongoDB CRUD operations. MongoDB Realm applies role-based data access rules to all queries in the context of the authenticated user specified in the connection string credentials.
Call a Function
You can call functions using the callFunction
database command.
Command | Description | Prototype | ||||
---|---|---|---|---|---|---|
Calls the specified function and returns any
result. |
|
Call a Service Action [DEPRECATED]
You can call service actions using the callServiceFunction
database
command.
Command | Description | Prototype | |||||
---|---|---|---|---|---|---|---|
Calls the specified service action and
returns any result. |
|
Get the Logged In User's Data
You can get the user object for the authenticated
user using the userProfile
database command.
Command | Description | Prototype | |||
---|---|---|---|---|---|
Returns the user object for the authenticated
user. |
|