# 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 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're 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 new cluster

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

Additionally you can't restore the users and roles via `mongorestore`. So you have to create all the users with their credentials and roles via the IONOS 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 [User Management](/cloud/~/revisions/AMiYziCllTKB2y2lmONY/databases/mongodb/api-howtos/users-management.md). You can't see the plain text password on your old cluster, so you need to collect them from wherever you stored them.

### Dump data from old cluster

{% hint style="danger" %}
**Caution:** The use of `--oplog` isn't possible because it requires elevated privileges on restoring. Therefore you need to make sure that no write operations happen during the dump. Otherwise you get an inconsistent dump.
{% endhint %}

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

```
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:

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ionos.com/cloud/~/revisions/AMiYziCllTKB2y2lmONY/databases/mongodb/api-howtos/migration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.