Skip to main content
Version: Develop

Creating Local Copy of the Data

This document describes how to discover who is the primary of an a9s MongoDB service instance and how to create and restore a dump of this service instance.

All a9s MongoDB versions support the following guide.

Dependencies​

First, you will need to install the MongoDB tools. You can check the official MongoDB documentation on how to install it: https://docs.mongodb.com/manual/installation.

  • mongo: The MongoDB shell for version 5.0.
  • mongosh: The MongoDB shell for version 7.0.
  • mongodump: The MongoDB client to create dumps of the service.
  • mongorestore: The MongoDB client to restore dumps to a service.

Warnings​

Known Issues​

The mongodump and mongorestore utilities work with BSON data dumps, and are useful for creating backups of
small deployments. For resilient and non-disruptive backups, use a file system or block-level disk snapshot
function, such as the methods described in the MongoDB Backup Methods document.
  • MongoDB also advises to not use mongodump and mongorestore to backup and restore sharded clusters. MongoDB Documentation says:
mongodump and mongorestore cannot be part of a backup strategy for 4.2+ sharded clusters that have sharded
transactions in progress, as backups created with mongodump do not maintain the atomicity guarantees of
transactions across shards.

Stop Connections During the Backup and Restoration​

Any existing open connection to MongoDB MUST be killed and any new connections to MongoDB MUST be avoided during the backup and restore process using mongodump and mongorestore.

Downtime During the Migration​

During the migration, the MongoDB MUST not have any open connection all along with the backup creation and restoration period, hence MongoDB will have downtime during this time.

Create a Service Key​

You will need to access the MongoDB instance, to be able to do it, you will need credentials. You can either use the credentials used by the application bound to the service with cf env <app> or create a new service key with cf create-service-key <service-name> <key-name>, in this case, you can check the service key with cf service-key <service-name> <key-name>.

You will need to know the uri and the default_database to use on the next steps.

If you have access to the service instance directly, use the credentials from the key or the credentials from the app environment. The examples below use localhost, assuming that it is not possible to access the service instance directly.

Create an SSH Tunnel​

If it is not possible to access the service instance directly, you can create a tunnel to your app using cf ssh, and access the service using this tunnel.

For this step, you will need an app that is bound to the service instance. After pushing the app and binding it to the service, check the credentials, and tunnel the connection to any node belonging to the service instance.

cf ssh <app-name> -L 27017:<a9s-mongodb-host>:27017

Example:

cf ssh bindingo -L 27017:mod57756-mongodb-0.node.dc1.a9ssvc:27017

If you can access the service instance directly, you can use the Service host to connect and skip the SSH tunnel creation.

Access the MongoDB Service​

You can access the MongoDB service directly with:

a9s MongoDB 5.0
# When the Service Instance is SSL, use `--ssl` `--sslCAFile <your-ca-file-path>`.
mongo "mongodb://<username>:<password>@localhost:27017/<default_database>"
a9s MongoDB 7.0
# When the Service Instance is SSL, use `--tls` `--tlsCAFile <your-ca-file-path>`.
mongosh "mongodb://<username>:<password>@localhost:27017/<default_database>"

Since you are tunneling the connection from your local machine to the service instance, use localhost instead of the host given in the credentials.

Example:

a9s MongoDB 5.0
# When the Service Instance is SSL, use `--ssl` `--sslCAFile <your-ca-file-path>`.
mongo "mongodb://a9s-brk-usr-715a028ce02165651096e011d5e02b1d0b392d26:a9se7970e2a142a958a93fddd14e2be6a156b03b757@localhost:27017/mod57756"
a9s MongoDB 7.0
# When the Service Instance is SSL, use `--tls` `--tlsCAFile <your-ca-file-path>`.
mongosh "mongodb://a9s-brk-usr-715a028ce02165651096e011d5e02b1d0b392d26:a9se7970e2a142a958a93fddd14e2be6a156b03b757@localhost:27017/mod57756"

As long as your cluster (if using a cluster) is healthy, it should be ok to take a copy of any of the nodes, since replication is in place they should have the same view of the data. However, we suggest creating a copy from the primary node.

To discover the primary node of the Service, access the a9s MongoDB instance and execute the following command on any node of the cluster:

rs0:<role>> rs.isMaster()

Check for the field "primary" and use the address in this field to create the tunnel, as mentioned above.

Create a MongoDB Dump​

The command below will take a copy of the specified database to your local machine using the tunnel created above: Use the credentials from cf env or from the generated service key (cf service-key <service-name> <key-name>)

mongodump --uri="mongodb://<username>:<password>@localhost:27017/<default_database>" \
--gzip --archive=<dump-file>.gz
note

When creating a dump meant to be restored on an a9s MongoDB 7.0 Service Instance, ensure the use of the SCRAM-SHA-256 authentication mechanism by including the following flag: --authenticationMechanism=SCRAM-SHA-256.

Example:

mongodump --uri="mongodb://a9s-brk-usr-a4471fa5b387767b7208edbaafda64d97b52bb91:a9s6718f1c870161b852a2b096458008f95e3a2d31e@localhost:27017/mod3ce8d" \
--gzip --archive=/tmp/mydump.gz

If this is an SSL instance, remember to add the SSL options:

mongodump --uri="mongodb://<username>:<password>@localhost:27017/<default_database>" --ssl \
--sslCAFile=<your-ca-file-path> --gzip --archive=<dump-file>.gz

Restore a MongoDB Dump​

When restoring your local copy (dump file) to a new MongoDB service, you can use the mongorestore command as follows:

mongorestore --uri="mongodb://<username>:<password>@localhost:27017/<default_database>" \
--gzip --archive=<output-file>.gz --nsInclude='<original-default_database>.*' --nsFrom='<original-default_database>.*' --nsTo='<default_database>.*'
note

When restoring a dump on an a9s MongoDB 7.0 Service Instance, ensure the use of the SCRAM-SHA-256 authentication mechanism by including the following flag: --authenticationMechanism=SCRAM-SHA-256.

Example:

mongorestore --uri="mongodb://a9s-brk-usr-733e61a812ea27627f991d91f4a6b48db5631294:a9se1d35f1466318718cb508be4856d33631fd8c4b9@localhost:27018/mod94cfad" \
--gzip --archive=/tmp/mydump.gz --nsInclude='mod3ce8d.*' --nsFrom='mod3ce8d.*' --nsTo='mod94cfad.*'

If this is an SSL instance, remember to add the SSL options:

mongorestore --uri="mongodb://<username>:<password>@localhost:27017/<db-name>" \
--gzip --archive=<output-file>.gz --nsInclude='<original-default_database>.*' --nsFrom='<original-default_database>.*' \
--nsTo='<default_database>.*' --ssl --sslCAFile=<your-ca-file-path>