sequel 3.21.0 → 3.28.0

data/lib/sequel/model/associations.rb

@@ -79,6 +79,27 @@ module Sequel
           true
         end
     
+        # The eager limit strategy to use for this dataset.
+        def eager_limit_strategy
+          fetch(:_eager_limit_strategy) do
+            self[:_eager_limit_strategy] = if self[:limit]
+              case s = self.fetch(:eager_limit_strategy){self[:model].default_eager_limit_strategy || :ruby}
+              when true
+                ds = associated_class.dataset
+                if ds.supports_window_functions?
+                  :window_function
+                else
+                  :ruby
+                end
+              else
+                s
+              end
+            else
+              nil
+            end
+          end
+        end
+
         # By default associations do not need to select a key in an associated table
         # to eagerly load.
         def eager_loading_use_associated_key?
@@ -92,6 +113,15 @@ module Sequel
           true
         end
     
+        # The limit and offset for this association (returned as a two element array).
+        def limit_and_offset
+          if (v = self[:limit]).is_a?(Array)
+            v
+          else
+            [v, nil]
+          end
+        end
+
         # Whether the associated object needs a primary key to be added/removed,
         # false by default.
         def need_associated_primary_key?
@@ -193,6 +223,11 @@ module Sequel
           self[:key].nil?
         end
     
+        # many_to_one associations don't need an eager limit strategy
+        def eager_limit_strategy
+          nil
+        end
+
         # The key to use for the key hash when eager loading
         def eager_loader_key
           self[:eager_loader_key] ||= self[:key]
@@ -248,7 +283,7 @@ module Sequel
         def can_have_associated_objects?(obj)
           !self[:primary_keys].any?{|k| obj.send(k).nil?}
         end
-    
+
         # Default foreign key name symbol for key in associated table that points to
         # current table's primary key.
         def default_key
@@ -259,6 +294,11 @@ module Sequel
         def eager_loader_key
           self[:eager_loader_key] ||= primary_key
         end
+
+        # The hash key to use for the eager loading predicate (left side of IN (1, 2, 3))
+        def eager_loading_predicate_key
+          self[:eager_loading_predicate_key] ||= self[:uses_composite_keys] ? self[:keys].map{|k| SQL::QualifiedIdentifier.new(associated_class.table_name, k)} : SQL::QualifiedIdentifier.new(associated_class.table_name, self[:key])
+        end
     
         # The column in the current table that the key in the associated table references.
         def primary_key
@@ -297,6 +337,31 @@ module Sequel
       class OneToOneAssociationReflection < OneToManyAssociationReflection
         ASSOCIATION_TYPES[:one_to_one] = self
         
+        # one_to_one associations don't use an eager limit strategy by default, but
+        # support both DISTINCT ON and window functions as strategies.
+        def eager_limit_strategy
+          fetch(:_eager_limit_strategy) do
+            self[:_eager_limit_strategy] = case s = self[:eager_limit_strategy]
+            when Symbol
+              s
+            when true
+              ds = associated_class.dataset
+              if ds.supports_ordered_distinct_on?
+                :distinct_on
+              elsif ds.supports_window_functions?
+                :window_function
+              end
+            else
+              nil
+            end
+          end
+        end
+
+        # The limit and offset for this association (returned as a two element array).
+        def limit_and_offset
+          [1, nil]
+        end
+
         # one_to_one associations return a single object, not an array
         def returns_array?
           false
@@ -362,6 +427,11 @@ module Sequel
           self[:eager_loader_key] ||= self[:left_primary_key]
         end
     
+        # The hash key to use for the eager loading predicate (left side of IN (1, 2, 3))
+        def eager_loading_predicate_key
+          self[:eager_loading_predicate_key] ||= self[:uses_left_composite_keys] ? self[:left_keys].map{|k| SQL::QualifiedIdentifier.new(self[:join_table], k)} : SQL::QualifiedIdentifier.new(self[:join_table], self[:left_key])
+        end
+    
         # many_to_many associations need to select a key in an associated table to eagerly load
         def eager_loading_use_associated_key?
           true
@@ -457,6 +527,12 @@ module Sequel
       #   Project.association_reflection(:portfolio)
       #   => {:type => :many_to_one, :name => :portfolio, ...}
       #
+      # Associations should not have the same names as any of the columns in the
+      # model's current table they reference. If you are dealing with an existing schema that
+      # has a column named status, you can't name the association status, you'd
+      # have to name it foo_status or something else.  If you give an association the same name
+      # as a column, you will probably end up with an association that doesn't work, or a SystemStackError.
+      #
       # For a more in depth general overview, as well as a reference guide,
       # see the {Association Basics guide}[link:files/doc/association_basics_rdoc.html].
       # For examples of advanced usage, see the {Advanced Associations guide}[link:files/doc/advanced_associations_rdoc.html].
@@ -464,6 +540,9 @@ module Sequel
         # All association reflections defined for this model (default: {}).
         attr_reader :association_reflections
 
