Docs Menu

Docs HomeMongoid

Mongoid 9.0

On this page

  • Sandbox Mode for Rails Console
  • New Transactions API
  • Embedded Documents Always Use Parent Persistence Context
  • Raise AttributeNotLoaded error when accessing fields omitted from query projection
  • Use configured time zone to typecast Date to Time in queries
  • `#touch method on embedded documents correctly handles touch: false option
  • Flipped default for :replace option in #upsert
  • Bug Fixes and Improvements

This page describes significant changes and improvements in Mongoid 9.0. The complete list of releases is available on GitHub and in JIRA; please consult GitHub releases for detailed release notes and JIRA for the complete list of issues fixed in each release, including bug fixes.

Mongoid now supports Rails console sandbox mode. If the Rails console started with --sandbox flag, Mongoid starts a transaction on the :default client before opening the console. This transaction won't be committed; therefore, all the commands executed in the console using the :default client won't be persisted in the database.


If you execute commands in the sandbox mode using any other client than default, these changes will be persisted as usual.

Mongoid 9.0 introduces new transactions API that is inspired by ActiveRecord:

Band.transaction do
Band.create(title: 'Led Zeppelin')
band = Band.create(title: 'Deep Purple')
band.transaction do = false!

Please consult transactions documentation for more details.

Mongoid 8.x and older allows user to specify persistence context for an embedded document (using store_in macro). In Mongoid 9.0 these settings are ignored for embedded documents; an embedded document now always uses the persistence context of its parent.

When attempting to access a field on a model instance which was excluded with the .only or .without query projections methods when the instance was loaded, Mongoid will now raise a Mongoid::Errors::AttributeNotLoaded error.

#=> raises Mongoid::Errors::AttributeNotLoaded
Band.without(:label).first.label = 'Sub Pop Records'
#=> raises Mongoid::Errors::AttributeNotLoaded

In earlier Mongoid versions, the same conditions would raise an ActiveModel::MissingAttributeError. Please check your code for any Mongoid-specific usages of this class, and change them to Mongoid::Errors::AttributeNotLoaded. Note additionally that AttributeNotLoaded inherits from Mongoid::Errors::MongoidError, while ActiveModel::MissingAttributeError does not.

When querying for a Time field using a Date value, Mongoid now correctly considers the Mongoid.use_activesupport_time_zone configuration option to perform type conversion.

Mongoid.use_activesupport_time_zone = true
class Magazine
include Mongoid::Document
field :published_at, type: Time
end = 'Asia/Tokyo'
Magazine.gte(published_at: Date.parse('2022-09-26'))
#=> will return all results on or after Sept 26th, 2022
# at 0:00 in Asia/Tokyo time zone.

In prior Mongoid versions, the above code would ignore the Mongoid.use_activesupport_time_zone setting and behave as if it were false, i.e. always using the system time zone to perform the type conversion.

Note that in prior Mongoid versions, typecasting Date to Time during persistence operations was already correctly using the Mongoid.use_activesupport_time_zone setting.

When the touch: false option is set on an embedded_in relation, calling the #touch method on an embedded child document will not invoke #touch on its parent document.

class Address
include Mongoid::Document
include Mongoid::Timestamps
embedded_in :mall, touch: false
class Mall
include Mongoid::Document
include Mongoid::Timestamps
embeds_many :addresses
mall = Mall.create!
address = mall.addresses.create!
#=> updates address.updated_at but not mall.updated_at

In addition, the #touch method has been optimized to perform one persistence operation per parent document, even when using multiple levels of nested embedded documents.

Mongoid 8.1 added the :replace option to the #upsert method. This option was used to specify whether or not the existing document should be updated or replaced.

Mongoid 9.0 flips the default of this flag from true => false.

This means that, by default, Mongoid 9 will update the existing document and will not replace it.

This section will be for smaller bug fixes and improvements:

  • The .unscoped method now also clears scopes declared using .with_scope MONGOID-5214.

  • When evolving a String to a BigDecimal (i.e. when querying a BigDecimal field with a String object), if the map_big_decimal_to_decimal128 flag set to true, the conversion will return a BSON::Decimal128 and not a String MONGOID-5484.

  • Created new error Mongoid::Errors::InvalidEstimatedCountCriteria for when calling estimated_document_count on a document class with a default scope MONGOID-4960.

  • Mongoid now uses primary reads for validations in all cases MONGOID-5150.

  • Added support for symbol keys in localized field translation hashes MONGOID-5334.

  • Added index wildcard option MONGOID-5388.

  • With the map_big_decimal_to_decimal128 flag set to false, demongoizing a non-numeric, non-string value that implements :to_d will return a string rather than a BigDecimal MONGOID-5507.

←  Release NotesMongoid 8.1 →
Share Feedback
© 2023 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.