Upgrading Mongoid [upgrading]

Mongoid provides a stable upgrade path for users migrate to new versions.


Each Mongoid release has a version number in major.minor.patch format. Beginning in Mongoid 7.4, Mongoid uses Semantic Versioning (SemVer), which typically means:


Mongoid 7.3 and prior do not strictly adhere to SemVer and may contain breaking changes even in minor version releases. Users should exercise additional caution when upgrading to these versions.

How to Upgrade Mongoid

Before you Upgrade

Upgrading Mongoid

The following outlines our recommended procedure to upgrade to a new Mongoid version:

  1. Upgrade to each minor version individually.

    For example, if you are upgrading from Mongoid 7.4 to 8.1, we recommend you follow this procedure for the latest patch version of each minor version, e.g. first to 7.5.x, then to 8.0.x, and finally to 8.1.x.

  2. Before upgrading, ensure you have load_defaults set to your current version.

    If you haven't yet enabled the latest behavior on your current version, you should do so prior to upgrading.

  3. Review the Release Notes <release-notes> carefully when upgrading.

  4. Test your app on the new version.

    Your app should be tested and released "as-is" on the new Mongoid version _without adjusting load_defaults or any feature flags.

  5. Once Step 4 is confirmed to be stable, set load_defaults to the new version to enable new functionality. Also fix any deprecation warnings at this time.

    You may also enable new functionalities one-by-one using feature flags.

Load Defaults and Feature Flags

When a feature flag is introduced, it will have a default value that preserves the previous (legacy) functionality. At this time, users are encouraged to manually set the flag to its new value in order to try out the new functionality.

In the next major version release, the flag's default value will be flipped to enable the new functionality. At this time, the flag itself will be marked deprecated. Finally, the deprecated flag will be removed from the config entirely in a subsequent major version release.

Feature flags are added as a convenience to facilitate upgrading, but are not intended to be supported in perpetuity.

Deprecation Policy

Mongoid may deprecate features, functionality, methods, constants, etc. from time to time. To do so, Mongoid may take one or more of the following actions:

Mongoid may then remove the deprecated functionality in the next major version release.

Methods which are marked @api private may be removed without deprecation, even if such methods are public in Ruby.