+        # The default :eager_limit_strategy option to use for *_many associations (default: nil)
+        attr_accessor :default_eager_limit_strategy
+
         # Array of all association reflections for this model class
         def all_association_reflections
           association_reflections.values
@@ -472,163 +551,179 @@ 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 three arguments, 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),
-        #     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.
+        # :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_limit_strategy :: Determines the strategy used for enforcing limits when eager loading associations via
+        #                          the +eager+ method.  For one_to_one associations, no strategy is used by default, and
+        #                          for *_many associations, the :ruby strategy is used by default, which still retrieves
+        #                          all records but slices the resulting array after the association is retrieved.  You
+        #                          can pass a +true+ value for this option to have Sequel pick what it thinks is the best
+        #                          choice for the database, or specify a specific symbol to manually select a strategy.
+        #                          one_to_one associations support :distinct_on, :window_function, and :correlated_subquery.
+        #                          *_many associations support :ruby, :window_function, and :correlated_subquery.
+        # :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]
           raise(Error, 'Model.associate name argument must be a symbol') unless Symbol === name
           raise(Error, ':eager_loader option must have an arity of 1 or 3') if opts[:eager_loader] && ![1, 3].include?(opts[:eager_loader].arity)
-      
+          raise(Error, ':eager_grapher option must have an arity of 1 or 3') if opts[:eager_grapher] && ![1, 3].include?(opts[:eager_grapher].arity)
+
           # dup early so we don't modify opts
           orig_opts = opts.dup
           orig_opts = association_reflection(opts[:clone])[:orig_opts].merge(orig_opts) if opts[:clone]
@@ -676,49 +771,119 @@ 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?
-          elsif 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_loading_use_associated_key?
             ds = if opts[:uses_left_composite_keys]
               t = opts.associated_key_table
-              ds.select_more(*opts.associated_key_alias.zip(opts.associated_key_column).map{|a, c| SQL::AliasedExpression.new(SQL::QualifiedIdentifier.new(t, c), a)})
+              ds.select_append(*opts.associated_key_alias.zip(opts.associated_key_column).map{|a, c| SQL::AliasedExpression.new(SQL::QualifiedIdentifier.new(t, c), a)})
             else
-              ds.select_more(SQL::AliasedExpression.new(SQL::QualifiedIdentifier.new(opts.associated_key_table, opts.associated_key_column), opts.associated_key_alias)) 
+              ds.select_append(SQL::AliasedExpression.new(SQL::QualifiedIdentifier.new(opts.associated_key_table, opts.associated_key_column), opts.associated_key_alias))
             end
           end
-          ds = ds.eager(associations) unless Array(associations).empty?
-          ds = opts[:eager_block].call(ds) if opts[:eager_block]
           ds
         end
 
         # Copy the association reflections to the subclass
         def inherited(subclass)
           super
-          subclass.instance_variable_set(:@association_reflections, @association_reflections.dup)
+          subclass.instance_variable_set(:@association_reflections, association_reflections.dup)
+          subclass.default_eager_limit_strategy =  default_eager_limit_strategy
         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
         
         private
       
+        # Use a correlated subquery to limit the results of the eager loading dataset.
+        def apply_correlated_subquery_eager_limit_strategy(ds, opts)
+          klass = opts.associated_class
+          kds = klass.dataset
+          dsa = ds.send(:dataset_alias, 1)
+          raise Error, "can't use a correlated subquery if the associated class (#{opts.associated_class.inspect}) does not have a primary key" unless pk = klass.primary_key
+          pka = Array(pk)
+          raise Error, "can't use a correlated subquery if the associated class (#{opts.associated_class.inspect}) has a composite primary key and the database does not support multiple column IN" if pka.length > 1 && !ds.supports_multiple_column_in?
+          table = kds.opts[:from]
+          raise Error, "can't use a correlated subquery unless the associated class (#{opts.associated_class.inspect}) uses a single FROM table" unless table && table.length == 1
+          table = table.first
+          if order = ds.opts[:order]
+            oproc = lambda do |x|
+              case x
+              when Symbol
+                t, c, a = ds.send(:split_symbol, x)
+                if t && t.to_sym == table
+                  SQL::QualifiedIdentifier.new(dsa, c)
+                else
+                  x
+                end
+              when SQL::QualifiedIdentifier
+                if x.table == table
+                  SQL::QualifiedIdentifier.new(dsa, x.column)
+                else
+                  x
+                end
+              when SQL::OrderedExpression
+                SQL::OrderedExpression.new(oproc.call(x.expression), x.descending, :nulls=>x.nulls)
+              else
+                x
+              end
+            end
+            order = order.map(&oproc) 
+          end
+          limit, offset = opts.limit_and_offset
+
+          subquery = yield kds.
+            unlimited.
+            from(SQL::AliasedExpression.new(table, dsa)).
+            select(*pka.map{|k| SQL::QualifiedIdentifier.new(dsa, k)}).
+            order(*order).
+            limit(limit, offset)
+
+          pk = if pk.is_a?(Array)
+            pk.map{|k| SQL::QualifiedIdentifier.new(table, k)}
+          else
+            SQL::QualifiedIdentifier.new(table, pk)
+          end
+          ds.filter(pk=>subquery)
+        end
+
+        # Use a window function to limit the results of the eager loading dataset.
+        def apply_window_function_eager_limit_strategy(ds, opts)
+          rn = ds.row_number_column 
+          limit, offset = opts.limit_and_offset
+          ds = ds.unordered.select_append{row_number(:over, :partition=>opts.eager_loading_predicate_key, :order=>ds.opts[:order]){}.as(rn)}.from_self
+          ds = if opts[:type] == :one_to_one
+            ds.where(rn => 1)
+          elsif offset
+            offset += 1
+            ds.where(rn => (offset...(offset+limit))) 
+          else
+            ds.where{SQL::Identifier.new(rn) <= limit} 
+          end
+        end
+
         # The module to use for the association's methods.  Defaults to
         # the overridable_methods_module.
         def association_module(opts={})
