sequel 4.7.0 → 4.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c36878b92e104f343cc1e7c92ff6e94026040c1
-  data.tar.gz: ee7e4399243acbbfa11e6f427fedb49684b2426f
+  metadata.gz: 6c96550377e172f2fe1bbca889e66dbf6f4ba2ea
+  data.tar.gz: 09b5f64bdd1e48a538caf87c359f0196c5cecf87
 SHA512:
-  metadata.gz: faea6910ec5976db18b931961ed086cd295560a7ea54227b9af0811ecb98e75d61ba34899bf0d762c67182dea1be980daf339cce65aad1e9fe06eb7365c43f84
-  data.tar.gz: d3f3b358199a9f624387f2218074b2d01e39e9a295504dc988dbb8e792155af32e26ac17ca5bbfd95fc3c2d5b7fc084edeab90fa0123b0c673952ec048d0d574
+  metadata.gz: d089308d0d6ae3643cd8d84d6a67ad2f130dbafc8bafc1d0432c6ce0e0f496f50c76fed0db3a503a82afc889be9ba7c5639f971b763d1a0b9def6867939ac743
+  data.tar.gz: 11bcfe87e96fbd8c61b336994cd142ceec0d0fe5964ab94ea4d2886e7304843180377c488515d2f87dcaf9839974d988c9805c3872baecc5e7f9c373ea2d70fc

data/CHANGELOG

