# Database Migration

This How-to shows you how to migrate your MongoDB data from one cluster to another one. For example how to migrate from your existing on-premise MongoDB cluster to the IONOS Cloud MongoDB cluster.

This migration requires some downtime, as you need to stop write operations to your old cluster during dumping the data.

## High level plan

The steps for a migration are as follows:

1\. Preparations 2. Stop writes to old cluster - start of downtime 3. Dump data from old cluster using `mongodump` 4. Optionally: copy dump 5. Restore data into new cluster using `mongorestore` 6. Use the new cluster - end of downtime

## Preparations

### A place to run `mongodump` and `mongorestore`

You need one machine that can access the old cluster, that can run `mongodump`, and one machine that can access the new cluster, that can run `mongorestore`.

Both can happen on the same machine. If they are on two different machines, you need a way to copy the data dump from one machine to the other.

### Check MongoDB version

Both clusters need to be running the same major version. You can see the version in the greeting if you connect with `mongosh` or you can query it with `db.version()`.

### Access to old cluster

If your old cluster has access control enabled, you need a user with permissions for `find` to all databases. Easiest is to grant the `backup` role to the user that you want to use for dumping the data.

You can then verify that you can connect by using the command for `mongodump` mentioned in the section "Dump old data" and then aborting the dump with Ctrl-C.

### User in a new cluster

You need one user with write permissions to all databases that your dump contains.

Additionally, you cannot restore the users and roles via `mongorestore`. So you have to create all the users with their credentials and roles via the IONOS Cloud API. You can list all the users and roles in your old cluster with `db.system.users.find()` in the `admin` database and can then create them in the new cluster according to the documentation on [<mark style="color:blue;">User Management</mark>](https://docs.ionos.com/sections-test/guides/databases/mongodb/api/v1-api/users-management). You cannot see the plain-text passwords on your old cluster, so you need to retrieve them from wherever you stored them.

## Dump data from old cluster

{% hint style="danger" %}
**Caution:** The use of `--oplog` is not possible because it requires elevated privileges on restoring. Therefore, you need to ensure that no write operations occur during the dump. Otherwise, you get an inconsistent dump.
{% endhint %}

You can dump the data from the old cluster with this command:

```bash
mongodump --host="hostname:port" \
  --username="username" --password="password" \
  --authenticationDatabase "admin" \
  --gzip --archive=mongodb.dump
```

Optionally you can limit data using `--db`, `--collection`, or `--query` flags to only dump specific databases, collections, or documents.

## Restore data in new cluster

You can restore the dumped date in the new cluster with this command:

```bash
mongorestore --uri "mongodb+srv://username:password@cluster1.example.mongodb.net" \
  --gzip --archive=mongodb.dump \
  --nsExclude "admin.system.*"
```

The `admin.system.*` resources are excluded, since you cannot modify users and roles from inside MongoDB in an IONOS Cloud MongoDB cluster. You need to use the IONOS Cloud API for them.