Docs Menu
Docs Home
/
MongoDB Cluster-to-Cluster Sync
/
Reference
/
Beta Program

Namespace Remapping

On this page

  • Syntax
  • Parameter Fields
  • Behavior
  • Valid Namespace Remapping
  • Steps
  • Connect the source and destination clusters
  • Sync the clusters with namespace remapping
  • 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.

Steps

1

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"
2

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

Back

Pre-Existing Data Handling

Next

Oplog Rollover Resilience