sequel 3.25.0 → 3.26.0

data/lib/sequel/dataset/features.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Methods that describe what the dataset supports
+    # :section: 4 - Methods that describe what the dataset supports
     # These methods all return booleans, with most describing whether or not the
     # dataset supports a feature.
     # ---------------------
@@ -11,7 +11,13 @@ module Sequel
     
     # Whether this dataset quotes identifiers.
     def quote_identifiers?
-      @quote_identifiers
+      if defined?(@quote_identifiers)
+        @quote_identifiers
+      elsif db.respond_to?(:quote_identifiers?)
+        @quote_identifiers = db.quote_identifiers?
+      else
+        @quote_identifiers = false
+      end
     end
     
     # Whether this dataset will provide accurate number of rows matched for

data/lib/sequel/dataset/graph.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Methods related to dataset graphing
+    # :section: 5 - Methods related to dataset graphing
     # Dataset graphing changes the dataset to yield hashes where keys are table
     # name symbols and values are hashes representing the columns related to
     # that table.  All of these methods return modified copies of the receiver.

data/lib/sequel/dataset/misc.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Miscellaneous methods
+    # :section: 6 - Miscellaneous methods
     # These methods don't fit cleanly into another section.
     # ---------------------
     
@@ -23,17 +23,13 @@ module Sequel
     #   DB[:posts]
     #
     # Sequel::Dataset is an abstract class that is not useful by itself. Each
-    # database adaptor provides a subclass of Sequel::Dataset, and has
+    # database adapter provides a subclass of Sequel::Dataset, and has
     # the Database#dataset method return an instance of that subclass.
     def initialize(db, opts = nil)
       @db = db
-      @quote_identifiers = db.quote_identifiers? if db.respond_to?(:quote_identifiers?)
-      @identifier_input_method = db.identifier_input_method if db.respond_to?(:identifier_input_method)
-      @identifier_output_method = db.identifier_output_method if db.respond_to?(:identifier_output_method)
       @opts = opts || {}
-      @row_proc = nil
     end
-    
+
     # Define a hash value such that datasets with the same DB, opts, and SQL
     # will be consider equal.
     def ==(o)
@@ -87,10 +83,10 @@ module Sequel
     # have a table, raises an error.  If the table is aliased, returns the original
     # table, not the alias
     #
-    #   DB[:table].first_source_alias
+    #   DB[:table].first_source_table
     #   # => :table
     #
-    #   DB[:table___t].first_source_alias
+    #   DB[:table___t].first_source_table
     #   # => :table
     def first_source_table
       source = @opts[:from]
@@ -114,6 +110,30 @@ module Sequel
       [db, opts.sort_by{|k| k.to_s}, sql].hash
     end
     
+    # The String instance method to call on identifiers before sending them to
+    # the database.
+    def identifier_input_method
+      if defined?(@identifier_input_method)
+        @identifier_input_method
+      elsif db.respond_to?(:identifier_input_method)
+        @identifier_input_method = db.identifier_input_method
+      else
+        @identifier_input_method = nil
+      end
+    end
+    
+    # The String instance method to call on identifiers before sending them to
+    # the database.
+    def identifier_output_method
+      if defined?(@identifier_output_method)
+        @identifier_output_method
+      elsif db.respond_to?(:identifier_output_method)
+        @identifier_output_method = db.identifier_output_method
+      else
+        @identifier_output_method = nil
+      end
+    end
+    
     # Returns a string representation of the dataset including the class name 
     # and the corresponding SQL select statement.
     def inspect

data/lib/sequel/dataset/mutation.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Mutation methods
+    # :section: 7 - Mutation methods
     # These methods modify the receiving dataset and should be used with care.
     # ---------------------
     
@@ -21,10 +21,10 @@ module Sequel
     def_mutation_method(*MUTATION_METHODS)
     
     # Set the method to call on identifiers going into the database for this dataset
-    attr_accessor :identifier_input_method
+    attr_writer :identifier_input_method
     
     # Set the method to call on identifiers coming the database for this dataset
-    attr_accessor :identifier_output_method
+    attr_writer :identifier_output_method
 
     # Whether to quote identifiers for this dataset
     attr_writer :quote_identifiers

data/lib/sequel/dataset/prepared_statements.rb

@@ -1,7 +1,7 @@
 module Sequel 
   class Dataset
     # ---------------------
-    # :section: Methods related to prepared statements or bound variables
+    # :section: 8 - Methods related to prepared statements or bound variables
     # On some adapters, these use native prepared statements and bound variables, on others
     # support is emulated.  For details, see the {"Prepared Statements/Bound Variables" guide}[link:files/doc/prepared_statements_rdoc.html].
     # ---------------------
@@ -199,11 +199,9 @@ module Sequel
       clone(:bind_vars=>@opts[:bind_vars] ? @opts[:bind_vars].merge(bind_vars) : bind_vars)
     end
     
-    # For the given type (:select, :insert, :update, or :delete),
-    # run the sql with the bind variables
-    # specified in the hash.  values is a hash of passed to
-    # insert or update (if one of those types is used),
-    # which may contain placeholders.
+    # For the given type (:select, :first, :insert, :insert_select, :update, or :delete),
+    # run the sql with the bind variables specified in the hash.  +values+ is a hash passed to
+    # insert or update (if one of those types is used), which may contain placeholders.
     #
     #   DB[:table].filter(:id=>:$id).call(:first, :id=>1)
     #   # SELECT * FROM table WHERE id = ? LIMIT 1 -- (1)
@@ -212,11 +210,13 @@ module Sequel
       prepare(type, nil, *values).call(bind_variables, &block)
     end
     
-    # Prepare an SQL statement for later execution. This returns
-    # a clone of the dataset extended with PreparedStatementMethods,
-    # on which you can call call with the hash of bind variables to
-    # do substitution.  The prepared statement is also stored in
-    # the associated database.  The following usage is identical:
+    # Prepare an SQL statement for later execution.  Takes a type similar to #call,
+    # and the name symbol of the prepared statement.
+    # This returns a clone of the dataset extended with PreparedStatementMethods,
+    # which you can +call+ with the hash of bind variables to use.
+    # The prepared statement is also stored in
+    # the associated database, where it can be called by name.
+    # The following usage is identical:
     #
     #   ps = DB[:table].filter(:name=>:$name).prepare(:first, :select_by_name)
     #

data/lib/sequel/dataset/query.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Methods that return modified datasets
+    # :section: 1 - Methods that return modified datasets
     # These methods all return modified copies of the receiver.
     # ---------------------
 
@@ -80,7 +80,7 @@ module Sequel
     # :from_self :: Set to false to not wrap the returned dataset in a from_self, use with care.
     #
     #   DB[:items].except(DB[:other_items])
-    #   # SELECT * FROM items EXCEPT SELECT * FROM other_items
+    #   # SELECT * FROM (SELECT * FROM items EXCEPT SELECT * FROM other_items) AS t1
     #
     #   DB[:items].except(DB[:other_items], :all=>true, :from_self=>false)
     #   # SELECT * FROM items EXCEPT ALL SELECT * FROM other_items
@@ -381,7 +381,11 @@ module Sequel
       inner_join(*args, &block)
     end
 
