bang query methods (where!, includes!, etc.) cause indeciperable errors when called on model class

I understand that bang methods in the classic Ruby sense are supposed to alter the current instance, but getting errors like:

NoMethodError: undefined method `where!’ for #Class:0x007ff1522d3110


NoMethodError: undefined method `includes!’ for #Class:0x007ff1522d3110

when calling the bang methods from QueryMethods on a model class are really not helpful.

It’s understandable that you don’t want to pass a model class into a method that expects a relation that it can act upon and change with a bang query method and have it successfully create a new relation and call some method on it that is never again seen, hence the error. I also understand wanting to avoid any more checking/raising code than necessary in ActiveRecord both for maintainability, clarity, and maybe efficiency- but just look at this:

2.0.0p247 :001 > MyModel.to_s

=> “MyModel”

2.0.0p247 :002 >

=> “#< MyModel:0x007fc92aa017e8>”

2.0.0p247 :003 > MyModel.where({})

=> …

2.0.0p247 :003 > MyModel.where!({})

NoMethodError: undefined method `where!’ for #Class:0x007fc92a95a240


The bang methods are private and should not be used in applications (see the :nodoc: in the method definition)


There is a reason for that? They sound useful in a lot of scenarios.

Yes, there is


I’m too late to the party, I thought these bang methods was public on rails 4 :frowning:

We will have people doing wrong things with these methods but a good documentation will reduce that, ruby itself have a lot of these methods like params.merge!(…) or controller_name.gsub!(…) and I never saw people (that do not means there is no people reporting, I just don’t saw) reporting issues because things like that.

The problem of scopes that must not be mutated can be solved using some freeze implementation on that scope, like this:

relation = User.where(:dumb => false).immutable!

relation.where!(:dumb => true)

#=> raises ActiveRecord::ImmutableRelation

I agree that new developers may do strange things but the rails itself is not so easy for beginners, but I have no expertise about how it may impact the community, so if you guys think that won’t be great these methods be public, :okaymeme:


What I usually do when “mutable relations” makes sense are filters like that:

The primary reason I would be against these being public is the following example:

User.where!(email: ‘’)

Reading that, I would expect that I have changed the default scope for EVERY user query. I believe this is what José Valim was hinting at. Because the ActiveRecord class is a global object, scopes originate from there, and any piece of code could modify the behavior of that global, it would introduce side effects throughout an application. Ideally, when side effects are present, they’re localized to a small scope.

That’s why the proposal of immutable relations, User.where! would raise a ActiveRecord::ImmutableRelation but must be a way to create mutable relations, Model.all would be fine since it returns new relations on each call (not sure about internals but it seems not too difficulty to make it work):

irb(main):012:0> Transaction.all.object_id
=> 70363740246020
irb(main):013:0> Transaction.all.object_id
=> 70363740260420

An “acceptable" API would be:

User.where!(email: ‘’)

#=> raise ActiveRecord::ImmutableRelation(“You can’t use bang relation methods directly on model, use User.all.where! instead”)

User.all.where!(email: ‘’)

#=> []


Gabriel Sobrinho

I prefer to stick with that decision.

It is easier to teach people when we say “Relations are immutables” than “Relations are immutables, unless you call these methods, or someone called they in some plugin”.

Documentation will help, but it will not solve. In the same way you didn’t read that these methods are private API (they are not even listed in the API site) people will not read the gotcha in the documentation.

Also I don’t why we should complicate the relation API even more adding a new exception and new methods only to make possible to people able to call these bang methods.

I see, makes sense, thanks! :slight_smile:


Gabriel Sobrinho

Thanks, Gabriel. The one place it was a pain, I just did array wrapping and unsplat to remedy, e.g. before I had:

def some_method(relation, param_name)

… other code


opts.reverse_merge(attr_name: param_name.to_sym)


in code that calls it…

opts = some_method(relation, param_name)

now I have:

def some_method(relation, param_name)

… other code

relation = relation.joins(opts[:joins])

[relation, opts.reverse_merge(attr_name: param_name.to_sym)]


in code that calls it…

relation, opts = *some_method(relation, param_name)

It’s doing more than I’d like (having to create another array to wrap the result, and all of the additional operations in joins(…) vs. joins!(…)), but that’s ok.


We plan to move the API to YARD, hopefully for 4.1 unless there is something unexpected in the transition.

These would be use-cases for the @private tag I believe. The tag will convey user-level private visibility better than nodoc for those reading the source code.

That’s great, thanks Xavier!


Gabriel Sobrinho