@@ -753,9 +918,20 @@ module Sequel
           def_association_method(opts)
         end
 
-        # Adds the association method to the association methods module. 
-        def def_association_method(opts)
-          association_module_def(opts.association_method, opts){|*reload| load_associated_objects(opts, reload[0])}
+        # Adds the association method to the association methods module. Be backwards
+        # compatible with ruby 1.8.6, which doesn't support blocks taking block arguments.
+        if RUBY_VERSION >= '1.8.7'
+          class_eval <<-END, __FILE__, __LINE__+1
+            def def_association_method(opts)
+              association_module_def(opts.association_method, opts){|*dynamic_opts, &block| load_associated_objects(opts, dynamic_opts[0], &block)}
+            end
+          END
+        else
+          class_eval <<-END, __FILE__, __LINE__+1
+            def def_association_method(opts)
+              association_module_def(opts.association_method, opts){|*dynamic_opts| load_associated_objects(opts, dynamic_opts[0])}
+            end
+          END
         end
       
         # Configures many_to_many association reflection and adds the related association methods
@@ -782,14 +958,27 @@ module Sequel
           opts[:graph_join_table_join_type] ||= opts[:graph_join_type]
           opts[:after_load].unshift(:array_uniq!) if opts[:uniq]
           opts[:dataset] ||= proc{opts.associated_class.inner_join(join_table, rcks.zip(opts.right_primary_keys) + lcks.zip(lcpks.map{|k| send(k)}))}
-          database = db
-          
+
           opts[:eager_loader] ||= proc do |eo|
             h = eo[:key_hash][left_pk]
-            eo[:rows].each{|object| object.associations[name] = []}
+            rows = eo[:rows]
+            rows.each{|object| object.associations[name] = []}
             r = uses_rcks ? rcks.zip(opts.right_primary_keys) : [[right, opts.right_primary_key]]
             l = uses_lcks ? [[lcks.map{|k| SQL::QualifiedIdentifier.new(join_table, k)}, h.keys]] : [[left, h.keys]]
-            model.eager_loading_dataset(opts, opts.associated_class.inner_join(join_table, r + l), Array(opts.select), eo[:associations], eo).all do |assoc_record|
+            ds = model.eager_loading_dataset(opts, opts.associated_class.inner_join(join_table, r + l), Array(opts.select), eo[:associations], eo)
+            case opts.eager_limit_strategy
+            when :window_function
+              delete_rn = true
+              rn = ds.row_number_column
+              ds = apply_window_function_eager_limit_strategy(ds, opts)
+            when :correlated_subquery
+              ds = apply_correlated_subquery_eager_limit_strategy(ds, opts) do |xds|
+                dsa = ds.send(:dataset_alias, 2)
+                xds.inner_join(join_table, r + lcks.map{|k| [k, SQL::QualifiedIdentifier.new(join_table, k)]}, :table_alias=>dsa)
+              end
+            end
+            ds.all do |assoc_record|
+              assoc_record.values.delete(rn) if delete_rn
               hash_key = if uses_lcks
                 left_key_alias.map{|k| assoc_record.values.delete(k)}
               else
@@ -798,6 +987,10 @@ module Sequel
               next unless objects = h[hash_key]
               objects.each{|object| object.associations[name].push(assoc_record)}
             end
+            if opts.eager_limit_strategy == :ruby
+              limit, offset = opts.limit_and_offset
+              rows.each{|o| o.associations[name] = o.associations[name].slice(offset||0, limit) || []}
+            end
           end
           
           join_type = opts[:graph_join_type]
@@ -810,9 +1003,10 @@ module Sequel
           jt_only_conditions = opts[:graph_join_table_only_conditions]
           jt_join_type = opts[:graph_join_table_join_type]
           jt_graph_block = opts[:graph_join_table_block]