-    # Returns a joined dataset.  Uses the following arguments:
+    # Returns a joined dataset.  Not usually called directly, users should use the
+    # appropriate join method (e.g. join, left_join, natural_join, cross_join) which fills
+    # in the +type+ argument.
+    #
+    # Takes the following arguments:
     #
     # * type - The type of join to do (e.g. :inner)
     # * table - Depends on type:
@@ -411,6 +415,23 @@ module Sequel
     #   in which case it yields the table alias/name for the table currently being joined,
     #   the table alias/name for the last joined (or first table), and an array of previous
     #   SQL::JoinClause. Unlike +filter+, this block is not treated as a virtual row block.
+    #
+    # Examples:
+    #
+    #   DB[:a].join_table(:cross, :b)
+    #   # SELECT * FROM a CROSS JOIN b
+    #
+    #   DB[:a].join_table(:inner, DB[:b], :c=>d)
+    #   # SELECT * FROM a INNER JOIN (SELECT * FROM b) AS t1 ON (t1.c = a.d)
+    #
+    #   DB[:a].join_table(:left, :b___c, [:d])
+    #   # SELECT * FROM a LEFT JOIN b AS c USING (d)
+    #
+    #   DB[:a].natural_join(:b).join_table(:inner, :c) do |ta, jta, js|
+    #     (:d.qualify(ta) > :e.qualify(jta)) & {:f.qualify(ta)=>DB.from(js.first.table).select(:g)}
+    #   end
+    #   # SELECT * FROM a NATURAL JOIN b INNER JOIN c
+    #   #   ON ((c.d > b.e) AND (c.f IN (SELECT g FROM b)))
     def join_table(type, table, expr=nil, options={}, &block)
       using_join = expr.is_a?(Array) && !expr.empty? && expr.all?{|x| x.is_a?(Symbol)}
       if using_join && !supports_join_using?
@@ -591,7 +612,7 @@ module Sequel
       @opts[:order] ? ds.order_more(*@opts[:order]) : ds
     end
     
-    # Qualify to the given table, or first source if not table is given.
+    # Qualify to the given table, or first source if no table is given.
     #
     #   DB[:items].filter(:id=>1).qualify
     #   # SELECT items.* FROM items WHERE (items.id = 1)
@@ -718,7 +739,7 @@ module Sequel
     end
     
     # Set the server for this dataset to use.  Used to pick a specific database
-    # shard to run a query against, or to override the default (which is SELECT uses
+    # shard to run a query against, or to override the default (where SELECT uses
     # :read_only database and all other queries use the :default database).  This
     # method is always available but is only useful when database sharding is being
     # used.
@@ -790,8 +811,8 @@ module Sequel
     # :all :: Set to true to use UNION ALL instead of UNION, so duplicate rows can occur
     # :from_self :: Set to false to not wrap the returned dataset in a from_self, use with care.
     #
-    #   DB[:items].union(DB[:other_items]).sql
-    #   #=> "SELECT * FROM items UNION SELECT * FROM other_items"
+    #   DB[:items].union(DB[:other_items])
+    #   # SELECT * FROM (SELECT * FROM items UNION SELECT * FROM other_items) AS t1
     #
     #   DB[:items].union(DB[:other_items], :all=>true, :from_self=>false)
     #   # SELECT * FROM items UNION ALL SELECT * FROM other_items

data/lib/sequel/dataset/sql.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: User Methods relating to SQL Creation
+    # :section: 3 - User Methods relating to SQL Creation
     # These are methods you can call to see what SQL will be generated by the dataset.
     # ---------------------
     
@@ -163,7 +163,7 @@ module Sequel
     end
     
     # ---------------------
-    # :section: Internal Methods relating to SQL Creation
+    # :section: 9 - Internal Methods relating to SQL Creation
     # These methods, while public, are not designed to be used directly by the end user.
     # ---------------------
     

data/lib/sequel/extensions/migration.rb

@@ -2,6 +2,7 @@
 # the user to easily group schema changes and migrate the database
 # to a newer version or revert to a previous version.
 
+#
 module Sequel
   # Sequel's older migration class, available for backward compatibility.
   # Uses subclasses with up and down instance methods for each migration:

data/lib/sequel/model.rb

@@ -49,10 +49,11 @@ module Sequel
   # called directly on the class.  Model datasets return rows as model instances,
   # which have fairly standard ORM instance behavior.
   #
-  # <tt>Sequel::Model</tt> is built completely out of plugins, the only method not part of a
-  # plugin is the plugin method itself.  Plugins can override any class, instance, or
-  # dataset method defined by a previous plugin and call super to get the default
-  # behavior.
+  # <tt>Sequel::Model</tt> is built completely out of plugins.  Plugins can override any class,
+  # instance, or dataset method defined by a previous plugin and call super to get the default
+  # behavior.  By default, <tt>Sequel::Model</tt> loads two plugins, <tt>Sequel::Model</tt>
+  # (which is itself a plugin) for the base support, and <tt>Sequel::Model::Associations</tt>
+  # for the associations support.
   #
   # You can set the +SEQUEL_NO_ASSOCIATIONS+ constant or environment variable to
   # make Sequel not load the associations plugin by default.

data/lib/sequel/model/associations.rb

@@ -472,161 +472,165 @@ module Sequel
         # Associates a related model with the current model. The following types are
         # supported:
         #
-        # * :many_to_one - Foreign key in current model's table points to 
-        #   associated model's primary key.  Each associated model object can
-        #   be associated with more than one current model objects.  Each current
-        #   model object can be associated with only one associated model object.
-        # * :one_to_many - Foreign key in associated model's table points to this
-        #   model's primary key.   Each current model object can be associated with
-        #   more than one associated model objects.  Each associated model object
-        #   can be associated with only one current model object.
-        # * :one_to_one - Similar to one_to_many in terms of foreign keys, but
-        #   only one object is associated to the current object through the
-        #   association.  The methods created are similar to many_to_one, except
-        #   that the one_to_one setter method saves the passed object.
-        # * :many_to_many - A join table is used that has a foreign key that points
-        #   to this model's primary key and a foreign key that points to the
-        #   associated model's primary key.  Each current model object can be
-        #   associated with many associated model objects, and each associated
-        #   model object can be associated with many current model objects.
+        # :many_to_one :: Foreign key in current model's table points to 
+        #                 associated model's primary key.  Each associated model object can
+        #                 be associated with more than one current model objects.  Each current
+        #                 model object can be associated with only one associated model object.
+        # :one_to_many :: Foreign key in associated model's table points to this
+        #                 model's primary key.   Each current model object can be associated with
+        #                 more than one associated model objects.  Each associated model object
+        #                 can be associated with only one current model object.
+        # :one_to_one :: Similar to one_to_many in terms of foreign keys, but
+        #                only one object is associated to the current object through the
+        #                association.  The methods created are similar to many_to_one, except
+        #                that the one_to_one setter method saves the passed object.
+        # :many_to_many :: A join table is used that has a foreign key that points
+        #                  to this model's primary key and a foreign key that points to the
+        #                  associated model's primary key.  Each current model object can be
+        #                  associated with many associated model objects, and each associated
+        #                  model object can be associated with many current model objects.
         #
         # The following options can be supplied:
