FAQ: Connection String Options
On this page
- Why does my cluster have multiple connection strings?
- What does this mean for Google Cloud or Azure clusters in peering-only mode?
- Can my VNet-peered Azure cluster span multiple regions?
- How do I disable peering-only mode?
- How does this affect AWS VPC peering when I use custom DNS?
- How do I identify which connection string my application uses?
- Do I have to update my connection string when migrating to a different cloud provider from a
M0,M2, orM5cluster to another? - Do I have to update my connection string when migrating to a different cloud provider from a dedicated cluster to another?
Atlas provides multiple connection strings. These strings allow you to connect to your clusters from both public and private contexts. Atlas always assigns clusters unique connections strings so that no two clusters share hostnames or connection strings across Atlas.
Why does my cluster have multiple connection strings?
To connect to Atlas, point your applications to a URI to communicate with a cluster. Atlas creates clusters with more than one node or host. Each node has its own hostname that resolves to an IP address. The URI, known as a connection string, to which Atlas connects might have more than one hostname. Configure Atlas to accept connections to the cluster hosts from allowed IP addresses.
Atlas secures connections from public IP address through authentication and TLS. If you want to connect to private IP addresses, you can use:
These features all manage communication over internal IP addresses within secure networks.
Atlas provides more than one connection string when using secure networks. Each network offers a string that resolves to different IP addresses.
All clusters have a standard connection string. This resolves to the cluster's:
Public IP addresses for Internet connections and
VPC private IP addresses for AWS clusters when resolved from a peered VPC.
Use this string for applications connecting over the Internet or connecting to peered clusters in AWS.
Clusters with peered networks have a Private IP for Peering connection string. This string resolves to IP addresses available to:
Peered networks in Azure or Google Cloud
AWS peered clusters with a custom DNS service.
Use this connection string with applications connecting:
Within an Azure or Google Cloud peered network
To AWS clusters when using AWS with custom DNS service.
AWS or Azure clusters in regions with private endpoints configured have one or more connection strings. Each string resolves to the private IP address of a network interface in your VPC or VNet that connects directly to a load balancer in the Atlas VPC or VNet. Use these connection strings with applications connecting with private endpoints.
What does this mean for Google Cloud or Azure clusters in peering-only mode?
Before 31 March 2020, you were required to enable peering-only mode to connect to databases on peer networked Azure or Google Cloud clusters. This mode:
Affected global DNS resolution and
Limited any database connections outside the peered network.
Multiple horizons lifts these restrictions and unlocks the following additional features:
To leverage multiple horizons, complete the following tasks:
Update your application's existing connection strings to use Private IP for Peering connection strings.
Connect using the strings outlined in Why does my cluster have multiple connection strings.
Note
You can keep connecting to your clusters using existing peering-enabled connection strings at this time. Peering-Only mode prevents access to the improved functionality and reduced limitations of multiple horizons. To use the new features and remove the legacy limitations, MongoDB requires that you use the new connection strings.
Can my VNet-peered Azure cluster span multiple regions?
Yes.
Change your applications to connect using the Private IP for Peering connection string. This change allows your applications to connect from peered networks using the UI or API.
To expand into more regions, disable Peering-Only mode on existing Azure clusters first.
How do I disable peering-only mode?
To disable Peering-Only mode using the:
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
If it's not already displayed, click Clusters in the sidebar.
The Clusters page displays.
Update All Applications to Use Private IP for Peering Connection Strings.
Change any URLs in your applications that use your Atlas clusters to use Private IP for Peering connection strings.
In Atlas, go to the Project Settings page.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Next to the Projects menu, expand the Options menu, then click Project Settings.
The Project Settings page displays.
Verify all clusters in your project use MongoDB 5.0 or later.
Call the get all API endpoint to return all clusters and their MongoDB versions:
Example
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --include \ --request GET "https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/clusters?pretty=true"
If successful, the response should include:
{ "results": [{ ... "mongoDBMajorVersion": "5.0", "mongoDBVersion": "5.0.14", ... },{ ... "mongoDBMajorVersion": "5.0", "mongoDBVersion": "5.0.12", ... } ] }
Update All Applications to Use Private IP for Peering Connection Strings.
Change any URLs in your applications that use your Atlas clusters to use Private IP for Peering connection strings.
Disable Private IP Mode on Your Clusters.
Call the API endpoint to Disable Private IP Mode.
Example
Using curl, you would invoke this command:
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --include \ --request PATCH "https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/privateIpMode?pretty=true" \ --data ' { "enabled" : false }'
Change {GROUP-ID} to the
Project ID of your project.
If successful, the response displays:
1 { 2 "enabled" : false 3 }
How does this affect AWS VPC peering when I use custom DNS?
Before 31 March 2020, applications deployed within AWS using custom DNS services and VPC-peered with Atlas couldn't connect over private IP addresses:
Custom DNS resolved to public IP addresses.
AWS internal DNS resolved to private IP addresses.
Applications deployed with custom DNS services in AWS should use Private IP for Peering connection strings.
To show these strings:
In Atlas, go to the Project Settings page.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Next to the Projects menu, expand the Options menu, then click Project Settings.
The Project Settings page displays.
How do I identify which connection string my application uses?
The structure of the connection string's URI indicates the string's type. If you have created a peering connection or private endpoint, Atlas displays more than one of these options for your use.
Standard Connection Strings
Standard connection strings follow this format:
mongodb://xyz456-shard-00-00.ab123.mongodb.net:27017 mongodb+srv://xyz456.ab123.mongodb.net
The dot before ab123 matters. URIs using this format resolve
to public IP addresses except when connecting from inside AWS with
VPC-peering configured.
Important
This format changes one character from the
Legacy Connection Strings: a hyphen
(-) after the cluster name becomes a period (.).
For example, this legacy connection string:
mongodb+srv://xyx456-ab123.mongodb.net
is written as this standard connection string:
mongodb+srv://xyx456.ab123.mongodb.net
For new clusters, replica sets and shards don't derive their name from the name of the cluster. The new names use a six alphanumeric character ID.
Private Connection Strings
Private connection strings follow this format:
mongodb://xyx456-shard-00-00-pri.ab123.mongodb.net:27017 mongodb+srv://xyx456-pri.ab123.mongodb.net
The -pri before ab123 matters. URIs using this format
resolve to private IP addresses reachable within the peered network.
If you configure network peering for your cluster, you must use the
new hostname when you connect to your cluster to utilize the peering.
Important
In new clusters, replica sets and shards don't derive their name from the name of the cluster. The new names use a six alphanumeric character ID.
AWS Privatelink Connection Strings
AWS PrivateLink connection strings follow this format:
mongodb://pl-0-us-east-1a.ab123.mongodb.net:1024 mongodb+srv://pl-0-us-east-1a.ab123.mongodb.net
If you enable the regionalized private endpoint setting, AWS PrivateLink connection strings follow this format:
mongodb://pl-0-us-west-1.ab123.mongodb.net:1024 mongodb+srv://cluster0-pl-0-us-west-1.ab123.mongodb.net
URIs using this format can be reachable via the AWS VPC where someone configured PrivateLink, though access can be transitive from other VPCs peered in turn.
Azure Private Link Connection Strings
Azure Private Link connection strings follow this format:
mongodb://pl-0-eastus2.ab123.mongodb.net:1024 mongodb+srv://pl-0-eastus2.ab123.mongodb.net
If you enable the regionalized private endpoint setting, Azure Private Link connection strings follow this format:
mongodb://pl-0-eastus2.ab123.mongodb.net:1024 mongodb+srv://cluster0-pl-0-eastus2.ab123.mongodb.net
URIs using this format can be reachable via the Azure VNet where someone configured Private Link, though access can be transitive from other VNets peered in turn.
Legacy Connection Strings
Before 31 March 2020, you wrote Atlas connection strings as follows:
AWS | | ||
Azure | | ||
Google Cloud | |
If you enabled Private Only mode, these hostnames resolve to peered network IP addresses. If you disabled that mode, hostnames resolve to public IP addresses.
If your application uses a legacy connection string in Peering Only mode, switch to Private IP for Peering connection strings.
Do I have to update my connection string when migrating to a different cloud provider from a M0, M2, or M5 cluster to another?
If you have a legacy connection string and you want to change cloud
providers, your connection string must include .gcp or .azure
and you want to do one of the following:
Move to Google Cloud or Azure
Move off of Google Cloud or Azure
Note
Either operation may change your connection string. In the Atlas UI, click Connect on your cluster after the upgrade completes for an updated connection string.
Do I have to update my connection string when migrating to a different cloud provider from a dedicated cluster to another?
It depends on the following:
which cloud provider your current cluster uses
when you created the cluster
GCP or Azure Clusters Created Before November 3, 2020
If you created your cluster before multi-cloud clusters were introduced on November 3, 2020, and your cluster runs on Google Cloud or Azure:
Open the cluster builder.
Edit the cluster.
Add read-only nodes from your target cloud provider.
Note
If you are using legacy backups, keep one node in your current cloud provider, and move the rest to your target cloud provider.
Review and submit the changes.
Copy the resulting comma-delimited URI connection string.
Replace the connection string in your application with this new standard connection string.
This allows your application to connect to nodes from multiple cloud providers.
Restart your application.
Make sure that your application can connect to Atlas.
After the first change completes, reconfigure your cluster:
Remove all electable nodes using the original cloud provider.
Remove the read-only nodes for the target cloud provider.
Add the same number of electable nodes using the target cloud provider.
Note
If you are using legacy backups, wait until new backups are taken, then move the remaining node to your target cloud provider.
Review and submit the changes.
Copy the resulting comma-delimited URI connection string.
Replace the URI connection string in your application with this new URI connection string.
Restart your application.
Make sure that your application can connect to Atlas.
AWS and Clusters Created After November 2, 2020
If your cluster runs on AWS or runs on any provider and was created after November 2, 2020, your connection string doesn't change and you don't experience cluster downtime.
Open the cluster builder.
Edit the cluster.
Change the cloud provider.
Review and submit the changes.