the test-app is included in the console session

README.md

@@ -51,7 +51,7 @@ Product.each_instance.lazy.inject(0) {|sum,r| sum +  r.quantity } #=> 499500
 All these methods take an options hash to control things more:
 
     block_size:n      The number of rows to fetch from the database each time (default 1000)
-    while:value       Continue looping as long as the block returns this value  
+    while:value       Continue looping as long as the block returns this value
     until:value       Continue looping until the block returns this value
     connection:conn   Use this connection instead of the current Product connection
     fraction:float    A value to set for the cursor_tuple_fraction variable.
@@ -103,6 +103,16 @@ Product.pluck_rows(:id) #=> ["1", "2", ...]
 Product.pluck_instances(:id, :quantity) #=> [[1, 503], [2, 932], ...]
 ```
 
+###Associations and Eager Loading
+
+ActiveRecord performs some magic when eager-loading associated row. It
+will usually not join the tables, and prefers to load the data in
+separate queries.
+
+This library hooks onto the `to_sql` feature of the query builder. As a
+result, it can't do the join if ActiveRecord decided not to join, nor
+can it construct the association objects eagerly.
+
 ##Background: Why PostgreSQL Cursors?
 
 ActiveRecord is designed and optimized for web performance. In a web transaction, only a "page" of

Rakefile

@@ -9,7 +9,7 @@ task :test do
   sh "ruby test/test_*"
 end
 
-desc "Open and IRB Console with the gem loaded"
+desc "Open and IRB Console with the gem and test-app loaded"
 task :console do
   sh "bundle exec irb  -Ilib -I . -r postgresql_cursor -r test-app/app"
   #require 'irb'

test-app/app.rb

@@ -1,8 +1,7 @@
 #!/usr/bin/env ruby
 ################################################################################
-# To run this "app", do a "rake setup" first
-# To work with this app, load it from the root's "rake console" task,
-# then do: require_relative 'test-app/app'
+# To run this "app", do a "rake setup" first.
+# To work with this app, run the "rake console" task, which loads this file.
 ################################################################################
 require 'rubygems'
 require 'bundler/setup'
@@ -14,17 +13,18 @@
   database: ENV['TEST_DATABASE'] || 'postgresql_cursor_test',
   username: ENV['TEST_USER']     || ENV['USER'] || 'postgresql_cursor')
 
-# create table products (id serial primary key);
-
 class Product < ActiveRecord::Base
   def self.generate(max=1_000)
+    Product.destroy_all
     max.times do |i|
       connection.execute("insert into products values (#{i})")
     end
   end
+
+  def tests
+    Product.where("id>0").each_row(block_size:100) { |r| p r["id"] } # Hash
+    Product.where("id>0").each_instance(block_size:100) { |r| p r.id } # Instance
+  end
 end
 
-#Product.destroy_all
 #Product.generate
-#Product.where("id>0").each_row(block_size:100) { |r| p r["id"] } # Hash
-#Product.where("id>0").each_instance(block_size:100) { |r| p r.id } # Instance