Docs Menu

Docs Home → MongoDB Cluster-to-Cluster Sync

mongosync Versioning

On this page

  • Currently Supported Versions
  • MongoDB Server Version Compatibility and Support
  • Synchronize Data Between Clusters Running Older MongoDB Server Versions
  • Synchronize Data Between Clusters with Different MongoDB Server Major Versions
  • Version-Related Considerations
  • Support Lifecycle
  • Patch Releases
  • Live Upgrade
  • Non-Live Upgrade or Downgrade
  • Persistent Metadata
  • Log Messages
  • Examples
  • Major Releases
  • Minor Releases
  • Patch Releases

Cluster-to-Cluster Sync uses Semantic Versioning 2.0.0. Version numbers have the form X.Y.Z, where X is the major version, Y is the minor version, and Z is the patch version.

MongoDB uses the following guidelines to determine when to increment the version number for Cluster-to-Cluster Sync:

  • Major number: The release breaks backwards compatibility.

  • Minor number: The release includes significant new features that are backwards compatible.

  • Patch number: This release only includes small, backwards compatible changes.

Currently Supported Versions

If you are using an unsupported version of mongosync, you may be asked to upgrade in order to receive support.

MongoDB Server Version Compatibility and Support

Before you run Cluster-to-Cluster Sync, consider the following MongoDB server version limitations and requirements:

  • The minimum supported server versions of MongoDB are 6.0.8 and 7.0.0.

  • mongosync doesn't support MongoDB rapid releases, such as 6.1 or 6.2.

  • The minimum supported server feature compatibility version is 6.0.

Synchronize Data Between Clusters Running Older MongoDB Server Versions

Starting in version 1.2, mongosync can sync between clusters running some older (pre-6.0) releases of MongoDB Server. This feature requires additional preparation and configuration in pre-6.0 releases.

If you would like to migrate pre-6.0 versions of MongoDB Server using mongosync, please contact your account team to inquire about Professional Services.

Synchronize Data Between Clusters with Different MongoDB Server Major Versions

Starting in 1.7.0, mongosync can perform a cross-version migration from a lower major version source cluster to a higher major version destination cluster. You can migrate up to two major versions ahead. For example, you can synchronize a cluster running MongoDB 6.0 with a cluster running 7.0.

Cross-version migration requires additional preparation and configuration when migrating from a pre-6.0 release. To perform a cross-version migration from a pre-6.0 version of the MongoDB Server using mongosync, please contact your account team to inquire about Professional Services.

Version-Related Considerations

Cluster-to-Cluster Sync has the following version related considerations:

Support Lifecycle

  • Major releases are supported for at least one year from the first release in that series.

  • If a version of Cluster-to-Cluster Sync only works with an unsupported version of MongoDB Server, that version of Cluster-to-Cluster Sync is also unsupported.

Patch Releases

Only the latest version in each major release series receives new patch releases. For example, when version Cluster-to-Cluster Sync 2.1.0 is released, version 2.0 would no longer receive patch releases. At the same time, version 1.3 would continue to receive patches until version 1.4 was released.

Live Upgrade

New in version 1.7.0.

Starting in mongosync 1.7.0, you can upgrade mongosync without restarting data synchronization operations from the beginning. You can only live upgrade from mongosync 1.6.0 or later to mongosync 1.7.0 or later.

After the live upgrade, mongosync continues operations that were in progress before the upgrade.

To live upgrade mongosync, perform these steps:

1

(Optional) Pause the mongosync processes

To pause mongosync, run pause on each running mongosync process.

You can resume the mongosync processes later from the paused state, as shown in the final step.

Tip

If you don't want to immediately resume data synchronization operations after live upgrade, consider pausing the mongosync processes. This is useful if you're coordinating operations from multiple mongosync processes.

2

Stop the mongosync processes

Use your operating system to stop each running mongosync process. To stop a process, see your operating system documentation for the specific steps.

3

Download and install the new mongosync binaries

To download and install the new mongosync binaries, see download and install mongosync.

4

Initialize the mongosync processes

To initialize the mongosync processes, see the mongosync examples. During initialization after a live upgrade, mongosync updates the persistent metadata.

5

Resume the mongosync processes

If you paused any mongosync processes earlier in the optional first step, run resume on all mongosync processes.

If a data synchronization operation was already in progress before the live upgrade, new features added in the latest mongosync version may not all be supported after the live upgrade. Performance improvements and bug fixes are always supported after the live upgrade. For more information on the new features that might be supported after a live upgrade, see the 1.7.0 Release.

Non-Live Upgrade or Downgrade

If you're using an earlier mongosync version not supported by the live upgrade procedure, or you need to downgrade mongosync, perform these steps:

  • Stop all currently running mongosync processes.

  • Drop all non-system databases in the destination cluster.

  • Install new mongosync binaries.

  • Start the mongosync processes using the new binaries.

Warning

The new mongosync processes do not resume any work that may have been in progress. Syncing operations restart from the beginning when you start the new processes.

Persistent Metadata

During normal operation, mongosync creates metadata that is persisted to disk in the destination database. This metadata is not versioned and may change at any time.

Log Messages

Log message formats are not versioned and may change at any time. This includes changes to the message text, as well as the presence, absence, or contents of other fields in the message.

User scripts and applications should not rely on logging output. Scripts and applications should use the monitoring API to determine the current state of mongosync.

Examples

The following examples illustrate the kinds of changes that would result in each type of version number update.

Major Releases

  • Changes that make the new and old versions of mongosync produce different results on the destination cluster for the same set of inputs. Except:

    • Bug fixes for cases where the older version of mongosync fails to replicate data.

    • When the earlier behavior is explicitly documented as unsupported.

  • Changes to documented CLI parameters or configuration keys such that mongosync rejects formerly valid input. Except:

    • Bug fixes such as parsing or type errors.

    • Even though CLI parameters or configuration keys may be deprecated, the meaning of documented CLI parameters or configuration keys will never change. If needed, new parameters or keys will replace the older, deprecated entities.

  • Changes that break compatibility with a supported version of MongoDB Server.

  • Dropping a version of the REST API. mongosync may drop all older endpoints in favor of a new version of the API. There will never be any other types of backwards incompatible changes in the REST API.

  • Removing support for a previously supported MongoDB Server feature if mongosync still supports a version of MongoDB Server that supports the feature.

  • If mongosync already supports a major version of MongoDB Server, changes that require new access privileges in order to continue supporting that version of MongoDB Server.

Minor Releases

  • Adding support for a previously incompatible MongoDB Server version.

  • Requiring new access privileges for a previously unsupported major release of MongoDB Server.

  • Adding support for previously unsupported collection types.

  • Adding support for previously unsupported index types.

  • Adding new endpoints, new fields, or new accepted inputs in the REST API.

  • Adding new documented CLI options.

  • Adding new configuration keys or accepted values.

Patch Releases

  • Backwards compatible bug fixes.

  • Performance regression fixes.

  • Performance improvements.

  • Changes to help text strings.

  • Changes to log text strings.

  • Changes to informational text in API responses, but not changes to enum-style string fields like "state".

  • Typo fixes.

←  TelemetryRelease Notes →

On this page

Share Feedback