Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Extend ActiveRecord to eagerly preload associations on a result set when one association is accessed

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 rails
Octocat-spinner-32 spec
Octocat-spinner-32 .gitignore
Octocat-spinner-32 Gemfile
Octocat-spinner-32 History.txt
Octocat-spinner-32 README.rdoc
Octocat-spinner-32 Rakefile
Octocat-spinner-32 TODO
Octocat-spinner-32 eager_record.gemspec
README.rdoc

EagerRecord

Never pass the `:include` option to `find` again.

EagerRecord is a simple extension to ActiveRecord that automates the process of preloading associations in a result set. Each time ActiveRecord loads a collection of more than one record out of the database, a reference to the collection is stored in each record. Then, when you first access an association on one of those records; EagerRecord automatically preloads that association for all of the records in the collection.

Basic Usage

There isn't really any usage; just install the gem and add it as a dependency. Whereas before you might write:

Comment.all(:include => :user).each { |comment| puts comment.user }

Now you get the same effect with:

Comment.all.each { |comment| puts comment.user }

In the first iteration of that loop, all the comments' users are loaded in a single SQL query.

Scoped Preloading

It isn't enabled by default, but EagerRecord has experimental support for “scoped preloading”. If you turn it on, EagerRecord will perform preloading on scoped associations in the same way that it does so for normal ones. For instance, let's say you've got a `:ham` named scope for your `Comment` class:

Post.all.each { |post| puts post.comments.ham.inspect }

In the first iteration of this loop, EagerRecord will preload all of the ham comments for all of the posts in the collection; the above code will only generate two SQL queries. A couple of caveats:

  • This only works for normal `has_many` associations right now. I could add support for other collection types in the future.

  • The code that does this is considerably more invasive in ActiveRecord's internals than the regular eager preloading code. It basically has to trick ActiveRecord into thinking that there is an association collection defined on your model that doesn't actually exist, and then tell it to preload that association. There are a couple of tests; so I know it basically works, but beware that your mileage may vary. Because of this, you have to explicitly tell eager record you want to use this feature (put this line in a file in `config/initializers`:

    EagerRecord::ScopedPreloading.install

As an alternative to using this functionality, consider defining extra scoped associations with `:readonly => true` as needed.

Does it work with all association types?

Mostly…

The test suite covers just about all of them; if you find one that doesn't work, please file an issue.

Except!

There's a bug in ActiveRecord's preloading that causes it to build an invalid query when preloading a `has_many :through` association that defines a `:conditions` option that references the join table. For that reason, EagerRecord does not attempt to eagerly load `has_many :through` associations that have a `:conditions` option.

Do I need to make any changes to my code?

EagerRecord doesn't add any new methods to ActiveRecord, so you don't need to interact with it directly. However, you might want to make adjustments to your code to encourage preloading to happen at the earliest possible point. In particular, if you're using `size` or `first` or `last`, on a collection, but then later on also working with all the members of that collection, you're better off calling `to_a` at the beginning so that preloading happens and ActiveRecord doesn't make extra SQL queries.

This is free software.

The author(s) of this software relinqiush all copyright on it to the maximum extent permitted by law. Anyone is free to copy, distribute, mangle, sell, improve, destroy, heckle, hate, or love this software with no restrictions.

Something went wrong with that request. Please try again.