-        # * *ALL types*:
-        #   - :after_add - Symbol, Proc, or array of both/either specifying a callback to call
-        #     after a new item is added to the association.
-        #   - :after_load - Symbol, Proc, or array of both/either specifying a callback to call
-        #     after the associated record(s) have been retrieved from the database.  Not called
-        #     when eager loading via eager_graph, but called when eager loading via eager.
-        #   - :after_remove - Symbol, Proc, or array of both/either specifying a callback to call
-        #     after an item is removed from the association.
-        #   - :after_set - Symbol, Proc, or array of both/either specifying a callback to call
-        #     after an item is set using the association setter method.
-        #   - :allow_eager - If set to false, you cannot load the association eagerly
-        #     via eager or eager_graph
-        #   - :before_add - Symbol, Proc, or array of both/either specifying a callback to call
-        #     before a new item is added to the association.
-        #   - :before_remove - Symbol, Proc, or array of both/either specifying a callback to call
-        #     before an item is removed from the association.
-        #   - :before_set - Symbol, Proc, or array of both/either specifying a callback to call
-        #     before an item is set using the association setter method.
-        #   - :cartesian_product_number - the number of joins completed by this association that could cause more
-        #     than one row for each row in the current table (default: 0 for many_to_one and one_to_one associations,
-        #     1 for one_to_many and many_to_many associations).
-        #   - :class - The associated class or its name. If not
-        #     given, uses the association's name, which is camelized (and
-        #     singularized unless the type is :many_to_one or :one_to_one)
-        #   - :clone - Merge the current options and block into the options and block used in defining
-        #     the given association.  Can be used to DRY up a bunch of similar associations that
-        #     all share the same options such as :class and :key, while changing the order and block used.
-        #   - :conditions - The conditions to use to filter the association, can be any argument passed to filter.
-        #   - :dataset - A proc that is instance_evaled to get the base dataset
-        #     to use for the _dataset method (before the other options are applied).
-        #   - :distinct - Use the DISTINCT clause when selecting associating object, both when
-        #     lazy loading and eager loading via .eager (but not when using .eager_graph).
-        #   - :eager - The associations to eagerly load via +eager+ when loading the associated object(s).
-        #   - :eager_block - If given, use the block instead of the default block when
-        #     eagerly loading.  To not use a block when eager loading (when one is used normally),
-        #     set to nil.
-        #   - :eager_graph - The associations to eagerly load via +eager_graph+ when loading the associated object(s).
-        #   - :eager_grapher - A proc to use to implement eager loading via +eager_graph+, overriding the default.
-        #     Takes one or three arguments. If three arguments, they are a dataset, an alias to use for
-        #     the table to graph for this association, and the alias that was used for the current table
-        #     (since you can cascade associations). If one argument, is passed a hash with keys :self,
-        #     :table_alias, and :implicit_qualifier, corresponding to the three arguments, and an optional
-        #     additional key :eager_block, a callback accepting one argument, the associated dataset. This
-        #     is used to customize the association at query time.
-        #     Should return a copy of the dataset with the association graphed into it.
-        #   - :eager_loader - A proc to use to implement eager loading, overriding the default.  Takes one or three arguments.
-        #     If three arguments, the first should be a key hash (used solely to enhance performance), the second an array of records,
-        #     and the third a hash of dependent associations. If one argument, is passed a hash with keys :key_hash,
-        #     :rows, and :associations, corresponding to the three arguments, and an additional key :self, which is
-        #     the dataset doing the eager loading. In the proc, the associated records should
-        #     be queried from the database and the associations cache for each
-        #     record should be populated.
-        #   - :eager_loader_key - A symbol for the key column to use to populate the key hash
-        #     for the eager loader.
-        #   - :extend - A module or array of modules to extend the dataset with.
-        #   - :graph_block - The block to pass to join_table when eagerly loading
-        #     the association via +eager_graph+.
-        #   - :graph_conditions - The additional conditions to use on the SQL join when eagerly loading
-        #     the association via +eager_graph+.  Should be a hash or an array of two element arrays. If not
-        #     specified, the :conditions option is used if it is a hash or array of two element arrays.
-        #   - :graph_join_type - The type of SQL join to use when eagerly loading the association via
-        #     eager_graph.  Defaults to :left_outer.
-        #   - :graph_only_conditions - The conditions to use on the SQL join when eagerly loading
-        #     the association via +eager_graph+, instead of the default conditions specified by the
-        #     foreign/primary keys.  This option causes the :graph_conditions option to be ignored.
-        #   - :graph_select - A column or array of columns to select from the associated table
-        #     when eagerly loading the association via +eager_graph+. Defaults to all
-        #     columns in the associated table.
-        #   - :limit - Limit the number of records to the provided value.  Use
-        #     an array with two elements for the value to specify a limit (first element) and an offset (second element).
-        #   - :methods_module - The module that methods the association creates will be placed into. Defaults
-        #     to the module containing the model's columns.
-        #   - :order - the column(s) by which to order the association dataset.  Can be a
-        #     singular column symbol or an array of column symbols.
-        #   - :order_eager_graph - Whether to add the association's order to the graphed dataset's order when graphing
-        #     via +eager_graph+.  Defaults to true, so set to false to disable.
-        #   - :read_only - Do not add a setter method (for many_to_one or one_to_one associations),
-        #     or add_/remove_/remove_all_ methods (for one_to_many and many_to_many associations).
-        #   - :reciprocal - the symbol name of the reciprocal association,
-        #     if it exists.  By default, Sequel will try to determine it by looking at the
-        #     associated model's assocations for a association that matches
-        #     the current association's key(s).  Set to nil to not use a reciprocal.
-        #   - :select - the columns to select.  Defaults to the associated class's
-        #     table_name.* in a many_to_many association, which means it doesn't include the attributes from the
-        #     join table.  If you want to include the join table attributes, you can
-        #     use this option, but beware that the join table attributes can clash with
-        #     attributes from the model table, so you should alias any attributes that have
-        #     the same name in both the join table and the associated table.
-        #   - :validate - Set to false to not validate when implicitly saving any associated object.
-        # * :many_to_one:
-        #   - :key - foreign_key in current model's table that references
-        #     associated model's primary key, as a symbol.  Defaults to :"#{name}_id".  Can use an
-        #     array of symbols for a composite key association.
-        #   - :primary_key - column in the associated table that :key option references, as a symbol.
-        #     Defaults to the primary key of the associated table. Can use an
-        #     array of symbols for a composite key association.
-        # * :one_to_many and :one_to_one:
-        #   - :key - foreign key in associated model's table that references
-        #     current model's primary key, as a symbol.  Defaults to
-        #     :"#{self.name.underscore}_id".  Can use an
-        #     array of symbols for a composite key association.
-        #   - :primary_key - column in the current table that :key option references, as a symbol.
-        #     Defaults to primary key of the current table. Can use an
-        #     array of symbols for a composite key association.
-        # * :many_to_many:
-        #   - :graph_join_table_block - The block to pass to +join_table+ for
-        #     the join table when eagerly loading the association via +eager_graph+.
-        #   - :graph_join_table_conditions - The additional conditions to use on the SQL join for
-        #     the join table when eagerly loading the association via +eager_graph+. Should be a hash
-        #     or an array of two element arrays.
-        #   - :graph_join_table_join_type - The type of SQL join to use for the join table when eagerly
-        #     loading the association via +eager_graph+.  Defaults to the :graph_join_type option or
-        #     :left_outer.
-        #   - :graph_join_table_only_conditions - The conditions to use on the SQL join for the join
-        #     table when eagerly loading the association via +eager_graph+, instead of the default
-        #     conditions specified by the foreign/primary keys.  This option causes the 
-        #     :graph_join_table_conditions option to be ignored.
-        #   - :join_table - name of table that includes the foreign keys to both
-        #     the current model and the associated model, as a symbol.  Defaults to the name
-        #     of current model and name of associated model, pluralized,
-        #     underscored, sorted, and joined with '_'.
-        #   - :join_table_block - proc that can be used to modify the dataset used in the add/remove/remove_all
-        #     methods.  Should accept a dataset argument and return a modified dataset if present.
-        #   - :left_key - foreign key in join table that points to current model's
-        #     primary key, as a symbol. Defaults to :"#{self.name.underscore}_id".  
-        #     Can use an array of symbols for a composite key association.
-        #   - :left_primary_key - column in current table that :left_key points to, as a symbol.
-        #     Defaults to primary key of current table.  Can use an
-        #     array of symbols for a composite key association.
-        #   - :right_key - foreign key in join table that points to associated
-        #     model's primary key, as a symbol.  Defaults to Defaults to :"#{name.to_s.singularize}_id".
-        #     Can use an array of symbols for a composite key association.
-        #   - :right_primary_key - column in associated table that :right_key points to, as a symbol.
-        #     Defaults to primary key of the associated table.  Can use an
-        #     array of symbols for a composite key association.
-        #   - :uniq - Adds a after_load callback that makes the array of objects unique.
+        # === All Types
+        # :after_add :: Symbol, Proc, or array of both/either specifying a callback to call
+        #               after a new item is added to the association.
+        # :after_load :: Symbol, Proc, or array of both/either specifying a callback to call
+        #                after the associated record(s) have been retrieved from the database.  Not called
+        #                when eager loading via eager_graph, but called when eager loading via eager.
+        # :after_remove :: Symbol, Proc, or array of both/either specifying a callback to call
+        #                  after an item is removed from the association.
+        # :after_set :: Symbol, Proc, or array of both/either specifying a callback to call
+        #               after an item is set using the association setter method.
+        # :allow_eager :: If set to false, you cannot load the association eagerly
+        #                 via eager or eager_graph
+        # :before_add :: Symbol, Proc, or array of both/either specifying a callback to call
+        #                before a new item is added to the association.
+        # :before_remove :: Symbol, Proc, or array of both/either specifying a callback to call
+        #                   before an item is removed from the association.
+        # :before_set :: Symbol, Proc, or array of both/either specifying a callback to call
+        #                before an item is set using the association setter method.
+        # :cartesian_product_number :: the number of joins completed by this association that could cause more
+        #                              than one row for each row in the current table (default: 0 for
+        #                              many_to_one and one_to_one associations, 1 for one_to_many and
+        #                              many_to_many associations).
+        # :class :: The associated class or its name. If not
+        #           given, uses the association's name, which is camelized (and
+        #           singularized unless the type is :many_to_one or :one_to_one)
+        # :clone :: Merge the current options and block into the options and block used in defining
+        #           the given association.  Can be used to DRY up a bunch of similar associations that
+        #            all share the same options such as :class and :key, while changing the order and block used.
+        # :conditions :: The conditions to use to filter the association, can be any argument passed to filter.
+        # :dataset :: A proc that is instance_evaled to get the base dataset
+        #             to use for the _dataset method (before the other options are applied).
+        # :distinct :: Use the DISTINCT clause when selecting associating object, both when
+        #              lazy loading and eager loading via .eager (but not when using .eager_graph).
+        # :eager :: The associations to eagerly load via +eager+ when loading the associated object(s).
+        # :eager_block :: If given, use the block instead of the default block when
+        #                 eagerly loading.  To not use a block when eager loading (when one is used normally),
+        #                 set to nil.
+        # :eager_graph :: The associations to eagerly load via +eager_graph+ when loading the associated object(s).
+        #                 many_to_many associations with this option cannot be eagerly loaded via +eager+.
+        # :eager_grapher :: A proc to use to implement eager loading via +eager_graph+, overriding the default.
+        #                   Takes one or three arguments. If three arguments, they are a dataset, an alias to use for
+        #                   the table to graph for this association, and the alias that was used for the current table
+        #                   (since you can cascade associations). If one argument, is passed a hash with keys :self,
+        #                   :table_alias, and :implicit_qualifier, corresponding to the three arguments, and an optional
+        #                   additional key :eager_block, a callback accepting one argument, the associated dataset. This
+        #                   is used to customize the association at query time.
+        #                   Should return a copy of the dataset with the association graphed into it.
+        # :eager_loader :: A proc to use to implement eager loading, overriding the default.  Takes one or three arguments.
+        #                  If three arguments, the first should be a key hash (used solely to enhance performance), the
+        #                  second an array of records, and the third a hash of dependent associations. If one argument, is
+        #                  passed a hash with keys :key_hash, :rows, and :associations, corresponding to the three
+        #                  arguments, and an additional key :self, which is the dataset doing the eager loading. In the
+        #                  proc, the associated records should be queried from the database and the associations cache for
+        #                  each record should be populated.
+        # :eager_loader_key :: A symbol for the key column to use to populate the key hash
+        #                      for the eager loader.
+        # :extend :: A module or array of modules to extend the dataset with.
+        # :graph_block :: The block to pass to join_table when eagerly loading
+        #                 the association via +eager_graph+.
+        # :graph_conditions :: The additional conditions to use on the SQL join when eagerly loading
+        #                      the association via +eager_graph+.  Should be a hash or an array of two element arrays. If not
+        #                      specified, the :conditions option is used if it is a hash or array of two element arrays.
+        # :graph_join_type :: The type of SQL join to use when eagerly loading the association via
+        #                     eager_graph.  Defaults to :left_outer.
+        # :graph_only_conditions :: The conditions to use on the SQL join when eagerly loading
+        #                           the association via +eager_graph+, instead of the default conditions specified by the
+        #                           foreign/primary keys.  This option causes the :graph_conditions option to be ignored.
+        # :graph_select :: A column or array of columns to select from the associated table
+        #                  when eagerly loading the association via +eager_graph+. Defaults to all
+        #                  columns in the associated table.
+        # :limit :: Limit the number of records to the provided value.  Use
+        #           an array with two elements for the value to specify a
+        #           limit (first element) and an offset (second element).
+        # :methods_module :: The module that methods the association creates will be placed into. Defaults
+        #                    to the module containing the model's columns.
+        # :order :: the column(s) by which to order the association dataset.  Can be a
+        #           singular column symbol or an array of column symbols.
+        # :order_eager_graph :: Whether to add the association's order to the graphed dataset's order when graphing
+        #                       via +eager_graph+.  Defaults to true, so set to false to disable.
+        # :read_only :: Do not add a setter method (for many_to_one or one_to_one associations),
+        #               or add_/remove_/remove_all_ methods (for one_to_many and many_to_many associations).
+        # :reciprocal :: the symbol name of the reciprocal association,
+        #                if it exists.  By default, Sequel will try to determine it by looking at the
+        #                associated model's assocations for a association that matches
+        #                the current association's key(s).  Set to nil to not use a reciprocal.
+        # :select :: the columns to select.  Defaults to the associated class's
+        #            table_name.* in a many_to_many association, which means it doesn't include the attributes from the
+        #            join table.  If you want to include the join table attributes, you can
+        #            use this option, but beware that the join table attributes can clash with
+        #            attributes from the model table, so you should alias any attributes that have
+        #            the same name in both the join table and the associated table.
+        # :validate :: Set to false to not validate when implicitly saving any associated object.
+        # === :many_to_one
+        # :key :: foreign key in current model's table that references
+        #         associated model's primary key, as a symbol.  Defaults to :"#{name}_id".  Can use an
+        #         array of symbols for a composite key association.
+        # :primary_key :: column in the associated table that :key option references, as a symbol.
+        #                 Defaults to the primary key of the associated table. Can use an
+        #                 array of symbols for a composite key association.
+        # === :one_to_many and :one_to_one
+        # :key :: foreign key in associated model's table that references
+        #         current model's primary key, as a symbol.  Defaults to
+        #         :"#{self.name.underscore}_id".  Can use an
+        #         array of symbols for a composite key association.
+        # :primary_key :: column in the current table that :key option references, as a symbol.
+        #                 Defaults to primary key of the current table. Can use an
+        #                 array of symbols for a composite key association.
+        # === :many_to_many
+        # :graph_join_table_block :: The block to pass to +join_table+ for
+        #                            the join table when eagerly loading the association via +eager_graph+.
+        # :graph_join_table_conditions :: The additional conditions to use on the SQL join for
+        #                                 the join table when eagerly loading the association via +eager_graph+.
+        #                                 Should be a hash or an array of two element arrays.
+        # :graph_join_table_join_type :: The type of SQL join to use for the join table when eagerly
+        #                                loading the association via +eager_graph+.  Defaults to the
+        #                                :graph_join_type option or :left_outer.
+        # :graph_join_table_only_conditions :: The conditions to use on the SQL join for the join
+        #                                      table when eagerly loading the association via +eager_graph+,
+        #                                      instead of the default conditions specified by the
+        #                                      foreign/primary keys.  This option causes the
+        #                                      :graph_join_table_conditions option to be ignored.
+        # :join_table :: name of table that includes the foreign keys to both
+        #                the current model and the associated model, as a symbol.  Defaults to the name
+        #                of current model and name of associated model, pluralized,
+        #                underscored, sorted, and joined with '_'.
+        # :join_table_block :: proc that can be used to modify the dataset used in the add/remove/remove_all
+        #                      methods.  Should accept a dataset argument and return a modified dataset if present.
+        # :left_key :: foreign key in join table that points to current model's
+        #              primary key, as a symbol. Defaults to :"#{self.name.underscore}_id".  
+        #              Can use an array of symbols for a composite key association.
+        # :left_primary_key :: column in current table that :left_key points to, as a symbol.
+        #                      Defaults to primary key of current table.  Can use an
+        #                      array of symbols for a composite key association.
+        # :right_key :: foreign key in join table that points to associated
+        #               model's primary key, as a symbol.  Defaults to Defaults to :"#{name.to_s.singularize}_id".
+        #               Can use an array of symbols for a composite key association.
+        # :right_primary_key :: column in associated table that :right_key points to, as a symbol.
+        #                       Defaults to primary key of the associated table.  Can use an
+        #                       array of symbols for a composite key association.
+        # :uniq :: Adds a after_load callback that makes the array of objects unique.
         def associate(type, name, opts = {}, &block)
           raise(Error, 'one_to_many association type with :one_to_one option removed, used one_to_one association type') if opts[:one_to_one] && type == :one_to_many
           raise(Error, 'invalid association type') unless assoc_class = ASSOCIATION_TYPES[type]