-          opts[:eager_grapher] ||= proc do |ds, assoc_alias, table_alias|
-            ds = ds.graph(join_table, use_jt_only_conditions ? jt_only_conditions : lcks.zip(lcpks) + graph_jt_conds, :select=>false, :table_alias=>ds.unused_table_alias(join_table), :join_type=>jt_join_type, :implicit_qualifier=>table_alias, :from_self_alias=>ds.opts[:eager_graph][:master], &jt_graph_block)
-            ds.graph(opts.associated_class, use_only_conditions ? only_conditions : opts.right_primary_keys.zip(rcks) + conditions, :select=>select, :table_alias=>assoc_alias, :join_type=>join_type, &graph_block)
+          opts[:eager_grapher] ||= proc do |eo|
+            ds = eo[:self]
+            ds = ds.graph(join_table, use_jt_only_conditions ? jt_only_conditions : lcks.zip(lcpks) + graph_jt_conds, :select=>false, :table_alias=>ds.unused_table_alias(join_table), :join_type=>jt_join_type, :implicit_qualifier=>eo[:implicit_qualifier], :from_self_alias=>ds.opts[:eager_graph][:master], &jt_graph_block)
+            ds.graph(eager_graph_dataset(opts, eo), use_only_conditions ? only_conditions : opts.right_primary_keys.zip(rcks) + conditions, :select=>select, :table_alias=>eo[:table_alias], :join_type=>join_type, &graph_block)
           end
       
           def_association_dataset_methods(opts)
@@ -876,8 +1070,9 @@ module Sequel
           only_conditions = opts[:graph_only_conditions]
           conditions = opts[:graph_conditions]
           graph_block = opts[:graph_block]
-          opts[:eager_grapher] ||= proc do |ds, assoc_alias, table_alias|
-            ds.graph(opts.associated_class, use_only_conditions ? only_conditions : opts.primary_keys.zip(cks) + conditions, :select=>select, :table_alias=>assoc_alias, :join_type=>join_type, :implicit_qualifier=>table_alias, :from_self_alias=>ds.opts[:eager_graph][:master], &graph_block)
+          opts[:eager_grapher] ||= proc do |eo|
+            ds = eo[:self]
+            ds.graph(eager_graph_dataset(opts, eo), use_only_conditions ? only_conditions : opts.primary_keys.zip(cks) + conditions, eo.merge(:select=>select, :join_type=>join_type, :from_self_alias=>ds.opts[:eager_graph][:master]), &graph_block)
           end
       
           def_association_dataset_methods(opts)
@@ -905,20 +1100,38 @@ module Sequel
           end
           opts[:eager_loader] ||= proc do |eo|
             h = eo[:key_hash][primary_key]
+            rows = eo[:rows]
             if one_to_one
-              eo[:rows].each{|object| object.associations[name] = nil}
+              rows.each{|object| object.associations[name] = nil}
             else
-              eo[:rows].each{|object| object.associations[name] = []}
+              rows.each{|object| object.associations[name] = []}
             end
             reciprocal = opts.reciprocal
             klass = opts.associated_class
-            model.eager_loading_dataset(opts, klass.filter(uses_cks ? {cks.map{|k| SQL::QualifiedIdentifier.new(klass.table_name, k)}=>h.keys} : {SQL::QualifiedIdentifier.new(klass.table_name, key)=>h.keys}), opts.select, eo[:associations], eo).all do |assoc_record|
+            filter_keys = opts.eager_loading_predicate_key
+            ds = model.eager_loading_dataset(opts, klass.filter(filter_keys=>h.keys), opts.select, eo[:associations], eo)
+            case opts.eager_limit_strategy
+            when :distinct_on
+              ds = ds.distinct(*filter_keys).order_prepend(*filter_keys)
+            when :window_function
+              delete_rn = true
+              rn = ds.row_number_column
+              ds = apply_window_function_eager_limit_strategy(ds, opts)
+            when :correlated_subquery
+              ds = apply_correlated_subquery_eager_limit_strategy(ds, opts) do |xds|
+                xds.where(opts.associated_object_keys.map{|k| [SQL::QualifiedIdentifier.new(xds.first_source_alias, k), SQL::QualifiedIdentifier.new(xds.first_source_table, k)]})
+              end
+            end
+            ds.all do |assoc_record|
+              assoc_record.values.delete(rn) if delete_rn
               hash_key = uses_cks ? cks.map{|k| assoc_record.send(k)} : assoc_record.send(key)
               next unless objects = h[hash_key]
               if one_to_one
                 objects.each do |object| 
-                  object.associations[name] = assoc_record
-                  assoc_record.associations[reciprocal] = object if reciprocal
+                  unless object.associations[name]
+                    object.associations[name] = assoc_record
+                    assoc_record.associations[reciprocal] = object if reciprocal
+                  end
                 end
               else
                 objects.each do |object| 
@@ -927,6 +1140,10 @@ module Sequel
                 end
               end
             end
+            if opts.eager_limit_strategy == :ruby
+              limit, offset = opts.limit_and_offset
+              rows.each{|o| o.associations[name] = o.associations[name].slice(offset||0, limit) || []}
+            end
           end
           
           join_type = opts[:graph_join_type]
