Edit

Share via

Connect to Azure DocumentDB using Azure portal

MongoDB Shell (mongosh) is a JavaScript and Node.js environment for interacting with MongoDB deployments. It's a popular community tool to test queries and interact with the data in your Azure DocumentDB cluster. The Azure portal contains multiple tools to query MongoDB data including the Azure Cloud Shell. Azure Cloud Shell is an interactive, authenticated, browser-accessible terminal for managing Azure resources. This article explains how to connect to an Azure DocumentDB cluster using MongoDB Shell within Azure Cloud Shell.

Prerequisites

  • An Azure subscription

    • If you don't have an Azure subscription, create a free account

  • An existing Azure DocumentDB cluster

  • Firewall rules that allow clients within your networks to connect to the cluster. For more information, see configure firewall.

  • (Optional) These prerequisites are only required if you're using Azure Cloud Shell within a virtual network that's the same or peered with Azure DocumentDB.

    • One or more existing Azure Virtual Networks with subnets for Azure Cloud Shell and Azure DocumentDB deployment.

    • A private endpoint for the Azure DocumentDB cluster. For more information, see configure private link.

    • Azure Cloud Shell deployed to the same or a peered virtual network with connectivity to the Azure DocumentDB private endpoint. For more information, see deploy Cloud Shell to virtual network.

Enable access to your cluster from Azure Cloud Shell

First, ensure that Azure Cloud Shell can access your Azure DocumentDB cluster by allowing its IP addresses in the firewall.

  1. Sign in to the Azure portal (https://portal.azure.com).

  2. Navigate to the Azure DocumentDB cluster.

  3. Select Networking from the navigation menu.

  4. On the Networking page within the Public access section, select the + Add Azure Cloud Shell IPs option to automatically add your current IP address to the allowed list.

  5. Select Save to apply the changes.

Note

To ensure connectivity, make sure the specific IP addresses for your region are allowed. For more information, see IP addresses for Azure DocumentDB.

Connect using Azure Cloud Shell from Quick Start

To connect directly to Azure DocumentDB using MongoDB Shell, use the Quick Start experience available on the resource's page in the Azure portal.

  1. In the cluster resource page, select Quick start (preview) from the navigation menu.

  2. Then, select Open MongoDB shell.

  3. Wait for the MongoDB Shell environment to start.

  4. Once the environment is ready, enter Y to accept the notice.

    Note

    If you're experiencing an issue connecting using MongoDB Shell after accepting the notice, make sure Azure Cloud Shell has access to your cluster.

  5. Now, enter your password to connect your cluster to Cloud Shell.

Get cluster credentials

Get the connection string you need to connect to this cluster.

  1. Sign in to the Azure portal (https://portal.azure.com).

  2. Navigate to the existing Azure DocumentDB cluster.

Get the credentials you use to connect to the cluster.

  1. On the cluster page, select the Connection strings option in the resource menu.

  2. In the Connection strings section, copy or record the value from the Connection string field.

Screenshot showing connection strings option.

Important

The connection string in the portal doesn't include the password value. You must replace the <password> placeholder with the credentials you entered when you created the cluster or enter the password interactively.

Configure MongoDB Shell in Azure Cloud Shell manually

Install the MongoDB Shell (mongosh) client to your Azure Cloud Shell instance using Node Package Manager (npm).

  1. Open the Azure Cloud Shell configured with a Bash scripting environment.

  2. Install version 1 of the MongoDB Shell locally in your user directory.

    npm install mongosh@1

  3. Wait for the installation to complete.

  4. Verify that the installation was successful by getting the version of the mongosh tool.

    npx mongosh --version

Connect to the cluster

Connect to your cluster by using the MongoDB Shell with a connection string that doesn't include a password. Use the interactive password prompt to enter your password as part of the connection steps.

  1. Connect by entering the password in the MongoDB Shell prompt. For this step, use a connection string without the password.

    npx mongosh "mongodb+srv://<username>@<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000"

  2. After you provide the password and are successfully authenticated, observe the warning that appears.

    ------
   Warning: Non-Genuine MongoDB Detected
   This server or service appears to be an emulation of MongoDB rather than an official MongoDB product.
------

    Tip

    You can safely ignore this warning. This warning is generated because the connection string contains cosmos.azure. Azure DocumentDB is a native Azure platform as a service (PaaS) offering.

Perform test queries

Verify that you're successfully connected to your cluster by performing a series of test commands and queries.

  1. Check your connection status by running the connectionStatus command.

    db.runCommand({connectionStatus: 1})

    {
  ...
  ok: 1
}

  2. List the databases in your cluster.

    show dbs

  3. Switch to a specific database. Replace the <database-name> placeholder with the name of any database in your cluster.

    use <database-name>

    Tip

    For example, if the database name is inventory, then the command would be use inventory.

  4. List the collections within the database.

    show collections

  5. Find the first five items within a specific collection. Replace the <collection-name> placeholder with the name of any collection in your cluster.

    db.<collection-name>.find().limit(5)

    Tip

    For example, if the collection name is equipment, then the command would be db.equipment.find().limit(5).

Related content

  • Last updated on