Connecting to the new MongoDB at Compose

So you've just spun up one of our new MongoDB deployments and you are ready to go. Before you do that though, we'd like to explain, especially for those of you who are upgrading from MongoDB Classic, the differences and strengths.

Creating your first database

When you get your MongoDB deployment, it has no databases created in it. Well, almost no databases - there is the admin database but we'll get back to that later so for now ignore it. So, like MongoDB Classic, the first thing you need to do is to create a database. That's done through the Browser menu option.

Creating your first database

That command line usually only appears when you click the Add Database button, but the system can see you've got no databases of your own so it makes the command line appear for you. Select the name field in the command line that appears and enter the name for your database – we've put in "examples" here – then click Create Database. Assuming all goes well, you'll arrive this screen displaying the collections, or more accurately the lack of collections, in your newly created database:

Created Database

Yes, you could create a collection here and carry on, but what we want to do is enable user log ons. For that, you need to click on the "view/add users" link or just click on Users in the menu to get the user screen.

No Users

Then click Add User to reveal the command line and enter a user name and password into the fields.

Add User Command Line

The only option here is readOnly to make a read-only user. On MongoDB Classic, there was an oplogAccess option, but that's been removed because there's a new way to access oplogs which we'll explain in the next article.

The users that you create here will be owners of this database and have no access to other databases in this deployment. With the ground prepared we can get to connecting.

Connecting to your first database

Now you have a database user, you can log in to that database. To do this, go to the Admin menu option where you'll see connection strings and command lines specifically for this database:

Database Admin View

Lets start with connecting on the command line. You should have SSL enabled so we'll assume that as we explain these connections strings:

mongo --ssl --sslAllowInvalidCertificates aws-us-east-1-portal.7.dblayer.com:10764/examples -u <user> -p<password>  

Now then, this assumes you have MongoDB installed locally and that you have a version with SSL enabled. If you have MongoDB installed locally but don't know if it is SSL enabled, run mongo --help and if there's no options beginning with --ssl then you need to get an SSL enabled version of MongoDB to run on your system. If you are using Windows or Linux, you can download the latest from the MongoDB downloads page.

If you are on Mac OS X, we recommend that you setup the Homebrew package manager, then run brew install mongodb --with-openssl which will compile and install the latest MongoDB with OpenSSL configured. Once you've done that, you're ready to run the command line... after you've put in the MongoDB username and password you previously added to the database.

And at this point you should be logged in to your first database.

Driving to your first database

Now we'll look at the Mongo URI which is what you'd ideally use with a driver or other tools. You'll find it above the Mongo Console command on the database's admin page. Here's our example:

mongodb://<user>:<password>@aws-us-east-1-portal.7.dblayer.com:10764,aws-us-east-1-portal.10.dblayer.com:10361/examples?ssl=true  

If you're new to MongoDB, this URI contains two hosts for failover and specifies the database name to connect to at the end (examples) followed by a parameter ?ssl=true to activate SSL.

If you're coming from MongoDB classic, this may look similar to a MongoDB Classic URI, but it is actually different. For example, there's no "replicaset" parameter because, although two hosts are listed, they are not two members of a replica set. With new MongoDB deployments, you have two Mongos/Haproxy routers to handle your requests. Where drivers can make use of it, this means that the driver and the routers can help manager failover for much better availability.

The only problem is that all drivers are not equal and some make assumptions when multiple hosts are specified. For example, the Meteor/Node.js MongoDB driver sees two hosts and assumes it is talking to a replicaset. Upon connecting the driver asks which host is master and then errors out because neither of them are. The simple fix for this is to use one host in the URI, so for the example URI above, it would become:

mongodb://<user>:<password>@aws-us-east-1-portal.7.dblayer.com:10764/examples?ssl=true  
mongodb://<user>:<password>@aws-us-east-1-portal.10.dblayer.com:10361/examples?ssl=true  

We look forward to drivers and frameworks which are more in sync with MongoDB's URI specification but until then, you have to rely on a single Mongos/Haproxy router.

For drivers where this isn't an issue – check your documentation and if it doesn't say, test – you'll get the benefits of two layers of high availability.

All about admin

With our new MongoDB deployments, we've opened up the administration controls so you can create MongoDB users with cross-database credentials. To do this, every MongoDB deployment now comes with an admin database already created and an admin user pre-installed. We use the default admin user as part of managing your database.

You can create more admin level users in the admin database as needed, but these should be rarely needed. To do this, select Browser and then select the Admin database. You will see that you can only create users in this view:

Admin Users

What is important to know is that when you go to the Deployment Overview, the overview and all the information displayed is for an administrator. Specifically, the command line entry is for connecting as an administrator.

Deployment View Connection Strings

The user and password here must be created in the admin database. Once logged in though, they will be able to access any other database.

What's that --sslAllowInvalidCertificates?

You spotted it. Yes, in the command lines that the Compose console shows, for simplicity it uses the --sslAllowInvalidCertificates flag. That's because Compose uses self-signed certificates for our servers and many tools and drivers have a problem with them. They assume there's a certificate authority that will vouch for the certificate and when there isn't, they declare the certificate invalid. So --sslAllowInvalidCertificates says to the mongo command "Do all the usual checking, but don't go looking for a CA to vouch for the certificate".

But what if you want to be sure that you are connecting to the server you want to connect to? For that you need to download the public key certificate of your deployment – not database, the certificate is deployment wide – and present that in the command. You'll find the certificate on the Deployment Overview page.

No Show SSL Public Key

Click the button and you'll be prompted for your Compose account password. Enter that and then the SSL Public Key will be displayed like so:

Show SSL Public Key

This text, all of it including the "-----BEGIN..." and "-----END CERTIFICATE-----" lines needs to be cut and pasted into a file on your local system. Let's assume you copy them to a file and save it as compose.cert.

Now all you need to do is replace --sslAllowInvalidCertificates with --sslCAFile compose.cert. The --sslCAFile takes a parameter which can be the full path and filename to whereever you have put that certificate file. Remember the command line to connect to the examples database:

mongo --ssl --sslAllowInvalidCertificates aws-us-east-1-portal.7.dblayer.com:10764/examples -u <user> -p<password>  

Well, that now becomes:

mongo --ssl --sslCAFile compose.cert aws-us-east-1-portal.7.dblayer.com:10764/examples -u <user> -p<password>  

That generally works for all the MongoDB command line tools when connecting to Compose deployments.

Moving On

In the next part of this short series, we'll look at why and how to connect to the MongoDB oplog with the new MongoDB deployments at Compose.