@@ -936,10 +1153,11 @@ module Sequel
           conditions = opts[:graph_conditions]
           opts[:cartesian_product_number] ||= one_to_one ? 0 : 1
           graph_block = opts[:graph_block]
-          opts[:eager_grapher] ||= proc do |ds, assoc_alias, table_alias|
-            ds = ds.graph(opts.associated_class, use_only_conditions ? only_conditions : cks.zip(cpks) + conditions, :select=>select, :table_alias=>assoc_alias, :join_type=>join_type, :implicit_qualifier=>table_alias, :from_self_alias=>ds.opts[:eager_graph][:master], &graph_block)
+          opts[:eager_grapher] ||= proc do |eo|
+            ds = eo[:self]
+            ds = ds.graph(eager_graph_dataset(opts, eo), use_only_conditions ? only_conditions : cks.zip(cpks) + conditions, eo.merge(:select=>select, :join_type=>join_type, :from_self_alias=>ds.opts[:eager_graph][:master]), &graph_block)
             # We only load reciprocals for one_to_many associations, as other reciprocals don't make sense
-            ds.opts[:eager_graph][:reciprocals][assoc_alias] = opts.reciprocal
+            ds.opts[:eager_graph][:reciprocals][eo[:table_alias]] = opts.reciprocal
             ds
           end
       
@@ -993,6 +1211,15 @@ module Sequel
           association_module_def(opts.remove_method, opts){|o,*args| remove_associated_object(opts, o, *args)}
           association_module_def(opts.remove_all_method, opts){|*args| remove_all_associated_objects(opts, *args)}
         end
+
+        # Return dataset to graph into given the association reflection, applying the :callback option if set.
+        def eager_graph_dataset(opts, eager_options)
+          ds = opts.associated_class.dataset
+          if cb = eager_options[:callback]
+            ds = cb.call(ds)
+          end
+          ds
+        end
       end
 
       # Instance methods used to implement the associations support.
@@ -1004,8 +1231,8 @@ module Sequel
           @associations ||= {}
         end
       
-        # Used internally by the associations code, like pk but doesn't raise
-        # an Error if the model has no primary key.
+        # Formally used internally by the associations code, like pk but doesn't raise
+        # an Error if the model has no primary key.  Not used any longer, deprecated.
         def pk_or_nil
           key = primary_key
           key.is_a?(Array) ? key.map{|k| @values[k]} : @values[key]
@@ -1033,6 +1260,15 @@ module Sequel
           ds
         end
 
+        # Return a dataset for the association after applying any dynamic callback.
+        def _associated_dataset(opts, dynamic_opts)
+          ds = send(opts.dataset_method)
+          if callback = dynamic_opts[:callback]
+            ds = callback.call(ds)
+          end
+          ds
+        end
+        
         # Return an association dataset for the given association reflection
         def _dataset(opts)
           raise(Sequel::Error, "model object #{inspect} does not have a primary key") if opts.dataset_need_primary_key? && !pk
@@ -1045,13 +1281,14 @@ module Sequel
           opts[:join_table_block] ? opts[:join_table_block].call(ds) : ds
         end
 
-        # Return the associated objects from the dataset, without callbacks, reciprocals, and caching.
-        def _load_associated_objects(opts)
+        # Return the associated objects from the dataset, without association callbacks, reciprocals, and caching.
+        # Still apply the dynamic callback if present.
+        def _load_associated_objects(opts, dynamic_opts={})
           if opts.returns_array?
-            opts.can_have_associated_objects?(self) ? send(opts.dataset_method).all : []
+            opts.can_have_associated_objects?(self) ? _associated_dataset(opts, dynamic_opts).all : []
           else
             if opts.can_have_associated_objects?(self)
-              send(opts.dataset_method).all.first
+              _associated_dataset(opts, dynamic_opts).all.first
             end
           end
         end
@@ -1113,13 +1350,20 @@ module Sequel
         end
 
         # Load the associated objects using the dataset, handling callbacks, reciprocals, and caching.
-        def load_associated_objects(opts, reload=false)
+        def load_associated_objects(opts, dynamic_opts=nil)
+          if dynamic_opts == true or dynamic_opts == false or dynamic_opts == nil
+            dynamic_opts = {:reload=>dynamic_opts}
+          elsif dynamic_opts.respond_to?(:call)
+            dynamic_opts = {:callback=>dynamic_opts}
+          end
+          if block_given?
+            dynamic_opts = dynamic_opts.merge(:callback=>Proc.new)
+          end
           name = opts[:name]
-          if associations.include?(name) and !reload
+          if associations.include?(name) and !dynamic_opts[:callback] and !dynamic_opts[:reload]
             associations[name]
           else
-            objs = _load_associated_objects(opts)
-            run_association_callbacks(opts, :after_load, objs)
+            objs = _load_associated_objects(opts, dynamic_opts)
             if opts.set_reciprocal_to_self?
               if opts.returns_array?
                 objs.each{|o| add_reciprocal_object(opts, o)}
