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
- MongoDB advises not to use this method to create backups of big deployments. MongoDB Documentation says:
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
andmongorestore
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"
Primary of the Cluster (recommended)
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
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>.*'
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>