Edge Rider Build Status

Power tools for ActiveRecord relations (scopes)

In ActiveRecord, relations (or scopes) allow you to construct complex queries piece-by-piece and then trigger a query or update at a precisely defined moment. If you write any kind of scalable code with ActiveRecord, you are probably using relations (or scopes) to do it.

Edge Rider was created with two intents:

  1. Provide a number of utility methods to facilitate hardcore work with relations.
  2. Provide a stable API for working with relations across multiple versions of Rails (since Rails has a tradition of breaking details of its relation API every other release).

It is tested with Rails 2.3, 3.0, 3.2 and 4.1, and on Ruby 1.8.7, 1.9.3 and 2.1.0.

Usage

Traversing a relation along an association

Edge Rider gives your relations a method #traverse_association which returns a new relation by "pivoting" around a named association.

Say we have a Post model and each Post belongs to an author:

class Post < ActiveRecord::Base
  belongs_to :author
end

To turn a relation of posts into a relation of its authors:

posts = Post.where(:archived => false)
authors = posts.traverse_association(:author)

You can traverse multiple associations in a single call. E.g. to turn a relation of posts into a relation of all posts of their authors:

posts = Post.where(:archived => false)
posts_by_same_authors = posts.traverse_association(:author, :posts)

Implementation note: The traversal is achieved internally by collecting all foreign keys in the current relation and return a new relation with an IN(...) query (which is very efficient even for many thousand keys). This means every association that you pivot around will trigger one SQL query.

Efficiently collect all record IDs in a relation

You often want to retrieve an array of all record IDs in a relation.

You should not use relation.collect(&:id) for this because a call like that will instantiate a potentially large number of ActiveRecord objects only to collect its ID.

Edge Rider has a better way. Your relations gain a method #collect_ids that will fetch all IDs in a single query without instantiating a single ActiveRecord object:

posts = Post.where(:archived => false)
post_ids = posts.collect_ids

Implemenation note: In Rails 3.2+, #collect_ids delegates to #pluck, which can be used for the same purpose.

Collect record IDs from any kind of object

When writing a method that filters by record IDs, you can make it more useful by accepting any kind of argument that can be turned into a list of IDs:

Post.by_author(1)
Post.by_author([1, 2, 3])
Post.by_author(Author.find(1))
Post.by_author([Author.find(1), Author.find(2)])
Post.by_author(Author.active)

For this use case Edge Rider defines #collect_ids on many different types:

Post.where(:id => [1, 2]).collect_ids    # => [1, 2, 3]
[Post.find(1), Post.find(2)].collect_ids # => [1, 2]
Post.find(1).collect_ids                 # => [1]
[1, 2, 3].collect_ids                    # => [1, 2, 3]
1.collect_ids                            # => [1]

You can now write Post.by_author from the example above without a single if or case:

class Post < ActiveRecord::Base

  belongs_to :author

  def self.for_author(author_or_authors)
    where(:author_id => author_or_authors.collect_ids)
  end

end

Efficiently collect all values in a relation's column

You often want to ask a relation for an array of all values ofin a given column.

You should not use relation.collect(&:column) for this because a call like that will instantiate a potentially large number of ActiveRecord objects only to collect its column value.

Edge Rider has a better way. Your relations gain a method #collect_column that will fetch all column values in a single query without instantiating a single ActiveRecord object:

posts = Post.where(:archived => false)
subjects = posts.collect_column(:subject)

Implementation note: In Rails 3.2+, #collect_column delegates to #pluck, which can be used for the same effect.

Collect unique values in a relation's column

If you only care about unique values, use the :distinct => true option:

posts = Post.where(:archived => false)
distinct_subjects = posts.collect_column(:subject, :distinct => true)

With this options duplicates are discarded by the database before making their way into Ruby.

Implementation note: In Rails 3.2+, the :distinct option is implemented with #uniq which can be used for the same effect.

Retrieve the SQL a relation would produce

Sometimes it is useful to ask a relation which SQL query it would trigger, if it was evaluated right now. For this, Edge Rider gives your relations a method #to_sql:

# Rails 2 scope
Post.scoped(:conditions => { :id => [1, 2] }).to_sql 
# => "SELECT `posts`.* FROM `posts` WHERE `posts.id` IN (1, 2)"

# Rails 3 relation
Post.where(:id => [1, 2]).to_sql 
# => "SELECT `posts`.* FROM `posts` WHERE `posts.id` IN (1, 2)"

Implementation note: Rails 3+ implements #to_sql. Edge Rider backports this method to Rails 2 so you can use it regardless of your Rails version.

Simplify a complex relation for better chainability

In theory you can take any relation and extend it with additional joins or conditions. We call this chaining* relations.

In practice chaining becomes problematic as relation chains grow more complex. In particular having JOINs in your relation will reduce the relations's ability to be chained with additional JOINs without crashes or side effects. This is because ActiveRecord doesn't really "understand" your relation chain, it only mashes together strings that mostly happen to look like a MySQL query in the end.

Edge Rider gives your relations a new method #to_id_query:

Site.joins(:user).where(:users => { :name => 'Bruce' }).to_id_query

#to_id_query will immediately run an SQL query where it collects all the IDs that match your relation:

SELECT sites.id FROM sites INNER JOIN users WHERE sites.user_id = sites.id AND users.name = 'Bruce'

It now uses these IDs to return a new relation that has no joins and a single condition on the id column:

SELECT * FROM sites WHERE sites.user_id IN (3, 17, 103)

Preload associations for loaded ActiveRecords

Sometimes you want to fetch associations for records that you already instantiated, e.g. when it has deeply nested associations.

Edge Rider gives your model classes a method .preload_associations. The method can be used to preload associations for loaded objects like this:

@user = User.find(params[:id])
User.preload_associations [@user], { :threads => { :posts => :author }, :messages => :sender }

Implementation note: Rails 2.3 and Rails 3.0 already has a method .preload_associations which Edge Rider merely makes public. Edge Rider ports this method forward to Rails 3.1+.

Retrieve the class a relation is based on

Edge Rider gives your relations a method #origin_class that returns the class the relation is based on. This is useful e.g. to perform unscoped record look-up.

Post.recent.origin_class
# => Post

Note that #origin_class it roughly equivalent to the blockless form of unscoped from Rails 3.2+, but it works consistently across all Rails versions.

Turn a model into a scope or narrow down an existing scope

Edge Rider ports Model.scoped forward to Rails 4+ (taken from activerecord-deprecated_finders). This enables you to consistently turn models into scopes or narrow down scopes across all versions of Rails.

User.scoped # just calls User.all in Rails 4
User.active.scoped(conditions: { admin: true })

Implementation note: Rails 2 and 3 already have a method .scoped which Edge Rider does not touch. Rails 4 has removed this method and splits its functionality into the query methods known from Rails 3 (.where, .order etc.) and an .all method that just returns a scope.

Note that associations and scopes also have a .scoped method that behaves slightly different in all versions of Rails (see scoped_spec.rb). These methods are not modified.

Installation

In your Gemfile say:

gem 'edge_rider'

Now run bundle install and restart your server.

Development

  • Test applications for various Rails versions lives in spec.
  • You need to create a MySQL database and put credentials into spec/shared/app_root/config/database.yml.
  • You can bundle all test applications by saying bundle exec rake all:bundle
  • You can run specs from the project root by saying bundle exec rake all:spec.

If you would like to contribute:

  • Fork the repository.
  • Push your changes with passing specs.
  • Send me a pull request.

I'm very eager to keep this gem leightweight and on topic. If you're unsure whether a change would make it into the gem, talk to me beforehand.

Credits

Henning Koch from makandra