@@ -1128,6 +1372,8 @@ module Sequel
               end
             end
             associations[name] = objs
+            run_association_callbacks(opts, :after_load, objs)
+            associations[name]
           end
         end
 
@@ -1238,7 +1484,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)
@@ -1259,12 +1505,80 @@ module Sequel
       #   Artist.eager_graph(:albums=>:tracks).all
       #   Artist.eager(:albums=>{:tracks=>:genre}).all
       #   Artist.eager_graph(:albums=>{:tracks=>:genre}).all
+      #
+      # You can also pass a callback as a hash value in order to customize the dataset being
+      # eager loaded at query time, analogous to the way the :eager_block association option
+      # allows you to customize it at association definition time. For example,
+      # if you wanted artists with their albums since 1990:
+      #
+      #   Artist.eager(:albums => proc{|ds| ds.filter{year > 1990}})
+      #
+      # Or if you needed albums and their artist's name only, using a single query:
+      #
+      #   Albums.eager_graph(:artist => proc{|ds| ds.select(:name)})
+      #
+      # To cascade eager loading while using a callback, you substitute the cascaded
+      # associations with a single entry hash that has the proc callback as the key and 
+      # the cascaded associations as the value.  This will load artists with their albums
+      # since 1990, and also the tracks on those albums and the genre for those tracks:
+      #
+      #   Artist.eager(:albums => {proc{|ds| ds.filter{year > 1990}}=>{:tracks => :genre}})
       module DatasetMethods
         # Add the <tt>eager!</tt> and <tt>eager_graph!</tt> mutation methods to the dataset.
         def self.extended(obj)
           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.
         #
@@ -1311,9 +1625,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,
@@ -1327,18 +1641,16 @@ 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
           else
             # Each of the following have a symbol key for the table alias, with the following values: 
             # :reciprocals - the reciprocal instance variable to use for this association
+            # :reflections - AssociationReflection instance related to this association
             # :requirements - array of requirements for this association
-            # :alias_association_type_map - the type of association for this association
-            # :alias_association_name_map - the name of the association for this association
-            clone(:eager_graph=>{:requirements=>{}, :master=>alias_symbol(first_source), :alias_association_type_map=>{}, :alias_association_name_map=>{}, :reciprocals=>{}, :cartesian_product_number=>0})
+            clone(:eager_graph=>{:requirements=>{}, :master=>alias_symbol(first_source), :reflections=>{}, :reciprocals=>{}, :cartesian_product_number=>0})
           end
           ds.eager_graph_associations(ds, model, ds.opts[:eager_graph][:master], [], *associations)
         end
@@ -1366,20 +1678,32 @@ module Sequel
         # r :: association reflection for the current association
         # *associations :: any associations dependent on this one
         def eager_graph_association(ds, model, ta, requirements, r, *associations)
-          klass = r.associated_class
           assoc_name = r[:name]
           assoc_table_alias = ds.unused_table_alias(assoc_name)
-          ds = r[:eager_grapher].call(ds, assoc_table_alias, ta)
+          loader = r[:eager_grapher]
+          if !associations.empty?
+            if associations.first.respond_to?(:call)
+              callback = associations.first
+              associations = {}
+            elsif associations.length == 1 && (assocs = associations.first).is_a?(Hash) && assocs.length == 1 && (pr_assoc = assocs.to_a.first) && pr_assoc.first.respond_to?(:call)
+              callback, assoc = pr_assoc
+              associations = assoc.is_a?(Array) ? assoc : [assoc]
+            end
+          end
+          ds = if loader.arity == 1
+            loader.call(:self=>ds, :table_alias=>assoc_table_alias, :implicit_qualifier=>ta, :callback=>callback)
+          else
+            loader.call(ds, assoc_table_alias, ta)
+          end
           ds = ds.order_more(*qualified_expression(r[:order], assoc_table_alias)) if r[:order] and r[:order_eager_graph]
           eager_graph = ds.opts[:eager_graph]
           eager_graph[:requirements][assoc_table_alias] = requirements.dup
-          eager_graph[:alias_association_name_map][assoc_table_alias] = assoc_name
-          eager_graph[:alias_association_type_map][assoc_table_alias] = r.returns_array?
+          eager_graph[:reflections][assoc_table_alias] = r
           eager_graph[:cartesian_product_number] += r[:cartesian_product_number] || 2
           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.
         #
