= 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.where(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 create 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 'many_to_one' 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 'one_to_many' 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.

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 references 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 :albums, 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 cannot 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_predecessors, left_key: :successor_id,
      right_key: :predecessor_id, join_table: :edges, class: self
    many_to_many :direct_successors, 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

Note that the remove_all_* method does not call remove hooks defined on
the association, it just issues a single query to the database.  If you
want to remove all associated objects and call remove hooks, iterate
over the array of associated objects and call remove_* for each:

  @artist.albums.each do |album|
    @artist.remove_album(album)
  end

== 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 <tt>reload: true</tt> option to the association method:

  @album.artists # Not cached - Database Query
  @album.artists # Cached - No Database Query
  @album.artists(reload: 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 ...>, ...]

=== Code Reloading

When declaring associations, Sequel caches association metadata in the association reflection. If you're doing any code reloading that doesn't involve restarting the related process, you should disable caching of the association reflection, to avoid stale model classes still being referenced after reloading:

  Sequel::Model.cache_associations = false

== Dataset Method

In addition to the above methods, associations also add an 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, null: false, unique: true
  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, null: false
    String :name, null: false, unique: true
  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, null: false
  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, null: false
    foreign_key :artist_id, :artists, null: false
    primary_key [:album_id, :artist_id]
    index [:artist_id, :album_id]
  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_(opts={}) (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 previously cached associated
records, or nil if there were no cached associated records.

=== <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 preceded 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.

=== :setter (_<i>association</i>= method)

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, setter: (lambda 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

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.

=== :adder (\_add_<i>association</i> method)

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: (lambda do |album|
      album.update(artist_id: id, file_under: "#{name}-#{album.name}")
    end)
  end

You can set this to +nil+ to not create a add_<i>association</i> method.

=== :remover (\_remove_<i>association</i> method)

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: (lambda do |album|
      album.update(artist_id: nil, file_under: album.name)
    end)
  end

You can set this to +nil+ to not create a remove_<i>association</i> method.

=== :clearer (\_remove_all_<i>association</i> method)

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: (lambda do
      # 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

You can set this to +nil+ to not create a remove_all_<i>association</i> method.

=== :no_dataset_method

Setting this to true will not result in the <i>association</i>_dataset method
not being defined. This can save memory if you only use the <i>association</i>
method and do not call the <i>association</i>_dataset method directly or
indirectly.

=== :no_association_method

Setting this to true will not result in the <i>association</i> method
not being defined. This can save memory if you only use the
<i>association</i>_dataset method and do not call the <i>association</i> method
directly or indirectly.

== Association Options

Sequel's associations mostly share the same options.  For ease of understanding,
they are grouped here by section.

The defaults for any of these options can be set at the class level using
<tt>Sequel::Model.default_association_options</tt>.  To make
associations read only by default:

  Sequel::Model.default_association_options[:read_only] = true

Many of these options are specific to particular association types, and
the defaults can be set on a per association type basis.  To make one_to_many
associations read only by default:

  Sequel::Model.default_association_type_options[:one_to_many] = {read_only: true}

=== 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

The result of the block is cached as an optimization.  One of the side
effects of that is that if your block depends on external state, it won't
work correctly unless you setup a delayed evaluation.  For example:

  Artist.one_to_many :gold_albums, class: :Album do |ds|
    ds.where{copies_sold > $gold_limit}
  end

In this case if you change <tt>$gold_limit</tt> later, the changes won't
effect the association.  If you want to pick up changes to <tt>$gold_limit</tt>,
you need to setup a delayed evaluation:

  Artist.one_to_many :gold_albums, class: :Album do |ds|
    ds.where{copies_sold > Sequel.delay{$gold_limit}}
  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, including considering the namespace
of the current model.  If a *_to_many association is used, this uses the
singular form of the association name.  For example:

  Album.many_to_one :artist # guesses Artist
  Artist.one_to_many :albums # guesses Album
  Foo::Artist.one_to_many :albums # guesses Foo::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

If you are namespacing your models, and you need to specify the :class
option, the path you give to the :class option should be the full path
to the associated class including any namespaces:

  Foo::Album.many_to_one :artist                       # Uses Foo::Artist
  Foo::Album.many_to_one :artist, class: "Artist"      # Uses Artist
  Foo::Album.many_to_one :artist, class: "Foo::Artist" # Uses Foo::Artist

==== :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.

  Album.many_to_one :artist, key: :artistid

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: :artistid

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 or association_join to load the association.

If you do not use a hash or array of two element arrays, you should use the
:graph_conditions, :graph_only_conditions, or :graph_block option or you will not
be able to use eager_graph or association_join with 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[:tags].*, Sequel[: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

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 addition 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:

  Artist.one_to_many :songs, dataset: (lambda do |r|
    r.associated_dataset.select_all(:songs).
     join(:lyrics, 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, class: :Album, join_table_block: (lambda do |ds|
    ds.where(instrument_id: 5)
  end)

==== :join_table_db [+many_to_many+, +one_through_one+]

A Sequel::Database to use for the join table.  Specifying this option switches the
loading to use a separate query for the join table.  This is useful if the
join table is not located in the same database as the associated table, or
if the database account with access to the associated table doesn't have
access to the join table.

For example, if the Album class uses a different Sequel::Database than the Artist
class, and the join table is in the database that the Artist class uses:

  Artist.many_to_many :lead_guitar_albums, class: :Album, join_table_db: Artist.db

This option also affects the add/remove/remove_all methods, by changing
which database is used for inserts/deletes from the join table (add/remove/remove_all
defaults to use the current model's database instead of the associated model's database).

=== 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 call Model#cancel_action 
to signal Sequel to abort the modification.  If any before callback
calls cancel_action, the remaining before callbacks are not called and the modification
is aborted.

==== :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: lambda{|ar, al| ar.cancel_action 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 using <tt>remove_<i>association</i></tt>:

  class Artist
    # Don't allow removing a self-titled album
    one_to_many :albums, before_remove: lambda{|ar, al| ar.cancel_action if al.name == ar.name}
  end

This is not called when using <tt>remove_all_<i>association</i></tt>.

==== :after_remove [+one_to_many+, +many_to_many+]

Called after removing an object from the association using <tt>remove_<i>association</i></tt>:

  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

This is not called when using <tt>remove_all_<i>association</i></tt>.

==== :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: lambda{|al, ar| al.cancel_action 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(&: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, set 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[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 do |j,lj,js|
      {Sequel.function(:lower, Sequel[j][:artist_name])=> Sequel.function(:lower, Sequel[lj][:name])}
    end)

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-eager_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: (lambda do |eo|
    eo[:self].graph(:albums, {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[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.

=== Associations Based on SQL Expressions Options

Sequel's associations can work not just with columns, but also with
arbitrary SQL expressions.  For example, on PostgreSQL, you can store
foreign keys to other tables in hstore, json, or jsonb columns, and Sequel
can work with such constructs, including full support for
eager loading.

There's actually two parts to supporting associations based on SQL
expressions.  First is you must have an instance method in the model
that returns the value that the SQL expression would return. Second
is you must have an SQL expression object.  If Sequel has access to
a model instance and needs to get the value of the expression, it
calls the method to get the value.  If Sequel does not have access
to a model instance, but needs to use the SQL expression in a query,
it will use the SQL expression object.

Below is an example storing foreign keys to other tables in a
PostgreSQL hstore column, using the +pg_json+ and +pg_json_ops+
extensions.

  # Example schema:
  #  albums          artists
  #   :id       /---> :id
  #   :meta ---/      :name
  #   :name
  class Album < Sequel::Model
    many_to_one :artist, key_column: Sequel.pg_jsonb(:meta)['artist_id'].cast(String).cast(Integer)

    def artist_id
      meta['artist_id'].to_i
    end
  end
  class Artist < Sequel::Model
    one_to_many :albums, key: Sequel.pg_jsonb(:meta)['artist_id'].cast(String).cast(Integer), key_method: :artist_id
  end
  
  # Example schema:
  #  albums   albums_artists   artists
  #   :id  <----- :meta -------> :id
  #   :name                      :name
  class Album < Sequel::Model
    many_to_many :artists, left_key: Sequel.pg_jsonb(:meta)['album_id'].cast(String).cast(Integer),
      right_key: Sequel.pg_jsonb(:meta)['artist_id'].cast(String).cast(Integer)
  end
  class Artist < Sequel::Model
    many_to_many :albums, left_key: Sequel.pg_jsonb(:meta)['artist_id'].cast(String).cast(Integer),
      right_key: Sequel.pg_jsonb(:meta)['album_id'].cast(String).cast(Integer)
  end

==== :key_column [+many_to_one+]

Like the :key option, but :key references the method name, while
:key_column references the underlying column/expression.

==== :primary_key_method [+many_to_one+]

Like the :primary_key option, but :primary_key references the column/expression
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/expression.

==== :key_method [+one_to_many+, +one_to_one+]

Like the :key option, but :key references the column/expression
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/expression.

==== :right_primary_key_method [+many_to_many+, +one_through_one+]

Like the :right_primary_key option, but :right_primary_key references the column/expression
name, while :right_primary_key_method references the method name.

=== 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, Sequel will
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 you are not using the association modification methods, setting this
value to true will save memory.

==== :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).

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
  Artist.eager_graph(: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.

==== :allow_eager_graph

If set to false, you cannot load the association eagerly via eager_graph.

  Artist.one_to_many :albums, allow_eager_graph: false
  Artist.eager(:albums)       # Allowed
  Artist.eager_graph(:albums) # Raises Sequel::Error

This is useful if you still want to allow loading via eager, but do not want
to allow loading via eager graph, possibly because the association does not
support joins.

==== :allow_filtering_by

If set to false, you cannot use the association when filtering.

  Artist.one_to_many :albums, allow_filtering_by: false
  Artist.where(albums: Album.where(name: 'A')).all # Raises Sequel::Error

This is useful if such filtering cannot work, such as when a subquery cannot
be used because the necessary tables are not in the same database.

==== :instance_specific

This allows you to override the setting of whether the dataset contains instance
specific code.  If you are passing a block to the association,
Sequel sets this to true by default, which disables some optimizations that
would be invalid if the association is instance specific.  If you know that the
block does not contain instance specific code, you can set this to false to
reenable the optimizations.  Instance specific code is mostly commonly calling
model instance methods inside an association block, but also
includes cases where the association block can return different values based
on the runtime environment, such as calls to <tt>Time.now</tt> in the block.
Associations that use the :dataset option are always considered instance specific,
even if explicitly specified otherwise.

==== :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.

==== :class_namespace

If the :class option is specified as a symbol or string, the default namespace
in which to look up the class. If the :class option is not specified as a
symbol or string, this option is ignored.  This namespace can be overridden
by starting the string or symbol with <tt>::</tt>:

  Foo::Album.many_to_one :artist, class: "Artist"                                # Uses Artist
  Foo::Album.many_to_one :artist, class: "Artist", class_namespace: 'Foo'        # Uses Foo::Artist
  Foo::Album.many_to_one :artist, class: "Foo::Artist", class_namespace: 'Foo'   # Uses Foo::Foo::Artist
  Foo::Album.many_to_one :artist, class: "::Artist", class_namespace: 'Foo'      # Uses Artist
  Foo::Album.many_to_one :artist, class: "::Foo::Artist", class_namespace: 'Foo' # Uses Foo::Artist

==== :methods_module

The module that the methods created by the association will be placed
into.  Defaults to the module containing the model's columns.  Any module
given to this option is not included in the model's class automatically,
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.