Connecting to MongoDB

Connection Types and Security

Connections to MongoDB on Compose are available with, and without, TLS/SSL enabled. This is set on a deployment-wide basis and, for your own and your clients security, we recommend you run your deployments with TLS/SSL enabled.

Language Guides

If you want to use a particular language, you can go directly to its dedicated page:

• Go
• Javascript
• Ruby
• Python

Connection Overview and Credentials

In the Deployment Overview there is a Connection Info section to get you and your application connected to the deployment.

For drivers that support it, there is a connection string that combines both HAProxy portals so that failover is automatic if one portal is not available.

If the driver you are using does not support the combined connection string, use the single-portal connection strings. In this case, if one portal is not available you will want to have your application handle connecting to the other portal.

Connection String Parameters

• /compose: the default database for connections to your deployment. If you would like to connect to a different database upon connecting, change this to the database name you would like to connect to.
• ?authSource=admin: tells MongoDB where the user credentials are stored to authenticate against.
• &ssl=true: Only present on deployments that have ssl-enabled at provision, it is necessary to connect to those deployments.

Credentials

Users and authentication are handled by the admin database. After you have created users and granted them access to your deployment, tell MongoDB to authenticate your users through the admin database with the ?authSource=admin parameter sent in on your connection string.

Command-line Interface

To connect and communicate with your MongoDB deployment via command-line use the mongo shell. It comes packaged with MongoDB distribution, so install the package that is appropriate for your platform.

Once you have the mongo shell, use the connection string provided in the Command line section of the Deployment Overview. If you have TLS/SSL-enabled deployment and a TLS/SSL-enabled Mongo Shell installed, make sure to run the mongo command with the --ssl flag.

📘

TLS/SSL-enabled Packages

If you are using a TLS/SSL enabled deployment, you need to make sure that you also install an ssl-enabled MongoDB package. Current downloads for Windows and Linux MongoDB include TLS/SSL support. For Mac OS X, TLS/SSL is not compiled in by default, and you will need to install it with TLS/SSL. For example, using Homebrew on OSX brew install mongodb --with-openssl

Versions

The most recent version of MongoDB and it's command-line shell is different from the current version running on Compose, and will throw a warning when establishing a connection to a Compose deployment. To avoid this warning, you can install the version of MongoDB locally that matches the version of your Compose deployment.

Self-signed Certificates

Most deployments will have Let's Encrypt certificates installed and will not need any additional configuration to connect. However, some deployments have self-signed certificates. For those deployments you will see an additional field in the Deployment Overview titled SSL Certificate (Self-Signed).

Self-signed certificates and mongo shell

To connect the mongo shell with a self-signed certificate, use one of the two required flags that go with it: --sslAllowInvalidCertificates or --sslCAFile. The --sslAllowInvalidCertificates flag is simplest to use, as it tells the SSL to not verify the certificates being used to encrypt the connection:

$ mongo -ssl -sslAllowInvalidCertificates aws-us-east-1-portal.25.dblayer.com:25264/compose -u [username] -p [password] --authenticationDatabase admin

For the --sslCAFile option, we need to have the SSL certificate file for the server, and then supply it to the connection string for verification. The certificate is under the Connection info on your deployment. Save the certificate locally and supply the path to the mongo command:

$ mongo -ssl -sslCAFile /path/to/example.pem aws-us-east-1-portal.25.dblayer.com:25264/compose -u [username] -p [password] --authenticationDatabase admin

Still Need Help?

If this article didn't solve things, summon a human and get some help!