@@ -1406,20 +1730,220 @@ 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]
+        # 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
+      
+        # Return an expression for filtering by the given association reflection and associated object.
+        def association_filter_expression(op, ref, obj)
+          meth = :"#{ref[:type]}_association_filter_expression"
+          send(meth, op, ref, obj) if respond_to?(meth, true)
+        end
+
+        # Handle inversion for association filters by returning an inverted expression,
+        # plus also handling cases where the referenced columns are NULL.
+        def association_filter_handle_inversion(op, exp, cols)
+          if op == :'!=' || op == :'NOT IN'
+            if exp == SQL::Constants::FALSE
+              ~exp
+            else
+              ~exp | Sequel::SQL::BooleanExpression.from_value_pairs(cols.zip([]), :OR)
+            end
+          else
+            exp
+          end
+        end
+
+        # Return an expression for making sure that the given keys match the value of
+        # the given methods for either the single object given or for any of the objects
+        # given if +obj+ is an array.
+        def association_filter_key_expression(keys, meths, obj)
+          vals = if obj.is_a?(Sequel::Dataset)
+            {(keys.length == 1 ? keys.first : keys)=>obj.select(*meths).exclude(Sequel::SQL::BooleanExpression.from_value_pairs(meths.zip([]), :OR))}
+          else
+            vals = Array(obj).reject{|o| !meths.all?{|m| o.send(m)}}
+            return SQL::Constants::FALSE if vals.empty?
+            if obj.is_a?(Array)
+              if keys.length == 1
+                meth = meths.first
+                {keys.first=>vals.map{|o| o.send(meth)}}
+              else
+                {keys=>vals.map{|o| meths.map{|m| o.send(m)}}}
+              end  
+            else
+              keys.zip(meths.map{|k| obj.send(k)})
+            end
+          end
+          SQL::BooleanExpression.from_value_pairs(vals)
+        end
+
+        # Make sure the association is valid for this model, and return the related AssociationReflection.
+        def check_association(model, association)
+          raise(Sequel::UndefinedAssociation, "Invalid association #{association} for #{model.name}") unless reflection = model.association_reflection(association)
+          raise(Sequel::Error, "Eager loading is not allowed for #{model.name} association #{association}") if reflection[:allow_eager] == false
+          reflection
+        end
+      
+        # Eagerly load all specified associations 
+        def eager_load(a, eager_assoc=@opts[:eager])
+          return if a.empty?
+          # Key is foreign/primary key name symbol
+          # Value is hash with keys being foreign/primary key values (generally integers)
+          #  and values being an array of current model objects with that
+          #  specific foreign/primary key
+          key_hash = {}
+          # Reflections for all associations to eager load
+          reflections = eager_assoc.keys.collect{|assoc| model.association_reflection(assoc) || (raise Sequel::UndefinedAssociation, "Model: #{self}, Association: #{assoc}")}
+      
+          # Populate keys to monitor
+          reflections.each{|reflection| key_hash[reflection.eager_loader_key] ||= Hash.new{|h,k| h[k] = []}}
+          
+          # Associate each object with every key being monitored
+          a.each do |rec|
+            key_hash.each do |key, id_map|
+              case key
+              when Array
+                id_map[key.map{|k| rec[k]}] << rec if key.all?{|k| rec[k]}
+              when Symbol
+                id_map[rec[key]] << rec if rec[key]
+              end
+            end
+          end
+          
+          reflections.each do |r|
+            loader = r[:eager_loader]
+            associations = eager_assoc[r[:name]]
+            if associations.respond_to?(:call)
+              eager_block = associations
+              associations = {}
+            elsif associations.is_a?(Hash) && associations.length == 1 && (pr_assoc = associations.to_a.first) && pr_assoc.first.respond_to?(:call)
+              eager_block, associations = pr_assoc
+            end
+            if loader.arity == 1
+              loader.call(:key_hash=>key_hash, :rows=>a, :associations=>associations, :self=>self, :eager_block=>eager_block)
+            else
+              loader.call(key_hash, a, associations)
+            end
+            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)
+          lpks = lpks.first if lpks.length == 1
+          exp = association_filter_key_expression(rks, ref.right_primary_keys, obj)
+          if exp == SQL::Constants::FALSE
+            association_filter_handle_inversion(op, exp, Array(lpks))
+          else
+            association_filter_handle_inversion(op, SQL::BooleanExpression.from_value_pairs(lpks=>model.db[ref[:join_table]].select(*lks).where(exp).exclude(SQL::BooleanExpression.from_value_pairs(lks.zip([]), :OR))), Array(lpks))
+          end
+        end
+
+        # Return a simple equality expression for filering by a many_to_one association
+        def many_to_one_association_filter_expression(op, ref, obj)
+          keys = ref[:keys]
+          association_filter_handle_inversion(op, association_filter_key_expression(keys, ref.primary_keys, obj), keys)
+        end
+
+        # Return a simple equality expression for filering by a one_to_* association
+        def one_to_many_association_filter_expression(op, ref, obj)
+          keys = ref[:primary_keys]
+          association_filter_handle_inversion(op, association_filter_key_expression(keys, ref[:keys], obj), keys)
+        end
+        alias one_to_one_association_filter_expression one_to_many_association_filter_expression
+
+        # Build associations from the graph if #eager_graph was used, 
+        # and/or load other associations if #eager was used.
+        def post_load(all_records)
+          eager_graph_build_associations(all_records) if @opts[:eager_graph]
+          eager_load(all_records) if @opts[:eager]
+          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 after_load hook values
+        attr_reader :after_load_map
+        
+        # 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
+        
+        # Hash with table alias symbol keys and [limit, offset] values
+        attr_reader :limit_map
+        
+        # Hash with table alias symbol keys and callable values used to create model instances
+        # 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 AssociationReflection values
+        attr_reader :reflection_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 = eager_graph[:alias_association_name_map]
-          type_map = eager_graph[:alias_association_type_map]
-          reciprocal_map = eager_graph[:reciprocals]
+          reflection_map = @reflection_map = eager_graph[:reflections]
+          reciprocal_map = @reciprocal_map = eager_graph[:reciprocals]
+          @unique = eager_graph[:cartesian_product_number] > 1
       
