FAQ >
Connection String Options

Connection String Options¶

On this page

Why Does My Cluster Have Multiple Connection Strings?
What Does This Mean for GCP 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?

Atlas provides multiple connection strings. These strings allow you to connect to your clusters from both public and private contexts.

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 whitelisted 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 GCP
AWS peered clusters with a custom DNS service.

Use this connection string with applications connecting:

Within an Azure or GCP peered network
To AWS clusters when using AWS with custom DNS service.

AWS clusters with AWS PrivateLink configured have one or more connection strings. Each string resolves to the IP address of an Endpoint Interface. Use these connection strings with applications connecting over PrivateLink.

What Does This Mean for GCP or Azure Clusters in Peering-Only Mode?¶

Before this update, you enabled peering-only mode to connect to databases on peer networked Azure or GCP clusters. This mode:

Affected global DNS resolution and
Limited any database connections outside the peered network.

Multiple horizons lifts these restrictions and unlocks additional features. If your project has MongoDB 3.6 or later clusters, you can use:

To update your applications to use Atlas clusters running MongoDB 3.6 or later:

Update your application to use Private IP for Peering connection strings and
Disable Peering-Only mode.

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.

Private IP for Peering connection strings work with MongoDB 3.6 or later clusters.

How Do I Disable Peering-Only mode?¶

To disable Peering-Only mode using the Atlas interface:

Ensure all clusters in your project use MongoDB 3.6 or later.
Update all applications to use Private IP for Peering connection strings.
Navigate to your Atlas project.
Click Settings under the Project section in the left navigation.
Toggle Connect via Peering Only (GCP and Azure) to Off.

To disable Peering-Only mode using the Atlas API:

Ensure all clusters in your project use MongoDB 3.6 or later.
Update all applications to use Private IP for Peering connection strings.

Call the Set Private IP mode for Project endpoint:

copy

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:

copy

{
  "enabled" : false
}

How Does This Affect AWS VPC Peering When I Use Custom DNS?¶

Before this change, 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:

Toggle the Using Custom DNS on AWS with VPC Peering on On from the Project Settings menu.
View the connect modal for your AWS Cluster.
Select the Private IP for Peering connection string.

How Do I Identify Which Connection String My Application Uses?¶

The structure of the connection string’s URI indicates the string’s type.

Standard Connection Strings¶

Standard connection strings follow this format:

copy

mongodb://clustername-shard-00-00.abc123.mongodb.net:27017
mongodb+srv://clustername.abc123.mongodb.net

The dot before abc123 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 (.).

Example

This legacy connection string:

copy

mongodb+srv://clustername-abc123.mongodb.net

is written as this standard connection string:

copy

mongodb+srv://clustername.abc123.mongodb.net

Private Connection Strings¶

Private connection strings follow this format:

copy

mongodb://clustername-shard-00-00-pri.abc123.mongodb.net:27017
mongodb+srv://clustername-pri.abc123.mongodb.net

The -pri before abc123 matters. URIs using this format resolve to private IP addresses reachable within the peered network.

AWS Privatelink Connection Strings¶

AWS PrivateLink connection strings follow this format:

copy

mongodb://pl-us-east-1a.abc123.mongodb.net:1234
mongodb+srv://pl-us-east-1a.abc123.mongodb.net

URIs using this format can be reachable via the AWS VPC where someone configured PrivateLink, though access can be transient from other VPCs peered in turn.

Legacy Connection Strings¶

Before this change, you wrote Atlas connection strings as follows:

AWS	foo-shard-00-00-abc123.mongodb.net foo-abc123.mongodb.net
Azure	foo-shard-00-00-abc123.azure.mongodb.net foo-abc123.azure.mongodb.net
GCP	foo-shard-00-00-abc123.gcp.mongodb.net foo-abc123.gcp.mongodb.net

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.

← FAQ API →