@@ -681,13 +685,13 @@ module Sequel
           ds = ds.eager(opts[:eager]) if opts[:eager]
           ds = ds.distinct if opts[:distinct]
           if opts[:eager_graph]
+            raise(Error, "cannot eagerly load a #{opts[:type]} association that uses :eager_graph") if opts.eager_loading_use_associated_key?
             ds = ds.eager_graph(opts[:eager_graph])
-            ds = ds.add_graph_aliases(opts.associated_key_alias=>[opts.associated_class.table_name, opts.associated_key_alias, SQL::QualifiedIdentifier.new(opts.associated_key_table, opts.associated_key_column)]) if opts.eager_loading_use_associated_key?
           end
           ds = ds.eager(associations) unless Array(associations).empty?
           ds = opts[:eager_block].call(ds) if opts[:eager_block]
           ds = eager_options[:eager_block].call(ds) if eager_options[:eager_block]
-          if !opts[:eager_graph] && opts.eager_loading_use_associated_key?
+          if opts.eager_loading_use_associated_key?
             ds = if opts[:uses_left_composite_keys]
               t = opts.associated_key_table
               ds.select_append(*opts.associated_key_alias.zip(opts.associated_key_column).map{|a, c| SQL::AliasedExpression.new(SQL::QualifiedIdentifier.new(t, c), a)})