+          alias_map = @alias_map = {}
+          type_map = @type_map = {}
+          after_load_map = @after_load_map = {}
+          limit_map = @limit_map = {}
+          reflection_map.each do |k, v|
+            alias_map[k] = v[:name]
+            type_map[k] = v.returns_array?
+            after_load_map[k] = v[:after_load] unless v[:after_load].empty?
+            limit_map[k] = v.limit_and_offset if v[:limit]
+          end
+
           # 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 = {}
+          @dependency_map = {}
           # Sort the associations by requirements length, so that
           # requirements are added to the dependency hash before their
           # dependencies.
@@ -1439,139 +1963,199 @@ module Sequel
           # 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.
+          # 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=>{}}
+          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 = []
-          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
+
+          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
-            eager_graph_build_associations_graph(dependency_map, alias_map, type_map, reciprocal_map, records_map, primary_record, record_graph)
+            _load(dm, primary_record, h)
           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)
+          # Run after_load procs if there are any
+          post_process(records, dm) if @unique || !after_load_map.empty? || !limit_map.empty?
+
+          records
         end
       
         private
-      
-        # Make sure the association is valid for this model, and return the related AssociationReflection.
-        def check_association(model, association)
-          raise(Sequel::UndefinedAssociation, "Invalid association #{association} for #{model.name}") unless reflection = model.association_reflection(association)
-          raise(Sequel::Error, "Eager loading is not allowed for #{model.name} association #{association}") if reflection[:allow_eager] == false
-          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
+
+        # 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|
-            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
+            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
-            assoc_name = alias_map[ta]
-            if type_map[ta]
-              current.associations[assoc_name].push(rec) 
-              if reciprocal = reciprocal_map[ta]
-                rec.associations[reciprocal] = current
+
+            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
+              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)
+            _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 eager_graph_make_associations_unique(records, dependency_map, alias_map, type_map)
+        def post_process(records, dependency_map)
           records.each do |record|
             dependency_map.each do |ta, deps|
-              list = record.send(alias_map[ta])
-              list = if type_map[ta]
+              assoc_name = alias_map[ta]
+              list = record.send(assoc_name)
+              rec_list = if type_map[ta]
                 list.uniq!
+                if lo = limit_map[ta]
+                  limit, offset = lo
+                  list.replace(list[offset||0, limit])
+                end
+                list
+              elsif list
+                [list]
               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?
-          # Key is foreign/primary key name symbol
-          # Value is hash with keys being foreign/primary key values (generally integers)
-          #  and values being an array of current model objects with that
-          #  specific foreign/primary key
-          key_hash = {}
-          # Reflections for all associations to eager load
-          reflections = eager_assoc.keys.collect{|assoc| model.association_reflection(assoc) || (raise Sequel::UndefinedAssociation, "Model: #{self}, Association: #{assoc}")}
-      
-          # Populate keys to monitor
-          reflections.each{|reflection| key_hash[reflection.eager_loader_key] ||= Hash.new{|h,k| h[k] = []}}
-          
-          # Associate each object with every key being monitored
-          a.each do |rec|
-            key_hash.each do |key, id_map|
-              case key
-              when Array
-                id_map[key.map{|k| rec[k]}] << rec if key.all?{|k| rec[k]}
-              when Symbol
-                id_map[rec[key]] << rec if rec[key]
+                []
               end
+              record.send(:run_association_callbacks, reflection_map[ta], :after_load, list) if after_load_map[ta]
+              post_process(rec_list, deps) if !rec_list.empty? && !deps.empty?
             end
           end
-          
-          reflections.each do |r|
-            loader = r[:eager_loader]
-            if loader.arity == 1
-              loader.call(:key_hash=>key_hash, :rows=>a, :associations=>eager_assoc[r[:name]], :self=>self)
-            else
-              loader.call(key_hash, a, eager_assoc[r[:name]])
-            end
-            a.each{|object| object.send(:run_association_callbacks, r, :after_load, object.associations[r[:name]])} unless r[:after_load].empty?
-          end 
-        end
-      
-        # Build associations from the graph if #eager_graph was used, 
-        # and/or load other associations if #eager was used.
-        def post_load(all_records)
-          eager_graph_build_associations(all_records) if @opts[:eager_graph]
-          eager_load(all_records) if @opts[:eager]
-          super
         end
       end
     end