Namespace Remapping

On this page

Syntax

Parameter Fields
Behavior
Steps
Learn More

Important

Cluster-to-Cluster Sync Beta Program

This feature is only available in mongosync beta. To learn more, see Cluster-to-Cluster Sync Beta Program.

Starting in mongosync beta 1.8, you can remap database names during sync. This allows you to take data in one database on the source cluster and migrate it into a different database on the destination cluster.

To use namespace remapping, both the source cluster and destination cluster must use supported MongoDB version.

Syntax

The /start API endpoint accepts an optional namespaceRemap parameter with the following syntax:

curl <host>:<port>/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1"
      "namespaceRemap": [
         {
            "from": {
               "database": "<source-database>"
            },
            "to": {
               "database": "<destination-database>"
            }
         }
      ]
   } '

Parameter Fields

Field	Type	Required	Description
`namespaceRemap`	array	Optional	Array of documents that specify namespace changes to make during sync. New in version 1.8: Beta
`namespaceRemap[n].` `from`	document	Required	Document that specifies the database on the source cluster to migrate from in the remapping operation. New in version 1.8: Beta
`namespaceRemap[n].` `from.database`	string	Required	Database to migrate from on the source cluster. New in version 1.8: Beta
`namespaceRemap[n].` `to`	document	Required	Document that specifies the database on the destination cluster to migrate to in the remapping operation. New in version 1.8: Beta
`namespaceRemap[n].` `to.database`	string	Required	Database to migrate to on the destination cluster. New in version 1.8: Beta

Behavior

Valid Namespace Remapping

The following restrictions apply to namespace remapping:

Namespace remapping doesn't permit writing to the system, config, admin, or local databases, or writing to internal databases used by mongosync.
The database name on the destination cluster must be valid under Windows restrictions.
For more information, see Restrictions on Database Names for Windows.
Remapped database names on the destination cluster cannot differ only in case.
You can't specify a namespace remap and set the reversible flag to true.
The remap cannot produce namespace conflicts on the destination cluster.
For example:
```
"namespaceRemap": [
  {
     "from": { "database": "us-west" },
     "to": {"database": "us-accounts" }
  },
  {
     "from": { "database": "us-south" },
     "to": { "database": "us-accounts" }
  }
]
```
If each database on the source cluster contains a texas collection, mongosync may fail, corrupt data, or exhibit unexpected behavior.

Verification

Namespace Remapping is not compatible with the Embedded Verifier. The /start command returns an error if you enable both the verifier and Namespace Remapping.

For more information, see Verify Data Transfer.

Steps

Connect the source and destination clusters

The following example connects a source cluster (cluster0) with a destination cluster (cluster1):

mongosync \
   --cluster0 "mongodb://localhost:27000" \
   --cluster1 "mongodb://localhost:35000"

Sync the clusters with namespace remapping

The following /start call starts sync and remaps the accounts database on the source cluster to sales database on the destination cluster:

curl -X POST "http://localhost:27182/api/v1/start" --data '
   {
      "source": "cluster0",
      "destination": "cluster1",
      "namespaceRemap": [
        {
           "from": {
              "database": "accounts",
           },
           "to": {
              "database": "sales",
           }
        }
      ]
   } '

Example response:

{"success":true}

Learn More

/start

Back

Pre-Existing Data Handling

Oplog Rollover Resilience