Last Updated October 2014

MongoDB is "an open-source document database, and the leading NoSQL database." It's an incredibly powerful database built for speed and scalability. Creating and using MongoDB databases on Pagoda Box is extremely simple. After reading this doc, you will be familiar with:

  • How to create a MongoDB database
  • How to connect to your database
  • Things to know when using MongoDB on Pagoda Box

MongoDB's Known Issues

While MongoDB is a very popular NoSQL database, it has shortcomings. By using MongoDB on Pagoda Box, you accept the following:

Pagoda Box is not liable for data-loss or downtime related to these known issues.

Creating a MongoDB Database

Creating a MongoDB database can be done either in your dashboard or from your Boxfile.

Through the Dashboard

To create a MongoDB database through your dashboard, click on "New Service," then click the MongoDB icon.

You're given the option to name your database and select which MongoDB version you'd like use. If no name is provided, we will create one for you. Click "Create Service" to begin provisioning your MongoDB database.

Through the Boxfile

To create a MongoDB database through the Boxfile, include a database service in your Boxfile with the type specified as "mongodb".

MongoDB Database in the Boxfile YAML

    type: mongodb

On your next deploy, the database will be created.

Configuring MongoDB

Configuration that would typically happen in mongod, mongos, or a mongo config file is done through the Boxfile. The MongoDB Settings in the Boxfile doc walks through the available configurable options.

Connecting to MongoDB

Connecting services in your application to a MongoDB database isn't any different on Pagoda Box than any other host. Each database has specified connection credentials used to connect your codebase to your database. You can get the credentials in the App Dashboard. Simply click on your database service and open the "Connection" tab.

There are two approaches to including connections credentials in your codebase – hard-coding the credentials or using automatically-generated environment variables.

Hard-Coding Credentials

You can hard-code your database connection credentials into your codebase and it will connect, but there are some drawbacks to this approach:

  1. Connection credentials are viewable in your repo - On Pagoda Box, this doesn't compromise the security of your database.

  2. You have to create your database before you can get the credentials - To hard-code your database credentials, you first need to know what they are and you can't do that until you create the database. This isn't a critical problem. It's more of a workflow issue.

Using Automated Environment Variables

Whenever you create a MongoDB database on Pagoda Box, we automatically generate environment variables for each connection credential:


Note: The service ID (DATABASE1) changes depending on which database you're connecting to.

Including environment variables in place of connection credentials in your codebase allows you to avoid storing the actual credentials in your repo and sets connection details before the database is even created. If you create a MongoDB database with the credential environment variables in place, app will automatically connect.

Check out the Environment Variables doc for more information.

Managing MongoDB

The best way to manage the data inside your MongoDB database is through the Pagoda CLI's "tunnel" command. The tunnel allows you to remotely connect to your MongoDB database and manage it using your local client of choice. Below is an example of opening a tunnel:

Opening a Tunnel to MongoDB Terminal

  $ pagoda tunnel database1 -p 27017

  Tunnel established, use the following credentials to connect:

  Host      : localhost
  Port      : 27017
  Username  : 
  Password  : 
  Database  : gopagoda

  (note : ctrl-c To close this tunnel)

With the tunnel open, you can connect to and manage your MongoDB database with a local client.

Making MongoDB Redundant

Data stored in your MongoDB database can be incredibly important and ideally will always be available. Adding redundancy to MongoDB is the best way to ensure your data is always available. To make MongoDB redundant, use the "redundant" topology when creating your database.

After your MongoDB service is created, the topology can be changed in your dashboard.

With the Redundant topology, a second MongoDB instance is provisioned with primary/secondary replication between the two instances. If the primary instance every fails or becomes unresponsive, the secondary instance will act as a hot failover and take over handling requests until the primary instance can be repaired and/or restarted.

Potential for Data Loss

There are known issues that can result in data loss when using a replicated MongoDB architecture. These issues exist within the MongoDB core. Pagoda Box is not liable for data lost in a MongoDB failover event and using a replicated MongoDB is done at your own risk.

Things to Know When Using MongoDB

MongoDB is Not Built for Live Migrations

Whenever you vertically scale MongoDB, an entirely new instance is provisioned in parallel to your currently running instance. With other databases, data can be migrated while the database still handles queries. MongoDB is not built to do this. Any time you vertically scale a MongoDB service, it will have to be shut down in order to migrate data and your app will not be able to connect to the database while the migration is taking place.

Restoring to a Snapshot Can Take Hours/Days

When restoring MongoDB to a previous data snapshot, the restore process can take hours and even days depending on the amount of records stored in your database. This is mainly due to how mongorestore insterts and indexes records in the import process. More information is available in this stackoverflow thread.

If you have any questions, suggestions, or corrections, let us know.