asana2flowdock 1.0.0

data/vendor/bundle/ruby/1.9.1/gems/sequel-4.15.0/doc/association_basics.rdoc

@@ -0,0 +1,1763 @@
+= Association Basics
+
+This guide is based on http://guides.rubyonrails.org/association_basics.html
+
+== Why Associations?
+
+Associations exist to simplify code that deals with related rows in separate
+database tables.  Without associations, if you had classes such as:
+
+  class Artist < Sequel::Model
+  end
+  
+  class Album < Sequel::Model
+  end
+
+And you wanted to get all of the albums for a given artist (assuming each
+album was associated with only one artist):
+
+  Album.filter(:artist_id=>@artist.id).all
+  
+Or maybe you want to add an album for a given artist:
+
+  Album.create(:artist_id=>@artist.id, :name=>'RF')
+
+With Associations, you can make the above code simpler, by setting up associations
+between the two models:
+  
+  class Artist < Sequel::Model
+    one_to_many :albums
+  end
+  
+  class Album < Sequel::Model
+    many_to_one :artist
+  end
+
+Then, the code to retrieve albums related to the artist is simpler:
+
+  @artist.albums
+  
+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 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
+
+The many_to_one association is used when the table for the current class
+contains a foreign key that references the primary key in the table for the
+associated class.  It is named because there can be many rows in the current
+table for each row in the associated table.
+
+  # Database schema:
+  #  albums             artists
+  #   :id           /--> :id
+  #   :artist_id --/     :name
+  #   :name
+
+  class Album
+    # Uses singular form of associated model name
+    many_to_one :artist
+  end
+
+=== 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
+  #   :name       \----- :artist_id 
+  #                      :name
+
+  class Artist
+    # Uses plural form of associated model name
+    one_to_many :albums
+
+    # Uses singular form of associated model name
+    one_to_one :album
+  end
+
+=== 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
+many rows in the current table, by using a join table to associate the two tables.
+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   <----\ 
+  #   :name       \     albums_artists
+  #                \---- :album_id
+  #  artists       /---- :artist_id
+  #   :id   <-----/
+  #   :name
+  
+  class Artist
+    # Uses plural form of associated model name
+    many_to_many :albums
+
+    # Uses singular 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, 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?
+
+The simplest way to remember is that the model whose table has the foreign
+key uses many_to_one, and the other model uses one_to_one:
+
+  # Database schema:
+  #  artists            albums
+  #   :id   <----\       :id
+  #   :name       \----- :artist_id 
+  #                      :name
+
+  class Artist
+    one_to_one :album
+  end
+  class Album
+    many_to_one :artist
+  end
+
+== Most Common Options
+
+=== :key
+
+The :key option must be used if the default column symbol that Sequel would use is not
+the correct column.  For example:
+
+  class Album
+    # Assumes :key is :artist_id, based on association name of :artist
+    many_to_one :artist
+  end
+  class Artist
+    # Assumes :key is :artist_id, based on class name of Artist
+    one_to_many :albums
+  end
+  
+However, if your schema looks like:
+
+  # Database schema:
+  #  artists            albums
+  #   :id   <----\       :id
+  #   :name       \----- :artistid # Note missing underscore
+  #                      :name
+  
+Then the default :key option will not be correct.  To fix this, you need to
+specify an explicit :key option:
+
+  class Album
+    many_to_one :artist, :key=>:artistid
+  end
+  class Artist
+    one_to_many :albumst, :key=>:artistid
+  end
+  
+For many_to_many associations, the :left_key and :right_key options can be
+used to specify the column names in the join table, and the :join_table
+option can be used to specify the name of the join table:
+
+  # Database schema:
+  #  albums 
+  #   :id   <----\ 
+  #   :name       \     albumsartists
+  #                \---- :albumid
+  #  artists       /---- :artistid
+  #   :id   <-----/
+  #   :name
+  
+  class Artist
+    # Note that :left_key refers to the foreign key pointing to the
+    # current table, and :right_key the foreign key pointing to the
+    # associated table.
+    many_to_many :albums, :left_key=>:artistid, :right_key=>:albumid,
+      :join_table=>:albumsartists
+  end
+  class Album
+    many_to_many :artists, :left_key=>:albumid, :right_key=>:artistid,
+      :join_table=>:albumsartists
+  end
+
+=== :class
+
+If the class of the association can not be guessed directly by looking at
+the association name, you need to specify it via the :class option.  For
+example, if you have two separate foreign keys in the albums table that
+both point to the artists table, maybe to indicate one artist is the
+vocalist and one is the composer, you'd have to use the :class option:
+
+  # Database schema:
+  #  artists            albums
+  #   :id   <----\       :id
+  #   :name       \----- :vocalist_id
+  #                \---- :composer_id
+  #                      :name
+  
+  class Album
+    many_to_one :vocalist, :class=>:Artist
+    many_to_one :composer, :class=>:Artist
+  end
+  class Artist
+    one_to_many :vocalist_albums, :class=>:Album, :key=>:vocalist_id
+    one_to_many :composer_albums, :class=>:Album, :key=>:composer_id
+  end
+
+== Self-referential Associations
+
+Self-referential associations are easy to handle in Sequel.  The simplest
+example is a tree structure:
+
+  # Database schema:
+  #  nodes
+  #   :id        <--\ 
+  #   :parent_id ---/
+  #   :name
+  
+  class Node
+    many_to_one :parent, :class=>self
+    one_to_many :children, :key=>:parent_id, :class=>self
+  end
+
+For many_to_many self_referential associations, it's fairly similar.  Here's
+an example of a directed graph:
+
+  # Database schema:
+  #  nodes              edges
+  #   :id   <----------- :successor_id
+  #   :name       \----- :predecessor_id
+
+  class Node
+    many_to_many :direct_successors, :left_key=>:successor_id,
+      :right_key=>:predecessor_id, :join_table=>:edges, :class=>self
+    many_to_many :direct_predecessors, :right_key=>:successor_id,
+      :left_key=>:predecessor_id, :join_table=>:edges, :class=>self
+  end
+
+== Methods Added
+
+When you create an association, it's going to add instance methods to
+the class related to the association.
+
+All associations are going to have an instance method added with the
+same name as the association:
+
+  @artist.albums
+  @album.artists
+  
+many_to_one and one_to_one associations will also have a setter method
+added to change the associated object:
+
+  @album.artist = Artist.create(:name=>'YJM')
+
+many_to_many and one_to_many associations will have three methods added:
+
+- add_* to associate an object to the current object
+- remove_* to disassociate an object from the current object
+- remove_all_* to dissociate all currently associated objects
+
+Examples:
+
+  @artist.add_album(@album)
+  @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:
+
+  @artist.album # Not cached - Database Query
+  @artist.album # Cached - No Database Query
+  
+  @album.artists # Not cached - Database Query
+  @album.artists # Cached - No Database Query
+  
+You can choose to ignore the cached versions and do a database query to
+retrieve results by passing a true argument to the association method:
+
+  @album.artists # Not cached - Database Query
+  @album.artists # Cached - No Database Query
+  @album.artists(true) # Ignore cache - Database Query
+
+If you reload/refresh the object, it will automatically clear the
+associations cache for the object:
+
+  @album.artists # Not cached - Database Query
+  @album.artists # Cached - No Database Query
+  @album.reload
+  @album.artists # Not Cached - Database Query
+  
+If you want direct access to the associations cache, use the associations
+instance method:
+
+  @album.associations # {}
+  @album.associations[:artists] # nil
+  @album.artists # [<Artist ...>, ...]
+  @album.associations[:artists] # [<Artist ...>, ...]
+
+== Dataset Method
+
+In addition to the above methods, associations also add a instance method
+ending in +_dataset+ that returns a dataset representing the objects in the associated table:
+
+  @album.artist_id
+  # 10
+  @album.artist_dataset
+  # SELECT * FROM artists WHERE (id = 10) LIMIT 1
+  
+  @artist.id
+  # 20
+  @artist.albums_dataset
+  # SELECT * FROM albums WHERE (artist_id = 20)
+
+The association dataset is just like any other Sequel dataset, in that
+it can be further filtered, ordered, etc.:
+
+  @artist.albums_dataset.
+   where(Sequel.like(:name, 'A%')).
+   order(:copies_sold).
+   limit(10)
+  # SELECT * FROM albums
+  # WHERE ((artist_id = 20) AND (name LIKE 'A%' ESCAPE '\'))
+  # ORDER BY copies_sold LIMIT 10
+
+Records retrieved using the +_dataset+ method are not cached in the
+associations cache.
+
+  @album.artists_dataset.all # [<Artist ...>, ...]
+  @album.associations[:artists] # nil
+
+== Dynamic Association Modification
+
+Similar to the +_dataset+ method, you can provide a block to the association
+method to customize the dataset that will be used to retrieve the records.  So
+you can apply a filter in either of these two ways:
+
+  @artist.albums_dataset.where(Sequel.like(:name, 'A%'))
+  @artist.albums{|ds| ds.where(Sequel.like(:name, 'A%'))}
+
+While they both apply the same filter, using the +_dataset+ method does not
+apply any of the association callbacks or handle association reciprocals (see
+below for details about callbacks and reciprocals).  Using a block instead handles
+all those things, and also caches its results in the associations cache (ignoring
+any previously cached value).
+
+== Filtering By Associations
+
+In addition to using the association method to get associated objects, you
+can also use associated objects in filters.  For example, to get
+all albums for a given artist, you would usually do:
+
+  @artist.albums
+  # or @artist.albums_dataset for a dataset
+
+You can also do the following:
+
+  Album.where(:artist=>@artist).all
+  # or leave off the .all for a dataset
+
+For filtering by a single association, this isn't very useful.  However, unlike
+using the association method, using a filter allows you to filter by multiple
+associations:
+
+  Album.where(:artist=>@artist, :publisher=>@publisher)
+
+This will return all albums by that artist and published by that publisher.
+This isn't possible using just the association method approach, though you
+can combine the approaches:
+
+  @artist.albums_dataset.where(:publisher=>@publisher)
+
+This doesn't just work for +many_to_one+ associations, it also works for
+the other associations:
+
+  Album.one_to_one :album_info
+  # The album related to that AlbumInfo instance
+  Album.where(:album_info=>AlbumInfo[2])
+
+  Album.one_to_many :tracks
+  # The album related to that Track instance
+  Album.where(:tracks=>Track[3])
+
+  Album.many_to_many :tags
+  # 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.
+
+You can also exclude by associations:
+
+  Album.exclude(:artist=>@artist).all
+  
+This will return all albums not by that artist.
+
+You can also provide an array with multiple model objects:
+
+  Album.where(:artist=>[@artist1, @artist2]).all
+
+Similar to using an array of integers or strings, this will return
+all albums whose artist is one of those two artists.  You can also
+use +exclude+ if you want all albums not by either of those artists:
+
+  Album.exclude(:artist=>[@artist1, @artist2]).all
+
+If you are using a +one_to_many+ or +many_to_many+ association, you
+may want to return records where the records matches all of multiple
+records, instead of matching any of them.  For example:
+
+  Album.where(:tags=>[@tag1, @tag2])
+  
+This matches albums that are associated with either @tag1 or @tag2 or
+both.  If you only want ones that you are associated with both, you can
+use separate filter calls:
+
+  Album.where(:tags=>@tag1).where(:tags=>@tag2)
+
+Or the array form of condition specifiers:
+
+  Album.where([[:tags, @tag1], [:tags, @tag2]])
+
+These will return albums associated with both @tag1 and @tag2.
+
+You can also provide a dataset value when filtering by associations:
+
+  Album.where(:artist=>Artist.where(Sequel.like(:name, 'A%'))).all
+
+This will return all albums whose artist starts with 'A'. Like
+the other forms, this can be inverted:
+
+  Album.exclude(:artist=>Artist.where(Sequel.like(:name, 'A%'))).all
+ 
+This will return all albums whose artist does not start with 'A'.
+
+Filtering by associations even works for associations that have
+conditions added via the :conditions option or a block:
+
+  Album.one_to_many :popular_tags, :clone=>:tags do |ds|
+    ds.where{times_used > 1000}
+  end
+  Album.where(:popular_tags=>[@tag1, @tag2])
+
+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.
+
+== Name Collisions
+
+Because associations create instance methods, it's possible to override
+existing instance methods if you name an association the same as an
+existing method.  For example, <tt>values</tt> and <tt>associations</tt>
+would be bad association names.
+
+== Database Schema
+
+Creating an association doesn't modify the database schema.  Sequel
+assumes your associations reflect the existing database schema.  If not,
+you should modify your schema before creating the associations.
+
+=== many_to_one/one_to_many
+
+For example, for the following model code:
+
+  class Album
+    many_to_one :artist
+  end
+  class Artist
+    one_to_many :albums
+  end
+
+You probably want the following database schema:
+
+  #  albums             artists
+  #   :id           /--> :id
+  #   :artist_id --/     :name
+  #   :name
+  
+Which could be created using the following Sequel code:
+
+  DB.create_table(:artists) do
+    # Primary key must be set explicitly
+    primary_key :id
+    String :name
+  end
+  DB.create_table(:albums) do
+    primary_key :id
+    # Table that foreign key references needs to be set explicitly
+    # for a database foreign key reference to be created.
+    foreign_key :artist_id, :artists
+    String :name
+  end
+
+If you already had a schema such as:
+
+  # Database schema:
+  #  albums             artists
+  #   :id                :id
+  #   :name              :name
+  
+Then you just need to add the column:
+
+  DB.alter_table(:albums) do
+    add_foreign_key :artist_id, :artists
+  end
+
+=== many_to_many
+
+With many_to_many associations, the default join table for the association
+uses the sorted underscored names of both model classes.  For example, with
+the following model code:
+
+  class Album
+    many_to_many :artists
+  end
+  class Artist
+    many_to_many :albums
+  end
+
+The default join table name would be <tt>albums_artists</tt>, not
+<tt>artists_albums</tt>, because:
+
+  ["artists", "albums"].sort.join('_')
+  # "albums_artists"
+
+Assume you already had the albums and artists tables created, and you just
+wanted to add an albums_artists join table to create the following schema:
+
+  # Database schema:
+  #  albums 
+  #   :id   <----\ 
+  #   :name       \     albums_artists
+  #                \---- :album_id
+  #  artists       /---- :artist_id
+  #   :id   <-----/
+  #   :name
+
+You could use the following Sequel code:
+
+  DB.create_join_table(:album_id=>:albums, :artist_id=>:artists)
+  # or
+  DB.create_table(:albums_artists) do
+    foreign_key :album_id, :albums
+    foreign_key :artist_id, :artists
+  end
+
+== Association Scope
+
+If you nest your Sequel::Model classes inside modules, then you should know
+that Sequel will only look in the same module for associations by default.
+So the following code will work fine:
+
+  module App
+    class Artist < Sequel::Model
+      one_to_many :albums
+    end
+    class Album < Sequel::Model
+      many_to_one :artist
+    end
+  end
+
+However, if you enclose your model classes inside two different modules,
+things will not work by default:
+
+  module App1
+    class Artist < Sequel::Model
+      one_to_many :albums
+    end
+  end
+  module App2
+    class Album < Sequel::Model
+      many_to_one :artist
+    end
+  end
+
+To fix this, you need to specify the full model class name using the
+:class option:
+
+  module App1
+    class Artist < Sequel::Model
+      one_to_many :albums, :class=>"App2::Album"
+    end
+  end
+  module App2
+    class Album < Sequel::Model
+      many_to_one :artist, :class=>"App1::Artist"
+    end
+  end
+
+If both classes are in the same module, but the default class name
+used is not correct, you need to specify the full class name with the
+:class option:
+
+  module App1
+    class AlbumArtist < Sequel::Model
+      one_to_many :albums
+    end
+    class Album < Sequel::Model
+      many_to_one :artist, :class=>"App1::AlbumArtist"
+    end
+  end
+
+== Method Details
+
+In all of these methods, _association_ is replaced by the symbol you
+pass to the association.
+
+=== _association_(reload = false) (e.g. albums)
+
+For +many_to_one+ and +one_to_one+ associations, the _association_ method
+returns either the single object associated, or nil if no object is
+associated.
+
+  @artist = @album.artist
+
+For +one_to_many+ and +many_to_many+ associations, the _association_ method
+returns an array of associated objects, which may be empty if no objects
+are currently associated.
+
+  @albums = @artist.albums
+
+=== _association_=(object_to_associate) (e.g. artist=) [+many_to_one+ and +one_to_one+]
+
+The _association_= method sets up an association of the passed object to
+the current object.  For +many_to_one+ associations, this sets the
+foreign key for the current object to point to the associated
+object's primary key.
+
+  @album.artist = @artist
+
+For +one_to_one+ associations, this sets the foreign key of the
+associated object to the primary key value of the current object.
+
+For +many_to_one+ associations, this does not save the current object.
+For +one_to_one+ associations, this does save the associated object.
+
+=== add_<i>association</i>(object_to_associate) (e.g. add_album) [+one_to_many+ and +many_to_many+]
+
+The add_<i>association</i> method associates the passed object to the current
+object.  For +one_to_many+ associations, it sets the foreign key of the
+associated object to the primary key value of the current object, and
+saves the associated object.  For +many_to_many+ associations, this inserts
+a row into the join table with the foreign keys set to the primary key values
+of the current and associated objects.  Note that the singular form of the
+association name is used in this method.
+
+  @artist.add_album(@album)
+  
+In addition to passing an actual associated object, you can pass a hash,
+and a new associated object will be created from them:
+
+  @artist.add_album(:name=>'RF') # creates Album object
+
+The add_<i>association</i> method returns the new associated object:
+
+  @album = @artist.add_album(:name=>'RF')
+
+Note that the add_* methods for +one_to_many+ persist the changes by
+saving the passed in (or newly created) object.  However, to avoid
+silent failures of these methods, they explicitly raise exceptions
+even when raise_on_save_failure is false for the associated model.
+You can disable this behavior (i.e. return nil instead of raising
+exceptions on a save failure) by setting the <tt>:raise_on_save_failure=>false</tt>
+option for the association.
+
+=== remove_<i>association</i>(object_to_disassociate) (e.g. remove_album) [+one_to_many+ and +many_to_many+]
+
+The remove_<i>association</i> method disassociates the passed object from
+the current object.  For +one_to_many+ associations, it sets the foreign key of
+the associated object to NULL, and saves the associated object.  For
++many_to_many+ associations, this deletes the matching row in the join table.
+Similar to the add_<i>association</i> method, the singular form of the
+association name is used in this method.
+
+  @artist.remove_album(@album)
+
+Note that this does not delete <tt>@album</tt> from the database, it only
+disassociates it from the <tt>@artist</tt>.  To delete <tt>@album</tt> from the
+database:
+
+  @album.destroy
+
+The add_<i>association</i> and remove_<i>association</i> methods should be
+thought of as adding and removing from the association, not from the database.
+
+In addition to passing the object directly to remove_<i>association</i>, you
+can also pass the associated object's primary key:
+
+  @artist.remove_album(10)
+
+This will look up the associated object using the key, and remove that
+album.
+
+The remove_<i>association</i> method returns the now disassociated object:
+
+  @album = @artist.remove_album(10)
+
+=== remove_all_<i>association</i> (e.g. remove_all_albums) [+one_to_many+ and +many_to_many+]
+
+The remove_all_<i>association</i> method disassociates all currently associated
+objects.  For +one_to_many+ associations, it sets the foreign key of
+all associated objects to NULL in a single query.  For +many_to_many+
+associations, this deletes all matching rows in the join table.
+Unlike the add_<i>association</i> and remove_<i>association</i> method, the
+plural form of the association name is used in this method.
+The remove_all_<i>association</i> method returns the number of rows updated
+for +one_to_many+ associations and the number of rows deleted for
++many_to_many+ associations:
+
+  @rows_modified = @artist.remove_all_albums
+
+=== <i>association</i>_dataset (e.g. albums_dataset)
+
+The <i>association</i>_dataset method returns a dataset that represents
+all associated objects.  This dataset is like any other Sequel dataset,
+in that it can be filtered, ordered, etc.:
+
+  ds = @artist.albums_dataset.where(Sequel.like(:name, 'A%')).order(:copies_sold)
+
+Unlike most other Sequel datasets, association datasets have a couple of
+added methods:
+
+  ds.model_object # @artist
+  ds.association_reflection # same as Artist.association_reflection(:albums)
+
+For a more info on Sequel's reflection capabilities see the {Reflection page}[rdoc-ref:doc/reflection.rdoc].
+
+== Overriding Method Behavior
+
+Sequel is designed to be very flexible.  If the default behavior of the
+association modification methods isn't what you desire, you can override
+the methods in your classes.  However, you should be aware that for each
+of the association modification methods described, there is a private
+method that is preceeded by an underscore that does the actual
+modification.  The public method without the underscore handles caching
+and callbacks, and shouldn't be overridden by the user.
+
+In addition to overriding the private method in your class, you can also
+use association options to change which method Sequel defines.  The
+only difference between the two is that if you use an association option
+to change the method Sequel defines, you cannot call super to get the
+default behavior.
+
+=== _<i>association</i>= (:setter option)
+
+Let's say you want to set a specific field whenever associating an object
+using the association setter method.  For example, let's say you have
+a file_under column for each album to tell you where to file it.  If the
+album is associated with an artist, it should be filed under the artist's
+name and the album's name, otherwise it should just use the album's name.
+
+  class Album < Sequel::Model
+    many_to_one :artist
+    
+    private
+    
+    def _artist=(artist)
+      if artist
+        self.artist_id = artist.id
+        self.file_under = "#{artist.name}-#{name}"
+      else
+        self.artist_id = nil
+        self.file_under = name
+      end
+    end
+  end
+
+The above example is contrived, as you would generally use a before_save model
+hook to handle such a modification.  However, if you only modify the album's
+artist using the artist= method, this approach may perform better.
+
+=== \_add_<i>association</i> (:adder option)
+
+Continuing with the same example, here's how you would handle the same case if
+you also wanted to handle the Artist#add_album method:
+
+  class Artist < Sequel::Model
+    one_to_many :albums
+    
+    private
+    
+    def _add_album(album)
+      album.update(:artist_id => id, :file_under=>"#{name}-#{album.name}")
+    end
+  end
+
+=== \_remove_<i>association</i> (:remover option)
+
+Continuing with the same example, here's how you would handle the same case if
+you also wanted to handle the Artist#remove_album method:
+
+  class Artist < Sequel::Model
+    one_to_many :albums
+    
+    private
+    
+    def _remove_album(album)
+      album.update(:artist_id => nil, :file_under=>album.name)
+    end
+  end
+
+=== \_remove_all_<i>association</i> (:clearer option)
+
+Continuing with the same example, here's how you would handle the same case if
+you also wanted to handle the Artist#remove_all_albums method:
+
+  class Artist < Sequel::Model
+    one_to_many :albums
+    
+    private
+    
+    def _remove_all_albums
+      # This is Dataset#update, not Model#update, so the :file_under=>:name
+      # ends up being "SET file_under = name" in SQL.
+      albums_dataset.update(:artist_id => nil, :file_under=>:name)
+    end
+  end
+
+== Association Options
+
+Sequel's associations mostly share the same options.  For ease of understanding,
+they are grouped here by section
+
+=== Association Dataset Modification Options
+
+==== block
+
+All association defining methods take a block that is passed the
+default dataset and should return a modified copy of the dataset to
+use for the association.  For example, if you wanted an association
+that returns all albums of an artist that went gold (sold at least
+500,000 copies):
+
+  Artist.one_to_many :gold_albums, :class=>:Album do |ds|
+    ds.where{copies_sold > 500000}
+  end
+
+==== :class
+
+This is the class of the associated objects that will be used.  It's
+one of the most commonly used options.  If it is not given, it guesses
+based on the name of the association.  If a *_to_many association is
+used, uses the singular form of the association name.  For example:
+
+  Album.many_to_one :artist # guesses Artist
+  Artist.one_to_many :albums # guesses Album
+
+However, for more complex associations, especially ones that add
+additional filters beyond the foreign/primary key relationships, the
+default class guessed will be wrong:
+
+  # guesses GoldAlbum
+  Artist.one_to_many :gold_albums do |ds|
+    ds.where{copies_sold > 500000}
+  end
+
+You can specify the :class option using the class itself, a Symbol,
+or a String:
+
+  Album.many_to_one :artist, :class=>Artist # Class
+  Album.many_to_one :artist, :class=>:Artist # Symbol
+  Album.many_to_one :artist, :class=>"Artist" # String
+
+==== :key
+
+For +many_to_one+ associations, this is the foreign_key in the current model's
+table that references the associated model's primary key as a symbol.
+Defaults to :<i>association</i>_id.  Can use an array of symbols for a
+composite key association.
+
+  Album.many_to_one :artist # :key=>:artist_id
+
+For +one_to_one+ and +one_to_many+ associations, is the foreign key in
+associated model's table that references current model's primary key, as a
+symbol.  Defaults to :"#{self.name.underscore}_id".
+
+  Artist.one_to_many :albums # :key=>:artist_id
+
+In both cases an array of symbols can be used for a composite key association:
+
+  Apartment.many_to_one :building # :key=>[:city, :address]
+
+==== :conditions
+
+The conditions to use to filter the association, can be any argument passed to +where+.
+If you use a hash or an array of two element arrays, this will also be used as a
+filter when using eager_graph to load the association.
+
+  Artist.one_to_many :good_albums, :class=>:Album, :conditions=>{:good=>true}
+  @artist.good_albums
+  # SELECT * FROM albums WHERE ((artist_id = 1) AND (good IS TRUE))
+
+==== :order
+
+The column(s) by which to order the association dataset.  Can be a
+singular column or an array.
+
+  Artist.one_to_many :albums_by_name, :class=>:Album,
+   :order=>:name
+  Artist.one_to_many :albums_by_num_tracks, :class=>:Album,
+   :order=>[:num_tracks, :name]
+
+==== :select
+
+The columns to SELECT when loading the association.  For most associations,
+it defaults to nil, so * is used.  For +many_to_many+ associations, it
+defaults to the associated class's table_name.*, which means it doesn't include
+the columns from the join table.  This is to prevent the common issue where the
+join table includes columns with the same name as columns in the associated
+table, in which case the joined table's columns would usually end up clobbering
+the values in the associated table. If you want to include the join table
+attributes, you can use this option, but beware that the join table columns
+can clash with columns from the associated table, so you should alias any
+columns that have the same name in both the join table and the associated
+table.  Example:
+
+  Artist.one_to_many :albums, :select=>[:id, :name]
+  Album.many_to_many :tags, :select=>[Sequel.expr(:tags).*, :albums_tags__number]
+
+==== :limit
+
+Limit the number of records to the provided value:
+
+  Artist.one_to_many :best_selling_albums, :class=>:Album,
+  :order=>:copies_sold, :limit=>5 # LIMIT 5
+
+Use an array with two arguments for the value to specify a limit and an offset.
+
+  Artist.one_to_many :next_best_selling_albums, :class=>:Album,
+   :order=>:copies_sold, :limit=>[10, 5] # LIMIT 10 OFFSET 5
+
+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+, +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
+of associated model, pluralized, underscored, sorted, and joined with '_'.
+Here's an example of the defaults:
+
+  Artist.many_to_many :albums # :join_table=>:albums_artists
+  Album.many_to_many :artists # :join_table=>:albums_artists
+  Person.many_to_many :colleges # :join_table=>:colleges_people
+
+==== :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".
+
+  Album.many_to_many :tags # :left_key=>:album_id
+
+Can use an array of symbols for a composite key association.
+
+==== :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" for +many_to_many+
+and :"#{association_name}_id" for +one_through_one+.
+
+  Album.many_to_many :tags # :right_key=>:tag_id
+  
+Can use an array of symbols for a composite key association.
+
+==== :distinct
+
+Use the DISTINCT clause when selecting associating object, both when lazy
+loading and eager loading via eager (but not when using eager_graph).
+
+This is most useful for many_to_many associations that use join tables that
+contain more than just the foreign keys, where you are storing additional
+information.  For example, if you have a database of people, degree types, and
+colleges, and you want to return all people from a given college, you may want
+to use :distinct so that if a person has two separate degrees from the same
+college, they won't show up twice.
+
+==== :clone
+
+The :clone option clones an existing association, taking the options
+you specified for that association, and making a copy of them for this
+association.  Other options provided by this association are then merged
+into the cloned options.
+
+This is commonly used if you have a bunch of similar associations that
+you want to DRY up:
+
+  one_to_many :english_verses, :class=>:LyricVerse, :key=>:lyricsongid,
+    :order=>:number, :conditions=>{:languageid=>1}
+  one_to_many :romaji_verses, :clone=>:english_verses, :conditions=>{:languageid=>2}
+  one_to_many :japanese_verses, :clone=>:english_verses, :conditions=>{:languageid=>3}
+
+Note that for the final two asociations, you didn't have to specify the :class,
+:key, or :order options, as they were copied by the :clone option.  By specifying
+the :conditions option for the final two associations, it overrides the :conditions
+option of the first association, it doesn't attempt to merge them.
+
+In addition to the options hash, the :clone option will copy a block argument
+from the existing situation.  If you want a cloned association to not have the
+same block as the association you are cloning from, specify the :block=>nil option
+in additon to the :clone option.
+
+==== :dataset
+
+This is generally only specified for custom associations that aren't based on
+primary/foreign key relationships.  It should be a proc that is instance_execed
+to get the base dataset to use before the other options are applied.
+
+If the proc accepts an argument, it is passed the related association reflection.
+For best performance, it's recommended that custom associations call the
++associated_dataset+ method on the association reflection as the starting point
+for the dataset to return.  The +associated_dataset+ method will return a
+dataset based on the associated class with most of the association options
+already applied, and the proc should return a modified copy of this dataset.
+
+Here's an example of an association of songs to artists through lyrics, where
+the artist can perform any one of four tasks for the lyric:
+
+  Album.one_to_many :songs, :dataset=>(proc do |r|
+    r.associated_dataset.select_all(:songs).
+     join(Lyric, :id=>:lyricid,
+      id=>[:composer_id, :arranger_id, :vocalist_id, :lyricist_id])
+  end)
+  Artist.first.songs_dataset
+  # SELECT songs.* FROM songs
+  # INNER JOIN lyrics ON
+  #  lyrics.id = songs.lyric_id AND
+  #  1 IN (composer_id, arranger_id, vocalist_id, lyricist_id)
+
+==== :extend
+
+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 [+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
++one_to_many+ associations, this column is in the current table.  In both cases,
+it defaults to the primary key of the table. Can use an
+array of symbols for a composite key association.
+
+  Artist.set_primary_key :arid
+  Artist.one_to_many :albums # :primary_key=>:arid
+  Album.one_to_many :artist # :primary_key=>:arid
+
+==== :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.
+
+  Album.set_primary_key :alid
+  Album.many_to_many :tags # :left_primary_key=>:alid
+
+Can use an array of symbols for a composite key association.
+
+==== :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.
+
+  Tag.set_primary_key :tid
+  Album.many_to_many :tags # :right_primary_key=>:tid
+
+Can use an array of symbols for a composite key association.
+
+==== :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
+join of the join table and the associated table, whereas this option just
+applies to the join table.  It can be used to make sure that filters are used
+when deleting.
+
+  Artist.many_to_many :lead_guitar_albums, :join_table_block=>proc do |ds|
+    ds.where(:instrument_id=>5)
+  end
+
+=== Callback Options
+
+All callbacks can be specified as a Symbol, Proc, or array of both/either
+specifying a callback to call.  Symbols are interpreted as instance methods
+that are called with the associated object.  Procs are called with the receiver
+as the first argument and the associated object as the second argument.  If
+an array is given, all of them are called in order.  
+
+Before callbacks are often used to check preconditions, they can return
+false to signal Sequel to abort the modification.  If any before callback
+returns false, the remaining before callbacks are not called and modification
+is aborted.  Before callbacks are also commonly used to modify the current
+object or the associated object.
+
+After callbacks are often used for notification (logging, email) after a
+successful modification has been made.
+
+==== :before_add [+one_to_many+, +many_to_many+]
+
+Called before adding an object to the association:
+  
+  class Artist
+    # Don't allow adding an album to an artist if it has no tracks
+    one_to_many :albums, :before_add=>proc{|ar, al| false if al.num_tracks == 0}
+  end
+
+==== :after_add [+one_to_many+, +many_to_many+]
+
+Called after adding an object to the association:
+  
+  class Artist
+    # Log all associations of albums to an audit logging table
+    one_to_many :albums, :after_add=>:log_add_album
+    
+    private
+    
+    def log_add_album(album)
+      DB[:audit_logs].insert(:log=>"Album #{album.inspect} associated to #{inspect}")
+    end
+  end
+
+==== :before_remove [+one_to_many+, +many_to_many+]
+
+Called before removing an object from the association:
+
+  class Artist
+    # Don't allow removing a self-titled album
+    one_to_many :albums, :before_remove=>proc{|ar, al| false if al.name == ar.name}
+  end
+
+==== :after_remove [+one_to_many+, +many_to_many+]
+
+Called after removing an object from the association:
+
+  class Artist
+    # Log all disassociations of albums to an audit logging table
+    one_to_many :albums, :after_remove=>:log_remove_album
+    
+    private
+    
+    def log_remove_album(album)
+      DB[:audit_logs].insert(:log=>"Album #{album.inspect} disassociated from #{inspect}")
+    end
+  end
+
+==== :before_set [+many_to_one+, +one_to_one+]
+
+Called before the _<i>association</i>= method is called to modify the objects:
+
+  class Album
+    # Don't associate the album with an artist if the year the album was
+    # released is less than the year the artist/band started.
+    many_to_one :artist, :before_set=>proc{|al, ar| false if al.year < ar.year_started}
+  end
+
+==== :after_set [+many_to_one+, +one_to_one+]
+
+Called after the _<i>association</i>= method is called to modify the objects:
+
+  class Album
+    # Log all disassociations of albums to an audit logging table
+    many_to_one :artist, :after_set=>:log_artist_set
+    
+    private
+    
+    def log_artist_set(artist)
+      DB[:audit_logs].insert(:log=>"Artist for album #{inspect} set to #{artist.inspect}")
+    end
+  end
+
+==== :after_load
+
+Called after retrieving the associated records from the database.
+
+  class Artist
+    # Cache all album names to a single string when retrieving the
+    # albums.
+    one_to_many :albums, :after_load=>:cache_album_names
+    
+    attr_reader :album_names
+    
+    private
+    
+    def cache_album_names(albums)
+      @album_names = albums.map{|x| x.name}.join(", ")
+    end
+  end
+
+Generally used if you know you will always want a certain action done
+when retrieving the association.
+
+For +one_to_many+ and +many_to_many+ associations, both the argument to
+symbol callbacks and the second argument to proc callbacks will be an
+array of associated objects instead of a single object.
+
+==== :uniq [+many_to_many+]
+
+Adds a after_load callback that makes the array of objects unique. In many
+cases, using the :distinct option is a better approach.
+
+=== Eager Loading via eager (query per association) Options
+
+==== :eager
+
+The associations to eagerly load via eager when loading the associated object(s).
+This is useful for example if you always want to eagerly load dependent
+associations when loading this association.
+
+For example, if you know that any time that you want to load an artist's
+albums, you are also going to want access to the album's tracks as well:
+
+  # Eager load tracks when loading the albums
+  Artist.one_to_many :albums, :eager=>:tracks
+  
+You can also use a hash or array to specify multiple dependent associations
+to eagerly load:
+
+  # Eager load the albums' tracks and the tracks' tags when loading the albums
+  Artist.one_to_many :albums, :eager=>{:tracks=>:tags}
+  # Eager load the albums' tags and tracks when loading the albums
+  Artist.one_to_many :albums, :eager=>[:tags, :tracks]
+  # Eager load the albums' tags, tracks, and tracks' tags when loading the albums
+  Artist.one_to_many :albums, :eager=>[:tags, {:tracks=>:tags}]
+
+==== :eager_loader
+
+A custom loader to use when eagerly load associated objects via eager.
+For many details and examples of custom eager loaders, please see the
+{Advanced Associations guide}[rdoc-ref:doc/advanced_associations.rdoc].
+
+==== :eager_loader_key
+
+A symbol for the key column to use to populate the key hash for the eager
+loader.  Generally does not need to be set manually, defaults to the key
+method used.  Can be set to nil to not populate the key hash (better for
+performance if a custom eager loader does not use the key_hash).
+
+==== :eager_block
+
+If given, should be a proc to use instead of the association method block
+when eagerly loading.  To not use a block when eager loading when one is
+used normally, should to nil.  It's very uncommon to need this option.
+
+=== Eager Loading via eager_graph (one query with joins) Options
+
+==== :eager_graph
+
+The associations to eagerly load via eager_graph when loading the associated
+object(s). This is useful for example if you always want to eagerly load dependent
+associations when loading this association, but you want to filter or order the
+association based on dependent associations:
+
+  Artist.one_to_many :albums_with_short_tracks, :class=>:Album,
+   :eager_graph=>:tracks do |ds|
+    ds.where{tracks__seconds < 120}
+  end
+  Artist.one_to_many :albums_by_track_name, :class=>:Album,
+   :eager_graph=>:tracks do |ds|
+    ds.order(:tracks__name)
+  end
+
+You can also use a hash or array of arguments for :eager_graph, similar to
+what the :eager option accepts.
+
+==== :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.
+
+  Artist.one_to_many :active_albums, :class=>:Album,
+    :graph_conditions=>{:active=>true}
+
+Note that these conditions on the association are in addition to the default
+conditions specified by the foreign/primary keys.  If you want to replace
+the conditions specified by the foreign/primary keys, you need the
+:graph_only_conditions options.
+
+==== :graph_block
+
+The block to pass to Dataset#join_table when eagerly loading the association
+via eager_graph.  This is useful to specify conditions that can't be specified
+in a hash or array of two element arrays.
+
+  Artist.one_to_many :gold_albums, :class=>:Album,
+    :graph_block=>proc{|j,lj,js| Sequel.qualify(j, :copies_sold) > 500000}
+
+==== :graph_join_type
+
+The type of SQL join to use when eagerly loading the association via
+eager_graph.  Defaults to :left_outer.  This is useful if you want to
+ensure that only artists that have albums are returned:
+
+  Artist.one_to_many :albums, :graph_join_type=>:inner
+  # Will exclude artists without an album
+  Artist.eager_graph(:albums).all
+
+==== :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.
+
+==== :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.  This can be useful if the keys you are using are strings and you
+want to do a case insensitive comparison.  For example, let's say that instead
+of integer keys, you used string keys based on the album or artist name, and
+that the album was associated to the artist by name.  However, you weren't
+enforcing case sensitivity between the keys, so you still want to return albums
+where the artist's name differs in case:
+
+  Artist.one_to_many :albums, :key=>:artist_name, 
+    :graph_only_conditions=>nil, 
+    :graph_block=>proc{|j,lj,js| {Sequel.function(:lower, Sequel.qualify(j, :artist_name))=>
+      Sequel.function(:lower, Sequel.qualify(lj, :name))}}
+
+Note how :graph_only_conditions is set to nil to ignore any existing conditions,
+and :graph_block is used to set up the case insensitive comparison.
+
+Another case where :graph_only_conditions may be used is if you want to use
+a JOIN USING or NATURAL JOIN for the graph:
+
+  # JOIN USING
+  Artist.one_to_many :albums, :key=>:artist_name,
+   :graph_only_conditions=>[:artist_name]
+
+  # NATURAL JOIN
+  Artist.one_to_many :albums, :key=>:artist_name,
+   :graph_only_conditions=>nil, :graph_join_type=>:natural
+
+==== :graph_alias_base
+
+The base name to use for the table alias when eager graphing.  Defaults to the name
+of the association.  If the alias name has already been used in the query, Sequel will create
+a unique alias by appending a numeric suffix (e.g. alias_0, alias_1, ...) until the alias is
+unique.
+
+This is mostly useful if you have associations with the same name in many models, and you want
+to be able to easily tell which table alias corresponds to which association when eagerly
+graphing multiple associations with the same name.
+
+You can override this option on a per-graph basis by specifying the association as an
+SQL::AliasedExpression instead of a symbol:
+
+  Album.eager_graph(Sequel.as(:artist, :a))
+
+==== :eager_grapher
+
+Sets up a custom grapher to use when eager loading the objects via eager_graph.
+This is the eager_graph analogue to the :eager_loader option. This isn't generally
+needed, as one of the other eager_graph related association options is usually sufficient.
+
+If specified, should be a proc that accepts a single hash argument, which will contain
+at least the following keys:
+
+: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:
+
+  Artist.one_to_many :self_title_albums, :class=>:Album,
+   :eager_grapher=>(proc do |eo|
+    eo[:self].graph(Album, {:artist_id=>:id, :name=>:name},
+      :table_alias=>eo[:table_alias], :implicit_qualifier=>eo[:implicit_qualifier])
+  end)
+
+==== :order_eager_graph
+
+Whether to add the order to the dataset's order when graphing via eager_graph.
+Defaults to true, so set to false to disable.
+
+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_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
+of two element arrays.
+
+Let's say you have a database of people, colleges, and a table called
+degrees_received that includes a string field specifying the name of the
+degree, and you want to eager load all colleges for people where the person
+has received a specific degree:
+
+  Person.many_to_many :bs_degree_colleges, :class=>:College,
+    :join_table=>:degrees_received, 
+    :graph_join_table_conditions=>{:degree=>'BS'}
+
+==== :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,
+but is only used for +many_to_many+ associations when graphing the join
+table into the dataset.  It's used in the same place as
+:graph_join_table_conditions but like :graph_block, is needed for situations
+where the conditions can't be specified as a hash or array of two element
+arrays.
+
+Let's say you have a database of people, colleges, and a table called
+degrees_received that includes a string field specifying the name of the
+degree, and you want to eager load all colleges for people where the person
+has received a bachelor's degree (degree starting with B):
+
+  Person.many_to_many :bachelor_degree_colleges, :class=>:College,
+    :join_table=>:degrees_received,
+    :graph_join_table_block=>proc{|j,lj,js| Sequel.qualify(j, :degree).like('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+, +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
+:left_outer.  This exists mainly for consistency in the unlikely case that
+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+, +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
+by the foreign/primary keys.  This option causes the
+:graph_join_table_conditions option to be ignored.  This is only useful if
+you want to replace the default foreign/primary key conditions that Sequel
+would use when eagerly graphing.
+
+=== Column Naming Conflict Options
+
+Sequel's association support historically called methods on model objects
+to get primary key or foreign key values instead of accessing the column
+values directly, in order to allow advanced features such as associations
+based on virtual column keys.  Unfortunately, that causes issues if columns
+are used with names that clash with existing method names, which can happen
+if you want to name the association the same name as an existing column, or
+if the column has the same name as an already defined method such as
+<tt>object_id</tt>.
+
+Sequel has added the following options that allow you to work around the
+issue by either specifying the column name symbol or the method name symbol
+to use.  In most cases, these methods are designed to be used with column
+aliases defined with <tt>Model.def_column_alias</tt>:
+
+  # Example schema:
+  #  albums           artists
+  #   :id        /-->  :id
+  #   :artist --/      :name
+  #   :name
+  class Album < Sequel::Model
+    def_column_alias(:artist_id, :artist)
+    many_to_one :artist, :key=>:artist_id, :key_column=>:artist
+  end
+  
+  # Example schema:
+  #  things              objs
+  #   :id           /-->  :id
+  #   :object_id --/      :name
+  #   :name
+  class Thing < Sequel::Model
+    def_column_alias(:obj_id, :object_id)
+  end
+  class Obj < Sequel::Model
+    one_to_many :things, :key=>:object_id, :key_method=>:obj_id
+  end
+
+==== :key_column [+many_to_one+]
+
+Like the :key option, but :key references the method name, while
+:key_column references the underlying column.
+
+==== :primary_key_method [+many_to_one+]
+
+Like the :primary_key option, but :primary_key references the column
+name, while :primary_key_method references the method name.
+
+==== :primary_key_column [+one_to_many+, +one_to_one+]
+
+Like the :primary_key option, but :primary_key references the method name, while
+:primary_key_column references the underlying column.
+
+==== :key_method [+one_to_many+, +one_to_one+]
+
+Like the :key option, but :key references the column
+name, while :key_method references the method name.
+
+==== :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+, +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.
+
+=== Private Method Overriding Options
+
+These options override the private methods that Sequel defines to do
+the actual work of associating and deassociating objects.
+
+==== :setter [*_to_one associations]
+
+This overrides the default behavior when you call an association setter
+method.  Let's say you want to set a specific field whenever associating an object
+using the association setter method.
+
+  class Album < Sequel::Model
+    many_to_one :artist, :setter=>(proc do |artist|
+      if artist
+        self.artist_id = artist.id
+        self.file_under = "#{artist.name}-#{name}"
+      else
+        self.artist_id = nil
+        self.file_under = name
+      end
+    end)
+  end
+
+==== :adder [*_to_many associations]
+
+Continuing with the same example, here's how you would handle the same case if
+you also wanted to handle the Artist#add_album method:
+
+  class Artist < Sequel::Model
+    one_to_many :albums, :adder=>(proc do |album|
+      album.update(:artist_id => id, :file_under=>"#{name}-#{album.name}")
+    end)
+  end
+
+==== :remover [*_to_many associations]
+
+Continuing with the same example, here's how you would handle the same case if
+you also wanted to handle the Artist#remove_album method:
+
+  class Artist < Sequel::Model
+    one_to_many :albums, :remover=>(proc do |album|
+      album.update(:artist_id => nil, :file_under=>album.name)
+    end)
+  end
+
+==== :clearer [*_to_many associations]
+
+Continuing with the same example, here's how you would handle the same case if
+you also wanted to handle the Artist#remove_all_albums method:
+
+  class Artist < Sequel::Model
+    one_to_many :albums, :clearer=>(proc do
+      albums_dataset.update(:artist_id => nil, :file_under=>:name)
+    end)
+  end
+
+=== Advanced Options
+
+==== :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
+associations for a association that matches the current association's key(s).
+Set to nil to not use a reciprocal.
+
+Reciprocals are used in Sequel to modify the matching cached associations
+in associated objects when calling association methods on the current object.
+For example, when you retrieve objects in a one_to_many association, it'll
+automatically set the matching many_to_one association in the associated
+objects.  The result of this is that code that does this:
+
+  @artist.albums.each{|album| album.artist.name}
+  
+only does one database query, because when the @artist's albums are retrieved,
+the cached artist association for each album is set to @artist.
+
+In addition to the one_to_many retrieval case, the association modification
+methods affect the reciprocals as well:
+
+  # Sets the cached artist association for @album to @artist
+  @artist.add_album(@album)
+  
+  # Sets the cached artist association for @album to nil
+  @artist.remove_album(@album)
+  
+  # Sets the cached artist association to nil for the @artist's
+  # cached albums association
+  @artist.remove_all_albums
+  
+  # Remove @album from the artist1's cached albums association, and add @album
+  # to @artist2's cached albums association.
+  @album.artist # @artist1
+  @album.artist = @artist2
+
+Sequel can usually guess the correct reciprocal, but if you have multiple
+associations to the same associated class that use the same keys, you may
+want to specify the :reciprocal option manually to ensure the correct
+one is used.
+
+==== :read_only
+
+For +many_to_one+ and +one_to_one+ associations, do not add a setter method.
+For +one_to_many+ and +many_to_many+, do not add the add_<i>association</i>,
+remove_<i>association</i>, or remove_all_<i>association</i> methods.
+
+If the default modification methods would not do what you want, and you
+don't plan on overriding the internal modification methods to do what you
+want, it may be best to set this option to true.
+
+==== :validate
+
+Set to false to not validate when implicitly saving any associated object.
+When using the +one_to_many+ association modification methods, the +one_to_one+
+setter method, or creating a new object by passing a hash to the
+add_<i>association</i> method, Sequel will automatically save the object.
+If you don't want to validate objects when these implicit saves are done,
+the validate option should be set to false.
+
+==== :raise_on_save_failure [+one_to_many+ associations]
+
+Set to false to not raise an exception when validation or a before hook
+fails when implicitly saving an associated object in the add_* or remove_*
+methods.  This mirrors the raise_on_save_failure model setting, which these
+methods do not respect (by design, since the setting is dangerous).
+
+If you use this option, you must explicitly check all add_* and remove_* return
+values to see if they were successful.
+
+==== :allow_eager
+
+If set to false, you cannot load the association eagerly via eager or
+eager_graph.
+
+  Artist.one_to_many :albums, :allow_eager=>false
+  Artist.eager(:albums) # Raises Sequel::Error
+
+This is usually used if the association dataset depends on specific values in
+model instance that would not be valid when eager loading for multiple
+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 *_one
+associations, 1 for *_to_many associations).
+
+This should only be modified in specific cases.  For example, if you have
+a one_to_one association that can actually return more than one row
+(where the default association method will just return the first), or
+a many_to_many association where there is a unique index in the join table
+so that you know only one object will ever be associated through the
+association.
+
+==== :methods_module
+
+The module that the methods created by the association will be placed
+into.  Defaults to the module containing the model's columns.  This
+is not included in the model's class, so you are responsible for doing
+that manually.
+
+This is only useful in rare cases, such as when a plugin that adds
+associations depends on another plugin that defines instance methods of
+the same name.  In that case, the instance methods of the dependent
+plugin would override the association methods created by the main
+plugin.
+
+==== :eager_limit_strategy
+
+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.
+
+In general, Sequel picks an appropriate strategy, so it is not usually
+necessary to specify a strategy.  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:
+
+:union :: Uses one or more UNION queries with a subquery for each record
+          you are eagerly loading for (this is the default strategy).
+:distinct_on :: Uses DISTINCT ON to ensure only the first matching record
+                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.
+:ruby :: Uses ruby array slicing to emulate database limiting/offsetting.
+
+==== :subqueries_per_union
+
+The number of subqueries per union query to use when eager loading for a
+limited association using a union strategy.  This defaults to 40, but the
+optimum number depends on the database in use and the latency between the
+database and the application.
+
+==== :filter_limit_strategy
+
+The strategy to use when filtering by limited associations.  In general
+Sequel will choose either a :distinct_on, :window_function, or
+:correlated_subquery strategy based on the association type and what
+the database supports, but you can override that if necessary using
+this option.
+