@@ -1,3 +1,49 @@
+=== 4.8.0 (2014-03-01)
+
+* Add SQL::AliasedExpression#alias alias for #aliaz (jeremyevans)
+
+* Handle SQL::Identifier, SQL::QualifiedIdentifier, and SQL::AliasedExpression objects as first argument to Dataset#graph (jeremyevans)
+
+* Respect qualification and aliases in symbols passed as first argument to Dataset#graph (dividedmind) (#769)
+
+* Recognize new constraint violation error messages in SQLite 3.8.2+ (itswindtw) (#766)
+
+* Use limit strategy to correctly handle limited associations in the dataset_associations plugin (jeremyevans)
+
+* Handle issues in dataset_associations plugin when dataset uses unqualified identifiers for associations requiring joins (jeremyevans)
+
+* Handle fractional seconds in input timestamps in the odbc/mssql adapter (Ross Attrill, jeremyevans)
+
+* Return fractional seconds in timestamps in the odbc adapter (jeremyevans)
+
+* Support :plain and :phrase options to Dataset#full_text_search on PostgreSQL (jeremyevans)
+
+* Use limit strategy to correctly handle filtering by limited associations (jeremyevans)
+
+* Simplify queries used for filtering by associations with conditions (jeremyevans)
+
+* Use an eager limit strategy by default for *_one associations with orders (jeremyevans)
+
+* Support :limit_strategy eager_graph option, for specifying strategy used for limited associations in that eager graph (jeremyevans)
+
+* Add eager_graph_with_options to model datasets, for specifying options specific to the eager_graph call (jeremyevans)
+
+* Handle offsets on *_many associations when eager graphing when there are no associated results (jeremyevans)
+
+* Make Database#register_array_type work without existing scalar conversion proc in the pg_array extension (jeremyevans)
+
+* Handle presence validations on foreign keys in associated objects when creating new associated objects in the nested_attributes plugin (jeremyevans)
+
+* Respect offsets when eager graphing *_one associations (jeremyevans)
+
+* Add association_join to model datasets, for setting up joins based on associations (jeremyevans)
+
+* Add one_through_many association to many_through_many plugin, for only returning a single record (jeremyevans)
+
+* Add :graph_order association option, useful when :order needs to contain qualified identifiers (jeremyevans)
+
+* Add one_through_one association, similar to many_to_many but only returning a single record (jeremyevans)
+
 === 4.7.0 (2014-02-01)
 
 * Don't swallow underlying exception if there is an exception closing the cursor on PostgreSQL (jeremyevans) (#761)

data/README.rdoc

@@ -639,12 +639,14 @@ SQL query.
 
 === Associations
 
-Associations are used in order to specify relationships between model classes that reflect relationships between tables in the database, which are usually specified using foreign keys.  You specify model associations via the +many_to_one+, +one_to_one+, +one_to_many+, and +many_to_many+ class methods:
+Associations are used in order to specify relationships between model classes that reflect relationships between tables in the database, which are usually specified using foreign keys.  You specify model associations via class methods:
 
   class Post < Sequel::Model
     many_to_one :author
     one_to_many :comments
+    one_to_one :first_comment, :class=>:Comment, :order=>:id
     many_to_many :tags
+    one_through_one :first_tag, :class=>:Tag, :order=>:name, :right_key=>:tag_id
   end
 
 +many_to_one+ and +one_to_one+ create a getter and setter for each model object:
@@ -745,6 +747,28 @@ You can dynamically customize eager loads for both +eager+ and +eager_graph+ whi
   # Eagerly load only replies containing 'foo', and the person and tags for those replies
   Post.eager(:replies=>{proc{|ds| ds.where(Sequel.like(text, '%foo%'))}=>[:person, :tags]}).all
 
+=== Joining with Associations
+
+You can use the association_join method to add a join to the model's dataset based on the assocation:
+
+  Post.association_join(:author)
+  # SELECT * FROM posts
+  # INNER JOIN authors AS author ON (author.id = posts.author_id)
+
+This comes with variants for different join types:
+
+  Post.association_left_join(:replies)
+  # SELECT * FROM posts
+  # LEFT JOIN replies ON (replies.post_id = posts.id)
+
+Similar to the eager loading methods, you can use multiple associations and nested associations:
+
+  Post.association_join(:author, :replies=>:person).all
+  # SELECT * FROM posts
+  # INNER JOIN authors AS author ON (author.id = posts.author_id)
+  # INNER JOIN replies ON (replies.post_id = posts.id)
+  # INNER JOIN people AS person ON (person.id = replies.person_id)
+
 === Extending the underlying dataset
 
 The recommended way to implement table-wide logic by defining methods on the dataset using +dataset_module+:

data/doc/active_record.rdoc

@@ -396,7 +396,7 @@ ActiveRecord option :: Sequel option
 <tt>:polymorphic</tt>, <tt>:as</tt>, <tt>:source_type</tt> :: The +sequel_polymorphic+ external plugin
 <tt>:include</tt> :: <tt>:eager</tt>, <tt>:eager_graph</tt>
 <tt>:readonly</tt> :: No equivalent, the Sequel <tt>:read_only</tt> option just means the modification methods are not created (it makes the association read only, not records retrieved through the association)
-<tt>:through</tt>, <tt>:source</tt> :: Use a +many_to_many+ association, or the +many_through_many+ plugin
+<tt>:through</tt>, <tt>:source</tt> :: Use a +many_to_many+ or +one_through_one+ association, or the +many_through_many+ plugin
 <tt>:touch</tt> :: The +touch+ plugin
 <tt>:autosave</tt> :: A +before_save+ or +after_save+ hook
 <tt>:finder_sql</tt> :: <tt>:dataset</tt> to set a custom dataset

data/doc/advanced_associations.rdoc

@@ -240,6 +240,145 @@ Using the :eager_loader proc, you should be able to eagerly load all association
 that can be eagerly loaded, even if Sequel doesn't natively support such eager
 loading.
 
+== Limited Associations
+
+Sequel supports specifying limits and/or offsets for associations:
+
+  Artist.one_to_many :first_10_albums, :class=>:Album, :order=>:release_date, :limit=>10
+
+For retrieving the associated objects for a single object, this just uses
+a LIMIT:
+
+  artist.first_10_albums
+  # SELECT * FROM albums WHERE (artist_id = 1) LIMIT 10
+
+=== Eager Loading via eager
+
+However, if you want to eagerly load an association, you must use a different
+approach.  Sequel has 3 separate strategies for dealing with such cases,
+depending on database support.
+
+On PostgreSQL, for *_one associations that don't use an offset, it will by
+default use the distinct on strategy, which uses a DISTINCT ON clause:
+
+  Artist.one_to_one :first_album, :class=>:Album, :order=>:release_date
+  Artist.where(:id=>[1,2]).eager(:first_album).all
+  # SELECT DISTINCT ON (albums.artist_id) *
+  # FROM albums
+  # WHERE (albums.artist_id IN (1, 2))
+  # ORDER BY albums.artist_id, release_date
+  
+Otherwise, if the database supports window functions, it will use a subquery
+with a window function:
+
+  Artist.where(:id=>[1,2]).eager(:first_10_albums).all
+  # SELECT * FROM (
+  #   SELECT *, row_number() OVER (PARTITION BY tracks.album_id ORDER BY release_date) AS x_sequel_row_number_x
+  #   FROM tracks
+  #   WHERE (tracks.album_id IN (1, 2))
+  # ) AS t1
+  # WHERE (x_sequel_row_number_x <= 10)
+  
+If the database doesn't support window functions, it will fall back to
+retrieving all records, and then will slice the resulting array to get
+the first 10 after retrieval.
+
+=== Eager Loading via eager_graph_with_options
+
+When eager loading an association via eager_graph (which uses JOINs), the
+situation is similar.  Sequel can use a variant of the same 3 strategies,
+but by default it retrieves all records and then does the array slice
+in ruby.  As eager_graph does not support options, to use an eager_graph
+limit strategy you have to use the eager_graph_with_options method with
+the :limit_strategy option.
+
+The distinct on strategy uses DISTINCT ON in a subquery and JOINs that
+subquery:
+
+  Artist.eager_graph_with_options(:first_album, :limit_strategy=>true).all
+  # SELECT artists.id, artists.name, first_album.id AS first_album_id,
+  #        first_album.name AS first_album_name, first_album.artist_id,
+  #        first_album.release_date
+  # FROM artists 
+  # LEFT OUTER JOIN (
+  #   SELECT DISTINCT ON (albums.artist_id) *
+  #   FROM albums
+  #   ORDER BY albums.artist_id, release_date
+  # ) AS first_album ON (first_album.artist_id = artists.id)
+
+The window function approach JOINs to a nested subquery using a window
+function:
+
+  Artist.eager_graph_with_options(:first_10_albums, :limit_strategy=>true).all
+  # SELECT artists.id, artists.name, first_10_albums.id AS first_10_albums_id,
+  #        first_10_albums.name AS first_10_albums_name, first_10_albums.artist_id,
+  #        first_10_albums.release_date
+  # FROM artists 
+  # LEFT OUTER JOIN (
+  #   SELECT id, name, artist_id, release_date
+  #   FROM (
+  #     SELECT *, row_number() OVER (PARTITION BY tracks.album_id ORDER BY release_date) AS x_sequel_row_number_x
+  #     FROM albums
+  #   ) AS t1 WHERE (x_sequel_row_number_x <= 10)
+  # ) AS first_10_albums ON (first_10_albums.artist_id = artists.id)
+
+The reason that Sequel does not automatically use the distinct on or
+window function strategy for eager_graph is that it can perform much worse than the
+default of just doing the array slicing in ruby.  If you are only using eager_graph to
+return a few records, it may be cheaper to get all of their associated records and filter
+them in ruby as opposed to computing the set of limited associated records for all rows.
+
+It's recommended to only use an eager_graph limit strategy if you have benchmarked
+it against the default behavior and found it is faster for your use case.
+
+=== Filtering By Associations
+
+In order to return correct results, Sequel automatically uses a limit strategy when
+using filtering by associations with limited associations, using a similar approach as
+when using eager to eagerly load.
+
+The distinct on strategy:
+
+  Artist.where(:first_album=>Album[1]).all
+  # SELECT *
+  # FROM artists
+  # WHERE (artists.id IN (
+  #   SELECT albums.artist_id
+  #   FROM albums
+  #   WHERE ((albums.artist_id IS NOT NULL) AND (albums.id IN (
+  #     SELECT DISTINCT ON (albums.artist_id) albums.id
+  #     FROM albums
+  #     ORDER BY albums.artist_id, release_date
+  #   )) AND (albums.id = 1))))
+
+The window function strategy:
+
+  Artist.where(:first_10_albums=>Album[1]).all
+  # SELECT *
+  # FROM artists
+  # WHERE (artists.id IN (
+  #   SELECT albums.artist_id
+  #   FROM albums
+  #   WHERE ((albums.artist_id IS NOT NULL) AND (albums.id IN (
+  #     SELECT id FROM (
+  #       SELECT albums.id, row_number() OVER (PARTITION BY albums.artist_id ORDER BY release_date) AS x_sequel_row_number_x
+  #       FROM albums
+  #     ) AS t1
+  #     WHERE (x_sequel_row_number_x <= 10)
+  #   )) AND (albums.id = 1))))
+
+Note that if the database does not support window functions, filtering by associations
+with limited associations will not work correctly, leading it to return results where
+associated object used as an argument is not within the limit of the association.
+
+== Additional Association Types
+
+While the above examples for limited associations showed one_to_many and one_to_one associations,
+it's just because those are the simplest examples.  Sequel supports all of the same features for
+many_to_many and one_through_one associations that are enabled by default, as well as the
+many_through_many and one_through_many associations that are added by the many_through_many
+plugin.
+
 == ActiveRecord associations
 
 Sequel supports all of associations that ActiveRecord supports, though some
@@ -361,27 +500,14 @@ Sequel::Model:
 
   class Invoice < Sequel::Model
     many_to_one :client
-
-    # has_one :through equivalent 1
-    # eager load with :eager=>:firm option on :client association, and eager loading :client
-    def firm
-      client.firm if client
-    end
-
-    # has_one :through equivalent 2
-    # eager load the usual way
-    many_to_many :firms, :join_table=>:clients, :left_key=>:id, :left_primary_key=>:client_id, :right_key=>:firm_id
-    def firm
-      firms.first
-    end
-
-    # has_one :through equivalent 3
-    # eager loading requires custom :eager_loader proc
-    many_to_one :firm, :dataset=>proc{Firm.join(:clients, :firm_id=>:id, :id=>client_id).select_all(:firms)}
+    one_through_one :firm, :join_table=>:clients, :left_key=>:id, :left_primary_key=>:client_id, :right_key=>:firm_id
   end
 
   Firm.first.invoices
 
+To handle cases where there are multiple join tables, use the many_through_many
+plugin that ships with Sequel.
+
 === Polymorphic Associations
 
 Sequel discourages the use of polymorphic associations, which is the reason they

data/doc/association_basics.rdoc

@@ -41,14 +41,23 @@ As is the code to add a related album to an artist:
 
   @artist.add_album(:name=>'RF')
 
+It also makes it easier to creating queries that use joins based on the association:
+
+  Artist.association_join(:albums)
+  # SELECT * FROM artists
+  # INNER JOIN albums ON (albums.artist_id = artists.id)
+
 == The Types of Associations
 
-Sequel has four different association types built in:
+Sequel has five different association types built in:
 
 * many_to_one
 * one_to_many
 * one_to_one
 * many_to_many
+* one_through_one
+
+It ships with additional association types via plugins.
 
 === many_to_one
 
@@ -68,13 +77,19 @@ table for each row in the associated table.
     many_to_one :artist
   end
 
-=== one_to_many
+=== one_to_many and one_to_one
 
 The one_to_many association is used when the table for the associated class
 contains a foreign key that references the primary key in the table for the
 current class.  It is named because for each row in the current table there
 can be many rows in the associated table:
 
+The one_to_one association can be thought of as a subset of the one_to_many association,
+but where there can only be either 0 or 1 records in the associated table.  This is
+useful if there is a unique constraint on the foreign key field in the associated table.
+It's also useful if you want to impose an order on the association and just want the
+first record returned.
+
   # Database schema:
   #  artists            albums
   #   :id   <----\       :id
@@ -84,27 +99,12 @@ can be many rows in the associated table:
   class Artist
     # Uses plural form of associated model name
     one_to_many :albums
-  end
-
-=== one_to_one
-
-The one_to_one association can be thought of as a subset of the one_to_many association,
-but where there can only be either 0 or 1 records in the associated table.
-It is the least frequently used of the four associations.  If you assume
-each artist cannot be associated with more than one album:
 
-  # Database schema:
-  #  artists            albums
-  #   :id   <----\       :id
-  #   :name       \----- :artist_id 
-  #                      :name
-
-  class Artist
     # Uses singular form of associated model name
     one_to_one :album
   end
-  
-=== many_to_many
+
+=== many_to_many and one_through_one
 
 The many_to_many association allows each row in the current table to be associated
 to many rows in the associated table, and each row in the associated table to
@@ -112,6 +112,14 @@ many rows in the current table, by using a join table to associate the two table
 If you assume each artist can have multiple albums and each album can have multiple
 artists:
 
+The one_through_one association can be thought of as a subset of the many_to_many
+association, but where there can only be 0 or 1 records in the associated table.
+This is useful if there is a unique constraint on the foreign key in the join table
+that refrences the current table.  It's also useful if you want to impose an order
+on the association and just want the first record returned.  The one_through_one
+association is so named because it sets up a one-to-one association through a
+single join table.
+
   # Database schema:
   #  albums 
   #   :id   <----\ 
@@ -124,14 +132,15 @@ artists:
   class Artist
     # Uses plural form of associated model name
     many_to_many :albums
-  end
-  class Album
-    many_to_many :artists
+
+    # Uses plural form of associated model name
+    one_through_one :album
   end
 
 === Differences Between many_to_one and one_to_one
 
-If you want to setup a 1-1 relationship between two models, you have to use
+If you want to setup a 1-1 relationship between two models, where the
+foreign key in one table references the associated table directly, you have to use
 many_to_one in one model, and one_to_one in the other model.  How do you
 know which to use in which model?
 
@@ -293,6 +302,8 @@ Examples:
   @artist.remove_album(@album)
   @artist.remove_all_albums
 
+one_through_one associations do not have any modification methods added.
+
 == Caching
 
 Associations are cached after being retrieved:
@@ -334,7 +345,7 @@ ending in +_dataset+ that returns a dataset representing the objects in the asso
   @album.artist_id
   # 10
   @album.artist_dataset
-  # SELECT * FROM artists WHERE (id = 10)
+  # SELECT * FROM artists WHERE (id = 10) LIMIT 1
   
   @artist.id
   # 20
@@ -400,7 +411,7 @@ can combine the approaches:
   @artist.albums_dataset.where(:publisher=>@publisher)
 
 This doesn't just work for +many_to_one+ associations, it also works for
-+one_to_one+, +one_to_many+, and +many_to_many+ associations:
+the other associations:
 
   Album.one_to_one :album_info
   # The album related to that AlbumInfo instance
@@ -414,6 +425,10 @@ This doesn't just work for +many_to_one+ associations, it also works for
   # All albums related to that Tag instance
   Album.where(:tags=>Tag[4])
 
+  Album.one_through_one :tag
+  # All albums related to that Tag instance
+  Album.where(:tag=>Tag[4])
+
 Note that for +one_to_many+ and +many_to_many+ associations, you still
 use the plural form even though only a single model object is given.
 
@@ -474,10 +489,7 @@ This will return all albums that whose popular tags would include
 at least one of those tags.
 
 Note that filtering by associations does not work for associations
-that use blocks with instance-specific code, or associations that
-have a limit or offset. This includes many_to_one/one_to_one
-associations that would return multiple values if they were not
-limited to a single value.
+that use blocks with instance-specific code.
 
 == Name Collisions
 
@@ -966,7 +978,7 @@ Use an array with two arguments for the value to specify a limit and an offset.
 This probably doesn't make a lot of sense for *_to_one associations, though you
 could use it to specify an offset.
 
-==== :join_table [+many_to_many+]
+==== :join_table [+many_to_many+, +one_through_one+]
 
 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
@@ -977,7 +989,7 @@ Here's an example of the defaults:
   Album.many_to_many :artists # :join_table=>:albums_artists
   Person.many_to_many :colleges # :join_table=>:colleges_people
 
-==== :left_key [+many_to_many+]
+==== :left_key [+many_to_many+, +one_through_one+]
 
 Foreign key in join table that points to current model's primary key, as a
 symbol.  Defaults to :"#{model_name.underscore}_id".
@@ -986,10 +998,11 @@ symbol.  Defaults to :"#{model_name.underscore}_id".
 
 Can use an array of symbols for a composite key association.
 
-==== :right_key [+many_to_many+]
+==== :right_key [+many_to_many+, +one_through_one+]
 
 Foreign key in join table that points to associated model's primary key, as a
-symbol.  Defaults to :"#{association_name.singularize}_id".
+symbol.  Defaults to :"#{association_name.singularize}_id" for +many_to_many+
+and :"#{association_name}_id" for +one_through_one+.
 
   Album.many_to_many :tags # :right_key=>:tag_id
   
@@ -1065,7 +1078,7 @@ A module or array of modules to extend the dataset with.  These are used to
 set up association extensions.  For more information , please see the
 {Advanced Associations page}[rdoc-ref:doc/advanced_associations.rdoc].
 
-==== :primary_key
+==== :primary_key [+many_to_one+, +one_to_one+, +one_to_many+]
 
 The column that the :key option references, as a symbol. For +many_to_one+
 associations, this column is in the associated table. For +one_to_one+ and
@@ -1077,7 +1090,7 @@ array of symbols for a composite key association.
   Artist.one_to_many :albums # :primary_key=>:arid
   Album.one_to_many :artist # :primary_key=>:arid
 
-==== :left_primary_key [+many_to_many+]
+==== :left_primary_key [+many_to_many+, +one_through_one+]
 
 Column in current table that :left_key option points to, as a symbol.
 Defaults to primary key of current table.
@@ -1087,7 +1100,7 @@ Defaults to primary key of current table.
 
 Can use an array of symbols for a composite key association.
 
-==== :right_primary_key [+many_to_many+]
+==== :right_primary_key [+many_to_many+, +one_through_one+]
 
 Column in associated table that :right_key points to, as a symbol.
 Defaults to primary key of the associated table.
@@ -1097,7 +1110,7 @@ Defaults to primary key of the associated table.
 
 Can use an array of symbols for a composite key association.
 
-==== :join_table_block [+many_to_many+]
+==== :join_table_block [+many_to_many+, +one_through_one+]
 
 A proc that can be used to modify the dataset used in the add/remove/remove_all
 methods.  It's separate from the association block, as that is called on a
@@ -1389,12 +1402,14 @@ needed, as one of the other eager_graph related association options is usually s
 If specified, should be a proc that accepts a single hash argument, which will contain
 at least the following keys:
 
-:self :: The dataset that is doing the eager loading
-:table_alias :: An alias to use for the table to graph for this association.
-:implicit_qualifier :: The alias that was used for the current table (since you can cascade associations).
 :callback :: A callback proc used to dynamically modify the dataset to graph into the
              current dataset, before such graphing is done. This is nil if no callback
              proc is used.
+:implicit_qualifier :: The alias that was used for the current table (since you can cascade associations).
+:join_type :: Override the join type to use when graphing.
+:limit_strategy :: The limit strategy symbol to use when graphing (for limited associations only)
+:self :: The dataset that is doing the eager loading
+:table_alias :: An alias to use for the table to graph for this association.
 
 Example:
 
@@ -1413,7 +1428,15 @@ Sequel has to do some guess work when attempting to add the association's
 order to an eager_graphed dataset.  In most cases it does so correctly, but
 if it has problems, you'll probably want to set this option to false.
 
-==== :graph_join_table_conditions [+many_to_many+]
+==== :graph_order
+
+Override the order added when using eager_graph, instead of using the one
+defined in :order.  This is useful if :order contains qualified identifiers,
+as the qualifiers may not match the aliases automatically used by eager_graph.
+This should contain unqualified identifiers, and eager_graph will automatically
+qualify them with the appropriate alias.
+
+==== :graph_join_table_conditions [+many_to_many+, +one_through_one+]
 
 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
@@ -1428,7 +1451,7 @@ has received a specific degree:
     :join_table=>:degrees_received, 
     :graph_join_table_conditions=>{:degree=>'BS'}
 
-==== :graph_join_table_block [+many_to_many+]
+==== :graph_join_table_block [+many_to_many+, +one_through_one+]
 
 The block to pass to join_table for the join table when eagerly loading the
 association via eager_graph.  This is used for similar reasons as :graph_block,
@@ -1450,7 +1473,7 @@ has received a bachelor's degree (degree starting with B):
 This should be done when graphing the join table, instead of when graphing the
 final table, as :degree is a column of the join table.
 
-==== :graph_join_table_join_type [+many_to_many+]
+==== :graph_join_table_join_type [+many_to_many+, +one_through_one+]
 
 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
@@ -1458,7 +1481,7 @@ association via eager_graph.  Defaults to the :graph_join_type option or
 you want to use a different join type when JOINing to the join table then
 you want to use for JOINing to the final table
 
-==== :graph_join_table_only_conditions [+many_to_many+]
+==== :graph_join_table_only_conditions [+many_to_many+, +one_through_one+]
 
 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
@@ -1525,12 +1548,12 @@ Like the :primary_key option, but :primary_key references the method name, while
 Like the :key option, but :key references the column
 name, while :key_method references the method name.
 
-==== :left_primary_key_column [+many_to_many+]
+==== :left_primary_key_column [+many_to_many+, +one_through_one+]
 
 Like the :left_primary_key option, but :left_primary_key references the method name, while
 :left_primary_key_column references the underlying column.
 
-==== :right_primary_key_method [+many_to_many+]
+==== :right_primary_key_method [+many_to_many+, +one_through_one+]
 
 Like the :right_primary_key option, but :right_primary_key references the column
 name, while :right_primary_key_method references the method name.
@@ -1678,7 +1701,7 @@ instances.
 ==== :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 *_to_one
+than one row for each row in the current table (default: 0 for *_one
 associations, 1 for *_to_many associations).
 
 This should only be modified in specific cases.  For example, if you have
@@ -1703,40 +1726,38 @@ plugin.
 
 ==== :eager_limit_strategy
 
-This setting determines what strategy to use for loading the associations
+This setting determines what strategy to use for eager loading the associations
 that use the :limit setting to limit the number of returned records. You
 can't use LIMIT directly, since you want a limit for each group of
 associated records, not a LIMIT on the total number of records returned
 by the dataset.
 
 By default, if a *_to_many association uses a limit or offset, or a
-one_to_one association uses an offset, Sequel will choose to use an
+one_*_one association uses an offset or an order, Sequel will choose to use an
 eager limit strategy.  The default strategy depends on the database
 being used.  For databases which support window functions, a window
 function will be used.  Other databases will just have an ruby array
 slice done on the entire record set.
 
-For one_to_one associations without offsets, no strategy is used by default
-because none is needed for a true one_to_one association (since there
+For one_*_one associations without an offset or order, no strategy is used by default
+because none is needed for a true one-to-one association (since there
 is only one associated record per current record).  However, if you are
 using a one_to_one association where the relationship is really one_to_many,
 and using an order to pick the first matching row, then if you don't
-specify an :eager_limit_strategy option, you'll be loading all related
+use an limit strategy, you'll be loading all related
 rows just to have Sequel ignore all rows after the first.  By using a
 strategy to change the query to only return one associated record per
 current record, you can get much better database performance.
 
 In general, Sequel picks an appropriate strategy, so it is not usually
-necessary to specify a specific strategy.  The exception is for one_to_one
-associations where there is more than one associated record per current
-record.  For those, you should probably specify true to this option to have
-Sequel pick an appropriate strategy.
+necessary to specify a specific strategy.
 
-You can also specify a symbol to manually choose a strategy.  The available
-strategies are:
+You can specify true for this option to have Sequel choose which strategy
+to use (this is the default).  You can specify a symbol to manually choose
+a strategy.  The available strategies are:
 
 :distinct_on :: Uses DISTINCT ON to ensure only the first matching record
-                is loaded (only used for one_to_one associations without
+                is loaded (only used for one_*_one associations without
                 offsets on PostgreSQL).
 :window_function :: Uses a ROW_NUMBER window functions to ensure the
                     correctly limited/offset records are returned.