@@ -704,22 +708,22 @@ module Sequel
           subclass.instance_variable_set(:@association_reflections, @association_reflections.dup)
         end
       
-        # Shortcut for adding a many_to_many association, see associate
+        # Shortcut for adding a many_to_many association, see #associate
         def many_to_many(name, opts={}, &block)
           associate(:many_to_many, name, opts, &block)
         end
         
-        # Shortcut for adding a many_to_one association, see associate
+        # Shortcut for adding a many_to_one association, see #associate
         def many_to_one(name, opts={}, &block)
           associate(:many_to_one, name, opts, &block)
         end
         
-        # Shortcut for adding a one_to_many association, see associate
+        # Shortcut for adding a one_to_many association, see #associate
         def one_to_many(name, opts={}, &block)
           associate(:one_to_many, name, opts, &block)
         end
 
-        # Shortcut for adding a one_to_one association, see associate.
+        # Shortcut for adding a one_to_one association, see #associate.
         def one_to_one(name, opts={}, &block)
           associate(:one_to_one, name, opts, &block)
         end
@@ -1285,7 +1289,7 @@ module Sequel
       # time, as it loads associated records using one query per association.  However,
       # it does not allow you the ability to filter or order based on columns in associated tables.  +eager_graph+ loads
       # all records in a single query using JOINs, allowing you to filter or order based on columns in associated
-      # tables.  However, +eager_graph+ can be slower than +eager+, especially if multiple
+      # tables.  However, +eager_graph+ is usually slower than +eager+, especially if multiple
       # one_to_many or many_to_many associations are joined.
       #
       # You can cascade the eager loading (loading associations on associated objects)
@@ -1330,6 +1334,56 @@ module Sequel
           obj.def_mutation_method(:eager, :eager_graph)
         end
       
