Azure Cosmos DB: Build a MongoDB API console app with Golang and the Azure portal

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 quick-start demonstrates how to use an existing MongoDB app written in Golang and connect it to your Azure Cosmos DB database, which supports MongoDB client connections by using the MongoDB API.

In other words, your Golang 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.


  • An Azure subscription. 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

  • Go and a basic knowledge of the Go language.

  • An IDE — GoLand by Jetbrains, Visual Studio Code by Microsoft, or Atom. In this tutorial, I'm using Goglang.

Create a database account

  1. In a new window, sign in to the Azure portal.
  2. In the left menu, click Create a resource, click Databases, and then under Azure Cosmos DB, click Create.

    Screen shot of the Azure portal, highlighting More Services, and Azure Cosmos DB

  3. In the New account blade, specify MongoDB as the API and fill out your desired configuration for the Azure Cosmos DB account.

    • ID must be a unique name you wish to use to identify your Azure Cosmos DB account. It may only contain lower case letters, numbers, the '-' character, and must be between 3 and 50 characters.
    • Subscription is your Azure subscription. It will be filled out for you.
    • Resource Group is the resource group name for your Azure Cosmos DB account. Select Create New, then enter a new resource-group name for your account. For simplicity, you can use the same name as your ID.
    • Location is the geographic location where your Azure Cosmos DB instance is located. Choose the location closest to your users.

      Then click Create.

      The new account page for Azure Cosmos DB

  4. The account creation takes a few minutes. Wait for the portal to display the Congratulations! Your Azure Cosmos DB account with MongoDB API is ready page.

    The Azure portal Notifications pane

Clone the sample application

Clone the sample application and install the required packages.

  1. Create a folder named CosmosDBSample inside the GOROOT\src folder, which is C:\Go\ by default.
  2. Run the following command using a git terminal window such as git bash to clone the sample repository into the CosmosDBSample folder.

    git clone
  3. Run the following command to get the mgo package.

    go get

The mgo driver is a MongoDB driver for the Go language that implements a rich and well tested selection of features under a very simple API following standard Go idioms.

Update your connection string

Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. Click Quick start in the left navigation menu, and then click Other to view the connection string information required by the Go application.

  2. In Goglang, open the main.go file in the GOROOT\CosmosDBSample directory and update the following lines of code using the connection string information from the Azure portal as shown in the following screenshot.

    The Database name is the prefix of the Host value in the Azure portal connection string pane. For the account shown in the image below, the Database name is golang-coach.

    Database: "The prefix of the Host value in the Azure portal",
    Username: "The Username in the Azure portal",
    Password: "The Password in the Azure portal",

    Quick start pane, Other tab in the Azure portal showing the connection string information

  3. Save the main.go file.

Review the code

This step is optional. If you're interested in learning how the database resources are created in the code, you can review the following snippets. Otherwise, you can skip ahead to Run the app.

The following snippets are all taken from the main.go file.

Connecting the Go app to Azure Cosmos DB

Azure Cosmos DB supports the SSL-enabled MongoDB. To connect to an SSL-enabled MongoDB, you need to define the DialServer function in mgo.DialInfo, and make use of the tls.Dial function to perform the connection.

The following Golang code snippet connects the Go app with Azure Cosmos DB MongoDB API. The DialInfo class holds options for establishing a session with a MongoDB cluster.

// DialInfo holds options for establishing a session with a MongoDB cluster.
dialInfo := &mgo.DialInfo{
    Addrs:    []string{""}, // Get HOST + PORT
    Timeout:  60 * time.Second,
    Database: "database", // It can be anything
    Username: "username", // Username
    Password: "Azure database connect password from Azure Portal", // PASSWORD
    DialServer: func(addr *mgo.ServerAddr) (net.Conn, error) {
        return tls.Dial("tcp", addr.String(), &tls.Config{})

// Create a session which maintains a pool of socket connections
// to our Azure Cosmos DB MongoDB database.
session, err := mgo.DialWithInfo(dialInfo)

if err != nil {
    fmt.Printf("Can't connect to mongo, go error %v\n", err)

defer session.Close()

// SetSafe changes the session safety mode.
// If the safe parameter is nil, the session is put in unsafe mode, 
// and writes become fire-and-forget,
// without error checking. The unsafe mode is faster since operations won't hold on waiting for a confirmation.

The mgo.Dial() method is used when there is no SSL connection. For an SSL connection, the mgo.DialWithInfo() method is required.

An instance of the DialWIthInfo{} object is used to create the session object. Once the session is established, you can access the collection by using the following code snippet:

collection := session.DB("database").C("package")

Create a document

// Model
type Package struct {
    Id bson.ObjectId  `bson:"_id,omitempty"`
    FullName      string
    Description   string
    StarsCount    int
    ForksCount    int
    LastUpdatedBy string

// insert Document in collection
err = collection.Insert(&Package{
    Description:"A framework for building native apps with React.",
    ForksCount: 11392,


if err != nil {
    log.Fatal("Problem inserting data: ", err)

Query or read a document

Azure Cosmos DB supports rich queries against JSON documents stored in each collection. The following sample code shows a query that you can run against the documents in your collection.

// Get a Document from the collection
result := Package{}
err = collection.Find(bson.M{"fullname": "react"}).One(&result)
if err != nil {
    log.Fatal("Error finding record: ", err)

fmt.Println("Description:", result.Description)

Update a document

// Update a document
updateQuery := bson.M{"_id": result.Id}
change := bson.M{"$set": bson.M{"fullname": "react-native"}}
err = collection.Update(updateQuery, change)
if err != nil {
    log.Fatal("Error updating record: ", err)

Delete a document

Azure Cosmos DB supports deleting JSON documents.

// Delete a document
query := bson.M{"_id": result.Id}
err = collection.Remove(query)
if err != nil {
   log.Fatal("Error deleting record: ", err)

Run the app

  1. In Goglang, ensure that your GOPATH (available under File, Settings, Go, GOPATH) include the location in which the gopkg was installed, which is USERPROFILE\go by default.
  2. Comment out the lines that delete the document, lines 103-107, so that you can see the document after running the app.
  3. In Goglang, click Run, and then click Run 'Build main.go and run'.

    The app finishes and displays the description of the document created in Create a document.

    Description: A framework for building native apps with React.
    Process finished with exit code 0

    Goglang showing the output of the app

Review your document in Data Explorer

Go back to the Azure portal to see your document in Data Explorer.

  1. Click Data Explorer (Preview) in the left navigation menu, expand golang-coach, package, and then click Documents. In the Documents tab, click the _id to display the document in the right pane.

    Data Explorer showing the newly created document

  2. You can then work with the document inline and click Update to save it. You can also delete the document, or create new documents or queries.

Review SLAs in the Azure portal

The throughput, storage, availability, latency, and consistency of the resources in your account are monitored in the Azure portal. Let's take a quick look at these metrics.

  1. Click Metrics in the navigation menu.

    Metrics in the Azure portal

  2. Click through each of the tabs so you're aware of the metrics Azure Cosmos DB provides.

    Each chart that's associated with the Azure Cosmos DB Service Level Agreements (SLAs) provides a line that shows if any of the SLAs have been violated. Azure Cosmos DB makes monitoring your SLAs transparent with this suite of metrics.

    Azure Cosmos DB metrics suite

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 run a Golang app using the API for MongoDB. You can now import additional data to your Cosmos DB account.