`mongosync` Versioning

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

MongoDB only supports the latest patch release of each major version. For example, mongosync 1.13.0 is the latest patch release of 1.12. If you are using an unsupported version of mongosync, you might be asked to upgrade in order to receive support.

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.

Upgrade or Downgrade

Note

mongosync supports live upgrades from v1.12 to v1.13.

Use the following steps to upgrade or downgrade mongosync:

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.

Back

Verifying Data with Custom Scripts

Version Compatibility