+        # If the expression is in the form <tt>x = y</tt> where +y+ is a <tt>Sequel::Model</tt>
+        # instance, array of <tt>Sequel::Model</tt> instances, or a <tt>Sequel::Model</tt> dataset,
+        # assume +x+ is an association symbol and look up the association reflection
+        # via the dataset's model.  From there, return the appropriate SQL based on the type of
+        # association and the values of the foreign/primary keys of +y+.  For most association
+        # types, this is a simple transformation, but for +many_to_many+ associations this 
+        # creates a subquery to the join table.
+        def complex_expression_sql(op, args)
+          r = args.at(1)
+          if (((op == :'=' || op == :'!=') and r.is_a?(Sequel::Model)) ||
+              (multiple = ((op == :IN || op == :'NOT IN') and ((is_ds = r.is_a?(Sequel::Dataset)) or r.all?{|x| x.is_a?(Sequel::Model)}))))
+            l = args.at(0)
+            if ar = model.association_reflections[l]
+              if multiple
+                klass = ar.associated_class
+                if is_ds
+                  if r.respond_to?(:model)
+                    unless r.model <= klass
+                      # A dataset for a different model class, could be a valid regular query
+                      return super
+                    end
+                  else
+                    # Not a model dataset, could be a valid regular query
+                    return super
+                  end
+                else
+                  unless r.all?{|x| x.is_a?(klass)}
+                    raise Sequel::Error, "invalid association class for one object for association #{l.inspect} used in dataset filter for model #{model.inspect}, expected class #{klass.inspect}"
+                  end
+                end
+              elsif !r.is_a?(ar.associated_class)
+                raise Sequel::Error, "invalid association class #{r.class.inspect} for association #{l.inspect} used in dataset filter for model #{model.inspect}, expected class #{ar.associated_class.inspect}"
+              end
+
+              if exp = association_filter_expression(op, ar, r)
+                literal(exp)
+              else
+                raise Sequel::Error, "invalid association type #{ar[:type].inspect} for association #{l.inspect} used in dataset filter for model #{model.inspect}"
+              end
+            elsif multiple && (is_ds || r.empty?)
+              # Not a query designed for this support, could be a valid regular query
+              super
+            else
+              raise Sequel::Error, "invalid association #{l.inspect} used in dataset filter for model #{model.inspect}"
+            end
+          else
+            super
+          end
+        end
+
         # The preferred eager loading method.  Loads all associated records using one
         # query for each association.
         #
@@ -1376,9 +1430,9 @@ module Sequel
         # The secondary eager loading method.  Loads all associations in a single query. This
         # method should only be used if you need to filter or order based on columns in associated tables.
         #
-        # This method builds an object graph using <tt>Dataset#graph</tt>.  Then it uses the graph
-        # to build the associations, and finally replaces the graph with a simple array
-        # of model objects.
+        # This method uses <tt>Dataset#graph</tt> to create appropriate aliases for columns in all the
+        # tables.  Then it uses the graph's metadata to build the associations from the single hash, and
+        # finally replaces the array of hashes with an array model objects inside all.
         #
         # Be very careful when using this with multiple one_to_many or many_to_many associations, as you can
         # create large cartesian products.  If you must graph multiple one_to_many and many_to_many associations,
@@ -1392,8 +1446,7 @@ module Sequel
         # all objects.  You can use the :graph_* association options to modify the SQL query.
         #
         # Like +eager+, you need to call +all+ on the dataset for the eager loading to work.  If you just
-        # call +each+, you will get a normal graphed result back (a hash with table alias symbol keys and
-        # model object values).
+        # call +each+, it will yield plain hashes, each containing all columns from all the tables.
         def eager_graph(*associations)
           ds = if @opts[:eager_graph]
             self
@@ -1408,55 +1461,6 @@ module Sequel
           ds.eager_graph_associations(ds, model, ds.opts[:eager_graph][:master], [], *associations)
         end
         
-        # If the expression is in the form <tt>x = y</tt> where +y+ is a <tt>Sequel::Model</tt>
-        # instance, assume +x+ is an association symbol and look up the association reflection
-        # via the dataset's model.  From there, return the appropriate SQL based on the type of
-        # association and the values of the foreign/primary keys of +y+.  For most association
-        # types, this is a simple transformation, but for +many_to_many+ associations this 
-        # creates a subquery to the join table.
-        def complex_expression_sql(op, args)
-          r = args.at(1)
-          if (((op == :'=' || op == :'!=') and r.is_a?(Sequel::Model)) ||
-              (multiple = ((op == :IN || op == :'NOT IN') and ((is_ds = r.is_a?(Sequel::Dataset)) or r.all?{|x| x.is_a?(Sequel::Model)}))))
-            l = args.at(0)
-            if ar = model.association_reflections[l]
-              if multiple
-                klass = ar.associated_class
-                if is_ds
-                  if r.respond_to?(:model)
-                    unless r.model <= klass
-                      # A dataset for a different model class, could be a valid regular query
-                      return super
-                    end
-                  else
-                    # Not a model dataset, could be a valid regular query
-                    return super
-                  end
-                else
-                  unless r.all?{|x| x.is_a?(klass)}
-                    raise Sequel::Error, "invalid association class for one object for association #{l.inspect} used in dataset filter for model #{model.inspect}, expected class #{klass.inspect}"
-                  end
-                end
-              elsif !r.is_a?(ar.associated_class)
-                raise Sequel::Error, "invalid association class #{r.class.inspect} for association #{l.inspect} used in dataset filter for model #{model.inspect}, expected class #{ar.associated_class.inspect}"
-              end
-
-              if exp = association_filter_expression(op, ar, r)
-                literal(exp)
-              else
-                raise Sequel::Error, "invalid association type #{ar[:type].inspect} for association #{l.inspect} used in dataset filter for model #{model.inspect}"
-              end
-            elsif multiple && (is_ds || r.empty?)
-              # Not a query designed for this support, could be a valid regular query
-              super
-            else
-              raise Sequel::Error, "invalid association #{l.inspect} used in dataset filter for model #{model.inspect}"
-            end
-          else
-            super
-          end
-        end
-
         # Do not attempt to split the result set into associations,
         # just return results as simple objects.  This is useful if you
         # want to use eager_graph as a shortcut to have all of the joins
@@ -1506,7 +1510,7 @@ module Sequel
           ds = ds.eager_graph_associations(ds, r.associated_class, assoc_table_alias, requirements + [assoc_table_alias], *associations) unless associations.empty?
           ds
         end
-      
+
         # Check the associations are valid for the given model.
         # Call eager_graph_association on each association.
         #
@@ -1533,67 +1537,10 @@ module Sequel
           ds
         end
       
