Azure Cosmos DB: Migrate an existing Node.js MongoDB web app

Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

This quickstart demonstrates how to use an existing MongoDB app written in Node.js and connect it to your Azure Cosmos DB database, which supports MongoDB client connections by using the MongoDB API. In other words, your Node.js application only knows that it's connecting to a database using MongoDB APIs. It is transparent to the application that the data is stored in Azure Cosmos DB.

When you are done, you will have a MEAN application (MongoDB, Express, Angular, and Node.js) running on Azure Cosmos DB.

MEAN.js app running in Azure App Service

Open Azure Cloud Shell

Azure Cloud Shell is a free, interactive shell that you can use to run the steps in this article. Common Azure tools are preinstalled and configured in Cloud Shell for you to use with your account. Just select the Copy button to copy the code, paste it in Cloud Shell, and then press Enter to run it. There are a few ways to open Cloud Shell:

Select Try It in the upper-right corner of a code block. Cloud Shell in this article
Open Cloud Shell in your browser.
Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal. Cloud Shell in the portal

If you choose to install and use the CLI locally, this topic requires that you are running the Azure CLI version 2.0 or later. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.


If you don't have an Azure subscription, create a free account before you begin.

Alternatively, you can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. Or you can use the Azure Cosmos DB Emulator for this tutorial with a connection string of


In addition to Azure CLI, you need Node.js and Git installed locally to run npm and git commands.

You should have working knowledge of Node.js. This quickstart is not intended to help you with developing Node.js applications in general.

Clone the sample application

Run the following commands to clone the sample repository. This sample repository contains the default MEAN.js application.

  1. Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
  2. Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
  3. Run the following command to clone the sample repository. This command creates a copy of the sample app on your computer.

    git clone

Run the application

Install the required packages and start the application.

cd mean
npm install
npm start

The application will try to connect to a MongoDB source and fail, go ahead and exit the application when the output returns "[MongoError: connect ECONNREFUSED]".

Log in to Azure

If you are using an installed Azure CLI, log in to your Azure subscription with the az login command and follow the on-screen directions. You can skip this step if you're using the Azure Cloud Shell.

az login 

Add the Azure Cosmos DB module

If you are using an installed Azure CLI, check to see if the cosmosdb component is already installed by running the az command. If cosmosdb is in the list of base commands, proceed to the next command. You can skip this step if you're using the Azure Cloud Shell.

If cosmosdb is not in the list of base commands, reinstall Azure CLI.

Create a resource group

Create a resource group with the az group create. An Azure resource group is a logical container into which Azure resources like web apps, databases and storage accounts are deployed and managed.

The following example creates a resource group in the West Europe region. Choose a unique name for the resource group.

If you are using Azure Cloud Shell, click Try It, follow the onscreen prompts to login, then copy the command into the command prompt.

az group create --name myResourceGroup --location "West Europe"

Create an Azure Cosmos DB account

Create an Azure Cosmos DB account with the az cosmosdb create command.

In the following command, please substitute your own unique Azure Cosmos DB account name where you see the <cosmosdb-name> placeholder. This unique name will be used as part of your Azure Cosmos DB endpoint (https://<cosmosdb-name>, so the name needs to be unique across all Azure Cosmos DB accounts in Azure.

az cosmosdb create --name <cosmosdb-name> --resource-group myResourceGroup --kind MongoDB

The --kind MongoDB parameter enables MongoDB client connections.

When the Azure Cosmos DB account is created, the Azure CLI shows information similar to the following example.


This example uses JSON as the Azure CLI output format, which is the default. To use another output format, see Output formats for Azure CLI commands.

  "databaseAccountOfferType": "Standard",
  "documentEndpoint": "https://<cosmosdb-name>",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Document
  "kind": "MongoDB",
  "location": "West Europe",
  "name": "<cosmosdb-name>",
  "readLocations": [
      "documentEndpoint": "https://<cosmosdb-name>",
      "failoverPriority": 0,
      "id": "<cosmosdb-name>-westeurope",
      "locationName": "West Europe",
      "provisioningState": "Succeeded"
  "resourceGroup": "myResourceGroup",
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "writeLocations": [
      "documentEndpoint": "https://<cosmosdb-name>",
      "failoverPriority": 0,
      "id": "<cosmosdb-name>-westeurope",
      "locationName": "West Europe",
      "provisioningState": "Succeeded"

Connect your Node.js application to the database

In this step, you connect your MEAN.js sample application to an Azure Cosmos DB database you just created, using a MongoDB connection string.

Configure the connection string in your Node.js application

In your MEAN.js repository, open config/env/local-development.js.

Replace the content of this file with the following code. Be sure to also replace the two <cosmosdb-name> placeholders with your Azure Cosmos DB account name.

'use strict';

module.exports = {
  db: {
    uri: 'mongodb://<cosmosdb-name>:<primary_master_key>@<cosmosdb-name>'

Retrieve the key

In order to connect to an Azure Cosmos DB database, you need the database key. Use the az cosmosdb list-keys command to retrieve the primary key.

az cosmosdb list-keys --name <cosmosdb-name> --resource-group myResourceGroup --query "primaryMasterKey"

The Azure CLI outputs information similar to the following example.


Copy the value of primaryMasterKey. Paste this over the <primary_master_key> in local-development.js.

Save your changes.

Run the application again.

Run npm start again.

npm start

A console message should now tell you that the development environment is up and running.

Navigate to http://localhost:3000 in a browser. Click Sign Up in the top menu and try to create two dummy users.

The MEAN.js sample application stores user data in the database. If you are successful and MEAN.js automatically signs into the created user, then your Azure Cosmos DB connection is working.

MEAN.js connects successfully to MongoDB

View data in Data Explorer

Data stored by an Azure Cosmos DB is available to view, query, and run business-logic on in the Azure portal.

To view, query, and work with the user data created in the previous step, login to the Azure portal in your web browser.

In the top Search box, type Azure Cosmos DB. When your Cosmos DB account blade opens, select your Cosmos DB account. In the left navigation, click Data Explorer. Expand your collection in the Collections pane, and then you can view the documents in the collection, query the data, and even create and run stored procedures, triggers, and UDFs.

Data Explorer in the Azure portal

Deploy the Node.js application to Azure

In this step, you deploy your MongoDB-connected Node.js application to Azure Cosmos DB.

You may have noticed that the configuration file that you changed earlier is for the development environment (/config/env/local-development.js). When you deploy your application to App Service, it will run in the production environment by default. So now, you need to make the same change to the respective configuration file.

In your MEAN.js repository, open config/env/production.js.

In the db object, replace the value of uri as show in the following example. Be sure to replace the placeholders as before.



The ssl=true option is important because Azure Cosmos DB requires SSL.

In the terminal, commit all your changes into Git. You can copy both commands to run them together.

git add .
git commit -m "configured MongoDB connection string"

Clean up resources

If you're not going to continue to use this app, delete all resources created by this quickstart with the following steps so you don't incur any charges:

  1. In the Azure portal, select Resource groups on the far left, and then select the resource group you created.

    If the left menu is collapsed, click Expand button to expand it.

    Metrics in the Azure portal

  2. In the new window select the resource group, and then click Delete resource group.

    Metrics in the Azure portal

  3. In the new window, type the name of the resource group to delete, and then click Delete.

Next steps

In this quickstart, you've learned how to create an Azure Cosmos DB account and create a MongoDB collection using the Data Explorer. You can now migrate your MongoDB data to Azure Cosmos DB.