upgrading

Use this as a reference when upgrading between Mongoid versions. You can always reference the changelog for bug fixes, new features, and major changes between versions.

upgrading to 2.4.0

No special changes are required.

upgrading to 2.3.0

Active Model, MongoDB, and the MongoDB Ruby Driver requirements have been raised:

  • Active Model 3.1 is now the minimum requirement.
  • MongoDB 2.0.0 is now the minimum requirement.
  • MongoDB Ruby Driver, BSON versions 1.4.0 are the minimum.

For those using #create, #create!, and #build on associations that are subclassed and passing in types to these methods, the type now needs to be the third argument as mass assignment scoping is now supported in these methods: 

canvas.shapes.build({ x: 10, y: 10 }, as: :admin, Circle)
canvas.shapes.create({ x: 10, y: 10 }, as: :admin, Circle)
canvas.shapes.create!({ x: 10, y: 10 }, as: :admin, Circle)

upgrading to 2.2.0

Previously when setting an embedded relation via attributes on the parent, Mongoid would persist the embedded relation regardless of whether the parent operation was a persistence operation or not. This is best shown with an example: 

class Person
  include Mongoid::Document
  field :name, type: String
  embeds_many :addresses
end

class Address
  include Mongoid::Document
  field :street, type: String
  embedded_in :person
end

# The following code would previously save the address with an atomic $push
# immediately then the attributes were set.
person.addresses_attributes = [ { :street => "High St." }]

Now Mongoid waits to persist the embedded documents until save is called on the parent, or if the attributes were set via update_attributes. The following are examples of calls and how they now behave: 

# Atomic $push of the new address.
person.addresses << Address.new

# Atomic $push of the new address.
person.addresses.create

# Atomic $push of the new address.
person.addresses = [ Address.new ]

# Atomic $push of the new address.
person.addresses = []
person.addresses = nil

# No save, will be atomic $set when parent is saved.
person.attributes = { :addresses => [ Address.new ] }

# No save, will be atomic $set when parent is saved.
person.addresses_attributes = [ { :street => "High St." }]

# No save, will be atomic $unset when parent is saved.
person.attributes = { :addresses => [] }
person.attributes = { :addresses => nil }

# No save, will be atomic $pull when parent is saved.
person.addresses_attributes = [ { :_id => 1, :_destroy => true }]

Upgrading to 2.1.0

Mongoid now requires MongoDB 1.8.0 and higher.

Traditional master/slave support has been removed, you will need to switch to using replica sets instead.

Custom field serialization has changed. Please see RDoc for API.

Upgrading to 2.0.0

You may use the familiar Active Record macros for relational associations if it helps with understanding where the foreign keys are stored.

  • has_many
  • has_one
  • belongs_to
  • has_and_belongs_to_many

The id method on criteria has been removed in favour of for_ids. 

Person.criteria.for_ids("4ab2bc4b8ad548971900005c")
Person.criteria.for_ids(["4ab2bc4b8ad548971900005c", "..."])

Upgrading to 2.0.0.rc.1 +

Please note there are many changes in this upgrade - please take caution and be mindful of each item listed here. There were close to 400 commits between beta 20 and rc 1, and was a COMPLETE REWRITE of all association code as well as refactorings and rewrites in many other areas.

Relational associations no longer autosave when the parent relation is created. Previously a save on a new document which had a references_many or references_one association loaded would save the relations on it's first save. In order to get this functionality back, an autosave: true option must be provided to the macro (This only applies to references_many and references_one): 

class Person
  include Mongoid::Document
  references_many :posts, autosave: true
  references_one :game, autosave: true
end

For relational many-to-many associations, the stored_as: :array option on references_many has been sacked. You will get an error on class load to change these to the new syntax: 

class Person
  include Mongoid::Document
  references_and_referenced_in_many :preferences
end

Mongoid now validates all associated "child" relations by default, which is the opposite behaviour from the last release. You may remove any validates_associated definitions that do not require custom behaviour for the following relations:

  • embeds_many
  • embeds_one
  • references_many
  • references_one

If you do NOT want the automatic validation on these relations, you can supply the definition with a validate: false option to turn it off: 

class Person
  include Mongoid::Document
  embeds_many :addresses, validate: false
end

Criteria object are now immutable, and return a new object with each method call. Also, the following methods have been added:

  • delete_all
  • destroy_all
  • create

This allows for limited database update commands to happen off of a criteria object: 

Person.where(title: "Prince").create # => Creates one
Person.where(:age.gt => 40).delete_all # => Delete all matching
Person.where(:age.gt => 40).destroy_all # => Destroy all matching

Mongoid now supports default_scope in a limited capacity: 

class Person
  include Mongoid::Document
  field :name, type: String
  default_scope asc(:name)
end

Mongoid now supports multiple additional database connections on a per-model basis. Note that the "databases" entry in the configuration is only for ADDITIONAL databases - the primary master still is configured as usual: 

defaults: &defaults
  host: localhost
  slaves:
    - host: localhost
      port: 27018
    - host: localhost
      port: 27019
  databases:
    secondary:
      database: secondary_config_test
      host: localhost
      post: 27020
      slaves:
        - host: localhost
          port: 27021
        - host: localhost
          port: 27022

To tell a model to persist to another database: 

class Business
  include Mongoid::Document
  set_database :secondary
end

The inverse_of option is no longer required on any relation.

Mongoid now allows recursive embedded relationships through 2 simple macros: 

class Role
  include Mongoid::Document
  field :name, type: String
  recursively_embeds_many
end

role.parent_role # => Gets the parent.
role.child_roles # => Gets the children.

class Role
  include Mongoid::Document
  field :name, type: String
  recursively_embeds_one
end

role.parent_role # => Gets the parent.
role.child_role # => Gets the child.

:default_order No longer functions on relations and is a known issue.

For third-party library developers, the internal Mongoid relation metadata has been revamped. Now when performing a Document#reflect_on_association(name) you will be returned a Mongoid::Relations::Metadata object, which now provides much more comprehensive information about the relation in question.

Upgrading to 2.0.0.beta.16 +

This version requires an upgrade to MongoDB 1.6.0.

Upgrading to 2.0.0.beta.15 +

If you had been using the class variable include_root_in_json for JSON serialization, this will no longer work. You will need to now use the global Mongoid configuration option of the same name in your mongoid.yml if you want to turn it on. (It now defaults to false.) 

defaults: &defaults
  include_root_in_json: true

Upgrading to 2.0.0.beta.14 +

The accessible: false option on fields has been removed in favor of attr_accessible and attr_protected. You will need to change those definitions in your models.

Note that gemcutter is sorting the gems funkily, so when upgrading Mongoid for now you will have to specify the exact version. If you are using bundler then it takes care of this for you. The gems in the way will get yanked soon.

Upgrading to 2.0.0.beta.11 +

The Mongoid.use_object_ids configuration option has been removed and will need to be removed from your mongoid.yml or configuration block.

If you had been using the default String representation of BSON::ObjectID as your ids, you will need to do one of the following options:

a) Tell each one of your models to use Strings as ids like so: 

class Person
  include Mongoid::Document
  identity type: String
end

b) Migrate all your String ids over to ObjectIDs in your database. See This Gist for an example script to do this. (Thanks Kyle Banker)

Upgrading to 2.0.0.beta.10 +

Passenger users who are using smart spawning must now remove their initializers with the reconnect on fork code. Mongoid now handles this for you.

Unicorn users who set preload_app to true must also delete their initializers with the reconnect on fork code. Mongoid now handles this for you as well.

Mongoid, 2009-2011, written and maintained by Durran Jordan.