-        # Build associations out of the array of returned object graphs.
-        def eager_graph_build_associations(record_graphs)
-          eager_graph = @opts[:eager_graph]
-          master = eager_graph[:master]
-          requirements = eager_graph[:requirements]
-          alias_map = eager_graph[:alias_association_name_map]
-          type_map = eager_graph[:alias_association_type_map]
-          reciprocal_map = eager_graph[:reciprocals]
-      
-          # Make dependency map hash out of requirements array for each association.
-          # This builds a tree of dependencies that will be used for recursion
-          # to ensure that all parts of the object graph are loaded into the
-          # appropriate subordinate association.
-          dependency_map = {}
-          # Sort the associations by requirements length, so that
-          # requirements are added to the dependency hash before their
-          # dependencies.
-          requirements.sort_by{|a| a[1].length}.each do |ta, deps|
-            if deps.empty?
-              dependency_map[ta] = {}
-            else
-              deps = deps.dup
-              hash = dependency_map[deps.shift]
-              deps.each do |dep|
-                hash = hash[dep]
-              end
-              hash[ta] = {}
-            end
-          end
-      
-          # This mapping is used to make sure that duplicate entries in the
-          # result set are mapped to a single record.  For example, using a
-          # single one_to_many association with 10 associated records,
-          # the main object will appear in the object graph 10 times.
-          # We map by primary key, if available, or by the object's entire values,
-          # if not. The mapping must be per table, so create sub maps for each table
-          # alias.
-          records_map = {master=>{}}
-          alias_map.keys.each{|ta| records_map[ta] = {}}
-      
-          # This will hold the final record set that we will be replacing the object graph with.
-          records = []
-          record_graphs.each do |record_graph|
-            primary_record = record_graph[master]
-            key = primary_record.pk_or_nil || primary_record.values.sort_by{|x| x[0].to_s}
-            if cached_pr = records_map[master][key]
-              primary_record = cached_pr
-            else
-              records_map[master][key] = primary_record
-              # Only add it to the list of records to return if it is a new record
-              records.push(primary_record)
-            end
-            # Build all associations for the current object and it's dependencies
-            eager_graph_build_associations_graph(dependency_map, alias_map, type_map, reciprocal_map, records_map, primary_record, record_graph)
-          end
-      
-          # Remove duplicate records from all associations if this graph could possibly be a cartesian product
-          eager_graph_make_associations_unique(records, dependency_map, alias_map, type_map) if eager_graph[:cartesian_product_number] > 1
-          
-          # Replace the array of object graphs with an array of model objects
-          record_graphs.replace(records)
+        # Replace the array of plain hashes with an array of model objects will all eager_graphed
+        # associations set in the associations cache for each object.
+        def eager_graph_build_associations(hashes)
+          hashes.replace(EagerGraphLoader.new(self).load(hashes))
         end
       
         private
@@ -1648,57 +1595,6 @@ module Sequel
           reflection
         end
       
-        # Build associations for the current object.  This is called recursively
-        # to build all dependencies.
-        def eager_graph_build_associations_graph(dependency_map, alias_map, type_map, reciprocal_map, records_map, current, record_graph)
-          return if dependency_map.empty?
-          # Don't clobber the cached association value for one_to_many and many_to_many associations if it has already been setup
-          dependency_map.keys.each do |ta|
-            assoc_name = alias_map[ta]
-            current.associations[assoc_name] = type_map[ta] ? [] : nil unless current.associations.include?(assoc_name)
-          end
-          dependency_map.each do |ta, deps|
-            next unless rec = record_graph[ta]
-            key = rec.pk_or_nil || rec.values.sort_by{|x| x[0].to_s}
-            if cached_rec = records_map[ta][key]
-              rec = cached_rec
-            else
-              records_map[ta][key] = rec
-            end
-            assoc_name = alias_map[ta]
-            if type_map[ta]
-              current.associations[assoc_name].push(rec) 
-              if reciprocal = reciprocal_map[ta]
-                rec.associations[reciprocal] = current
-              end
-            else
-              current.associations[assoc_name] = rec
-            end
-            # Recurse into dependencies of the current object
-            eager_graph_build_associations_graph(deps, alias_map, type_map, reciprocal_map, records_map, rec, record_graph)
-          end
-        end
-      
-        # If the result set is the result of a cartesian product, then it is possible that
-        # there are multiple records for each association when there should only be one.
-        # In that case, for each object in all associations loaded via +eager_graph+, run
-        # uniq! on the association to make sure no duplicate records show up.
-        # Note that this can cause legitimate duplicate records to be removed.
-        def eager_graph_make_associations_unique(records, dependency_map, alias_map, type_map)
-          records.each do |record|
-            dependency_map.each do |ta, deps|
-              list = record.send(alias_map[ta])
-              list = if type_map[ta]
-                list.uniq!
-              else
-                [list] if list
-              end
-              # Recurse into dependencies
-              eager_graph_make_associations_unique(list, deps, alias_map, type_map) if list
-            end
-          end
-        end
-      
         # Eagerly load all specified associations 
         def eager_load(a, eager_assoc=@opts[:eager])
           return if a.empty?
@@ -1742,7 +1638,12 @@ module Sequel
             a.each{|object| object.send(:run_association_callbacks, r, :after_load, object.associations[r[:name]])} unless r[:after_load].empty?
           end 
         end
-      
+
+        # Return plain hashes instead of calling the row_proc if eager_graph is being used.
+        def graph_each(&block)
+          @opts[:eager_graph] ? fetch_rows(select_sql, &block) : super
+        end
+
         # Return a subquery expression for filering by a many_to_many association
         def many_to_many_association_filter_expression(op, ref, obj)
           lpks, lks, rks = ref.values_at(:left_primary_keys, :left_keys, :right_keys)
@@ -1776,6 +1677,264 @@ module Sequel
           super
         end
       end
