# 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 <code class="expression">space.vars.ionos\_cloud</code> MongoDB cluster.

This migration requires some downtime, as you must 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 must 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 must create all the users with their credentials and roles via the <code class="expression">space.vars.ionos\_cloud</code> 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>](/cloud/databases/mongodb/api/v1-api/users-management.md). You cannot see the plain-text passwords on your old cluster, so you must retrieve them from wherever you stored them.

## Dump data from old cluster

{% hint style="danger" %}
**Caution:** You cannot use `--oplog` because it requires elevated privileges on restoring. Therefore, you must 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 <code class="expression">space.vars.ionos\_cloud</code> MongoDB cluster. You must use the <code class="expression">space.vars.ionos\_cloud</code> 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/databases/mongodb/api/v1-api/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.