<commit_before># Overview

For instructions on upgrading to newer versions, visit
[mongoid.org](http://mongoid.org/en/mongoid/docs/upgrading.html).

## 3.1.0 (branch: master)

### New Features

* Added `Document.first_or_create!` and `Criteria#first_or_create!`. This
  raises a validations error if creation fails validation.

        Band.where(name: "Depeche Mode").first_or_create!
        Band.where(name: "Tool").first_or_create!(active: true)

* Added `Document.first_or_initialize` and `Criteria#first_or_initialize`.
  This is the same as `first_or_create` but initializes a new (unpersisted)
  document if none is found.

        Band.where(name: "Depeche Mode").first_or_initialize
        Band.where(name: "Tool").first_or_initialize(active: true)

* Added `Model.pluck` and `Criteria#pluck` similar to Active Record's, which
  returns an array of values for the provided field. (<NAME>)

        Band.where(name: "Depeche Mode").pluck(:_id)
        Band.where(name: "Tool").pluck(:likes)

* \#2324 Embeds many relations now properly handle `delete_if`.

* \#2317 Added `Document.first_or_create` and `Criteria#first_or_create`.
  This will return the first matching document or create one with additional
  attributes if one does not exist. (incorvia)

        Band.where(name: "Depeche Mode").first_or_create
        Band.where(name: "Tool").first_or_create(active: true)

* \#2292 Added `Model.each_with_index`.

* \#2285 `Config.load_configuration` is now public for those who want to instantiate
  settings directly from a hash.

* \#2275 Added rake task `db:mongoid:purge` that will drop all collections with
  the exception of the system collections in the default database.

* \#2257 `after_find` callbacks have been added for when documents are returned
  from the database.

        class Band
          include Mongoid::Document

          after_find do |doc|
            # Some logic here.
          end
        end

* \#2223 Allow to find documents by javascript with parameters that are
  protected from javascript injection via `Model.for_js`.

        Band.for_js("this.name = param", param: "Tool")
        Band.where(:likes.gt => 1000).for_js("this.likes < this.follows")

* \#2197 When providing session configuration with no ports, Mongoid will now
  default these to 27017.

* \#2180 1-n and n-n relations now support before/after add/remove callbacks.
  (<NAME>)

        class Band
          include Mongoid::Document

          embeds_many :albums, after_add: :notify_labels
          has_many :followers, before_remove: ->(band, follower){ notify_unfollow(follower) }
        end

* \#2157 `Criteria#update` and `Criteria#update_all` now serialize values
  according to their field type, if a field is defined.

* \#2022 Custom callbacks can now register themselves for use with observers
  by using the `observable` macro.

        class Band
          include Mongoid::Document

          define_model_callbacks :notification
          observable :notification
        end

        class BandObserver < Mongoid::Observer

          def before_notification(band)
            #...
          end

          def after_notification(band)
            #...
          end
        end

* \#1766 Many to many relations will not touch the database if the foreign key
  is an empty array.

* \#1564 Many to many foreign keys now have the default set lazily only if the
  relation has been accessed. This avoids storing empty arrays if the relation
  has not been touched.

### Resolved Issues

## 3.0.7 (branch 3.0.0-stable)

### Resolved Issues
<commit_msg>Update changelog for #2399<commit_after># Overview

For instructions on upgrading to newer versions, visit
[mongoid.org](http://mongoid.org/en/mongoid/docs/upgrading.html).

## 3.1.0 (branch: master)

### New Features

* Added `Document.first_or_create!` and `Criteria#first_or_create!`. This
  raises a validations error if creation fails validation.

        Band.where(name: "Depeche Mode").first_or_create!
        Band.where(name: "Tool").first_or_create!(active: true)

* Added `Document.first_or_initialize` and `Criteria#first_or_initialize`.
  This is the same as `first_or_create` but initializes a new (unpersisted)
  document if none is found.

        Band.where(name: "Depeche Mode").first_or_initialize
        Band.where(name: "Tool").first_or_initialize(active: true)

* Added `Model.pluck` and `Criteria#pluck` similar to Active Record's, which
  returns an array of values for the provided field. (Jason Lee)

        Band.where(name: "Depeche Mode").pluck(:_id)
        Band.where(name: "Tool").pluck(:likes)

* \#2324 Embeds many relations now properly handle `delete_if`.

* \#2317 Added `Document.first_or_create` and `Criteria#first_or_create`.
  This will return the first matching document or create one with additional
  attributes if one does not exist. (incorvia)

        Band.where(name: "Depeche Mode").first_or_create
        Band.where(name: "Tool").first_or_create(active: true)

* \#2292 Added `Model.each_with_index`.

* \#2285 `Config.load_configuration` is now public for those who want to instantiate
  settings directly from a hash.

* \#2275 Added rake task `db:mongoid:purge` that will drop all collections with
  the exception of the system collections in the default database.

* \#2257 `after_find` callbacks have been added for when documents are returned
  from the database.

        class Band
          include Mongoid::Document

          after_find do |doc|
            # Some logic here.
          end
        end

* \#2223 Allow to find documents by javascript with parameters that are
  protected from javascript injection via `Model.for_js`.

        Band.for_js("this.name = param", param: "Tool")
        Band.where(:likes.gt => 1000).for_js("this.likes < this.follows")

* \#2197 When providing session configuration with no ports, Mongoid will now
  default these to 27017.

* \#2180 1-n and n-n relations now support before/after add/remove callbacks.
  (<NAME>)

        class Band
          include Mongoid::Document

          embeds_many :albums, after_add: :notify_labels
          has_many :followers, before_remove: ->(band, follower){ notify_unfollow(follower) }
        end

* \#2157 `Criteria#update` and `Criteria#update_all` now serialize values
  according to their field type, if a field is defined.

* \#2022 Custom callbacks can now register themselves for use with observers
  by using the `observable` macro.

        class Band
          include Mongoid::Document

          define_model_callbacks :notification
          observable :notification
        end

        class BandObserver < Mongoid::Observer

          def before_notification(band)
            #...
          end

          def after_notification(band)
            #...
          end
        end

* \#1766 Many to many relations will not touch the database if the foreign key
  is an empty array.

* \#1564 Many to many foreign keys now have the default set lazily only if the
  relation has been accessed. This avoids storing empty arrays if the relation
  has not been touched.

### Resolved Issues

## 3.0.7 (branch 3.0.0-stable)

### Resolved Issues

* \#2399 Reject blank id values on has_many `Model#object_ids=`.
  (<NAME>)

{'fraction_non_alphanumeric': 0.09018311992289688, 'fraction_numerical': 0.020652622883106153, 'mean_word_length': 3.1603665521191293, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5642620', 'n_tokens_mistral': 2235, 'n_tokens_neox': 2050, 'n_words': 737}