+
+      # This class is the internal implementation of eager_graph.  It is responsible for taking an array of plain
+      # hashes and returning an array of model objects with all eager_graphed associations already set in the
+      # association cache.
+      class EagerGraphLoader
+        # Hash with table alias symbol keys and association name values
+        attr_reader :alias_map
+        
+        # Hash with table alias symbol keys and subhash values mapping column_alias symbols to the
+        # symbol of the real name of the column
+        attr_reader :column_maps
+        
+        # Recursive hash with table alias symbol keys mapping to hashes with dependent table alias symbol keys.
+        attr_reader :dependency_map
+        
+        # The table alias symbol for the primary model
+        attr_reader :master
+        
+        # Hash with table alias symbol keys and primary key symbol values (or arrays of primary key symbols for
+        # composite key tables)
+        attr_reader :primary_keys
+
+        # Hash with table alias symbol keys and reciprocal association symbol values,
+        # used for setting reciprocals for one_to_many associations.
+        attr_reader :reciprocal_map
+        
+        # Hash with table alias symbol keys and subhash values mapping primary key symbols (or array of symbols)
+        # to model instances.  Used so that only a single model instance is created for each object.
+        attr_reader :records_map
+        
+        # Hash with table alias symbol keys and callable values used to create model instances
+        attr_reader :row_procs
+        
+        # Hash with table alias symbol keys and true/false values, where true means the
+        # association represented by the table alias uses an array of values instead of
+        # a single value (i.e. true => *_many, false => *_to_one).
+        attr_reader :type_map
+
+        # Initialize all of the data structures used during loading.
+        def initialize(dataset)
+          opts = dataset.opts
+          eager_graph = opts[:eager_graph]
+          @master =  eager_graph[:master]
+          requirements = eager_graph[:requirements]
+          alias_map = @alias_map = eager_graph[:alias_association_name_map]
+          type_map = @type_map = eager_graph[:alias_association_type_map]
+          reciprocal_map = @reciprocal_map = eager_graph[:reciprocals]
+          @unique = eager_graph[:cartesian_product_number] > 1
+      
+          # Make dependency map hash out of requirements array for each association.
+          # This builds a tree of dependencies that will be used for recursion
+          # to ensure that all parts of the object graph are loaded into the
+          # appropriate subordinate association.
+          @dependency_map = {}
+          # Sort the associations by requirements length, so that
+          # requirements are added to the dependency hash before their
+          # dependencies.
+          requirements.sort_by{|a| a[1].length}.each do |ta, deps|
+            if deps.empty?
+              dependency_map[ta] = {}
+            else
+              deps = deps.dup
+              hash = dependency_map[deps.shift]
+              deps.each do |dep|
+                hash = hash[dep]
+              end
+              hash[ta] = {}
+            end
+          end
+      
+          # This mapping is used to make sure that duplicate entries in the
+          # result set are mapped to a single record.  For example, using a
+          # single one_to_many association with 10 associated records,
+          # the main object column values appear in the object graph 10 times.
+          # We map by primary key, if available, or by the object's entire values,
+          # if not. The mapping must be per table, so create sub maps for each table
+          # alias.
+          records_map = {@master=>{}}
+          alias_map.keys.each{|ta| records_map[ta] = {}}
+          @records_map = records_map
+
+          datasets = opts[:graph][:table_aliases].to_a.reject{|ta,ds| ds.nil?}
+          column_aliases = opts[:graph_aliases] || opts[:graph][:column_aliases]
+          primary_keys = {}
+          column_maps = {}
+          models = {}
+          row_procs = {}
+          datasets.each do |ta, ds|
+            models[ta] = ds.model
+            primary_keys[ta] = []
+            column_maps[ta] = {}
+            row_procs[ta] = ds.row_proc
+          end
+          column_aliases.each do |col_alias, tc|
+            ta, column = tc
+            column_maps[ta][col_alias] = column
+          end
+          column_maps.each do |ta, h|
+            pk = models[ta].primary_key
+            if pk.is_a?(Array)
+              primary_keys[ta] = []
+              h.select{|ca, c| primary_keys[ta] << ca if pk.include?(c)}
+            else
+              h.select{|ca, c| primary_keys[ta] = ca if pk == c}
+            end
+          end
+          @column_maps = column_maps
+          @primary_keys = primary_keys
+          @row_procs = row_procs
+
+          # For performance, create two special maps for the master table,
+          # so you can skip a hash lookup.
+          @master_column_map = column_maps[master]
+          @master_primary_keys = primary_keys[master]
+
+          # Add a special hash mapping table alias symbols to 5 element arrays that just
+          # contain the data in other data structures for that table alias.  This is
+          # used for performance, to get all values in one hash lookup instead of
+          # separate hash lookups for each data structure.
+          ta_map = {}
+          alias_map.keys.each do |ta|
+            ta_map[ta] = [records_map[ta], row_procs[ta], alias_map[ta], type_map[ta], reciprocal_map[ta]]
+          end
+          @ta_map = ta_map
+        end
+
+        # Return an array of primary model instances with the associations cache prepopulated
+        # for all model objects (both primary and associated).
+        def load(hashes)
+          master = master()
+      
+          # Assign to local variables for speed increase
+          rp = row_procs[master]
+          rm = records_map[master]
+          dm = dependency_map
+
+          # This will hold the final record set that we will be replacing the object graph with.
+          records = []
+
+          hashes.each do |h|
+            unless key = master_pk(h)
+              key = hkey(master_hfor(h))
+            end
+            unless primary_record = rm[key]
+              primary_record = rm[key] = rp.call(master_hfor(h))
+              # Only add it to the list of records to return if it is a new record
+              records.push(primary_record)
+            end
+            # Build all associations for the current object and it's dependencies
+            _load(dm, primary_record, h)
+          end
+      
+          # Remove duplicate records from all associations if this graph could possibly be a cartesian product
+          unique(records, dm) if @unique
+          
+          records
+        end
+      
+        private
+
+        # Recursive method that creates associated model objects and associates them to the current model object.
+        def _load(dependency_map, current, h)
+          dependency_map.each do |ta, deps|
+            unless key = pk(ta, h)
+              ta_h = hfor(ta, h)
+              unless ta_h.values.any?
+                assoc_name = alias_map[ta]
+                unless (assoc = current.associations).has_key?(assoc_name)
+                  assoc[assoc_name] = type_map[ta] ? [] : nil
+                end
+                next
+              end
+              key = hkey(ta_h)
+            end
+            rm, rp, assoc_name, tm, rcm = @ta_map[ta]
+            unless rec = rm[key]
+              rec = rm[key] = rp.call(hfor(ta, h))
+            end
+
+            if tm
+              unless (assoc = current.associations).has_key?(assoc_name)
+                assoc[assoc_name] = []
+              end
+              assoc[assoc_name].push(rec) 
+              rec.associations[rcm] = current if rcm
+            else
+              current.associations[assoc_name] = rec
+            end
+            # Recurse into dependencies of the current object
+            _load(deps, rec, h) unless deps.empty?
+          end
+        end
+      
+        # Return the subhash for the specific table alias +ta+ by parsing the values out of the main hash +h+
+        def hfor(ta, h)
+          out = {}
+          @column_maps[ta].each{|ca, c| out[c] = h[ca]}
+          out
+        end
+
+        # Return a suitable hash key for any subhash +h+, which is an array of values by column order.
+        # This is only used if the primary key cannot be used.
+        def hkey(h)
+          h.sort_by{|x| x[0].to_s}
+        end
+
+        # Return the subhash for the master table by parsing the values out of the main hash +h+
+        def master_hfor(h)
+          out = {}
+          @master_column_map.each{|ca, c| out[c] = h[ca]}
+          out
+        end
+
+        # Return a primary key value for the master table by parsing it out of the main hash +h+.
+        def master_pk(h)
+          x = @master_primary_keys
+          if x.is_a?(Array)
+            unless x == []
+              x = x.map{|ca| h[ca]}
+              x if x.all?
+            end
+          else
+            h[x]
+          end
+        end
+
+        # Return a primary key value for the given table alias by parsing it out of the main hash +h+.
+        def pk(ta, h)
+          x = primary_keys[ta]
+          if x.is_a?(Array)
+            unless x == []
+              x = x.map{|ca| h[ca]}
+              x if x.all?
+            end
+          else
+            h[x]
+          end
+        end
+
+        # If the result set is the result of a cartesian product, then it is possible that
+        # there are multiple records for each association when there should only be one.
+        # In that case, for each object in all associations loaded via +eager_graph+, run
+        # uniq! on the association to make sure no duplicate records show up.
+        # Note that this can cause legitimate duplicate records to be removed.
+        def unique(records, dependency_map)
+          records.each do |record|
+            dependency_map.each do |ta, deps|
+              list = record.send(alias_map[ta])
+              list = if type_map[ta]
+                list.uniq!
+                unique(list, deps) if !list.empty? && !deps.empty?
+              elsif list
+                unique([list], deps) unless deps.empty?
+              end
+            end
+          end
+        end
+      end
     end
   end
 end