tdiary 5.0.6 → 5.0.7

data/vendor/bundle/gems/sequel-5.3.0/bin/sequel

@@ -0,0 +1,250 @@
+#!/usr/bin/env ruby
+# frozen-string-literal: true
+
+require 'optparse'
+
+code = nil
+copy_databases = nil
+dump_migration = nil
+dump_schema = nil
+env = nil
+migrate_dir = nil
+migrate_ver = nil
+backtrace = nil
+show_version = false
+test = true
+load_dirs = []
+exclusive_options = []
+loggers = []
+
+options = OptionParser.new do |opts|
+  opts.banner = "Sequel: The Database Toolkit for Ruby"
+  opts.define_head "Usage: sequel [options] <uri|path> [file]"
+  opts.separator ""
+  opts.separator "Examples:"
+  opts.separator "  sequel sqlite://blog.db"
+  opts.separator "  sequel postgres://localhost/my_blog"
+  opts.separator "  sequel config/database.yml"
+  opts.separator ""
+  opts.separator "For more information see http://sequel.jeremyevans.net"
+  opts.separator ""
+  opts.separator "Options:"
+
+  opts.on_tail("-h", "-?", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+
+  opts.on("-c", "--code CODE", "run the given code and exit") do  |v|
+    code = v
+    exclusive_options << :c
+  end
+  
+  opts.on("-C", "--copy-databases", "copy one database to another") do 
+    copy_databases = true
+    exclusive_options << :C
+  end
+  
+  opts.on("-d", "--dump-migration", "print database migration to STDOUT") do 
+    dump_migration = true
+    exclusive_options << :d
+  end
+  
+  opts.on("-D", "--dump-migration-same-db", "print database migration to STDOUT without type translation") do
+    dump_migration = :same_db
+    exclusive_options << :D
+  end
+
+  opts.on("-e", "--env ENV", "use environment config for database") do |v|
+    env = v
+  end
+  
+  opts.on("-E", "--echo", "echo SQL statements") do
+    require 'logger'
+    loggers << Logger.new($stdout)
+  end
+  
+  opts.on("-I", "--include dir", "specify $LOAD_PATH directory") do |v|
+    $: << v
+  end
+
+  opts.on("-l", "--log logfile", "log SQL statements to log file") do |v|
+    require 'logger'
+    loggers << Logger.new(v)
+  end
+  
+  opts.on("-L", "--load-dir DIR", "loads all *.rb under specifed directory") do |v|
+    load_dirs << v
+  end
+  
+  opts.on("-m", "--migrate-directory DIR", "run the migrations in directory") do |v|
+    migrate_dir = v
+    exclusive_options << :m
+  end
+  
+  opts.on("-M", "--migrate-version VER", "migrate the database to version given") do |v|
+    migrate_ver = Integer(v, 10)
+  end
+
+  opts.on("-N", "--no-test-connection", "do not test the connection") do
+    test = false
+  end
+
+  opts.on("-r", "--require LIB", "require the library, before executing your script") do |v|
+    load_dirs << [v]
+  end
+
+  opts.on("-S", "--dump-schema filename", "dump the schema for all tables to the file") do |v|
+    dump_schema = v
+    exclusive_options << :S
+  end
+
+  opts.on("-t", "--trace", "Output the full backtrace if an exception is raised") do
+    backtrace = true
+  end
+  
+  opts.on_tail("-v", "--version", "Show version") do
+    show_version = true
+  end
+end
+opts = options
+opts.parse!
+
+db = ARGV.shift
+
+error_proc = lambda do |msg|
+  $stderr.puts(msg)
+  exit 1
+end
+extra_proc = lambda do
+  $stderr.puts("Warning: last #{ARGV.length} arguments ignored") unless ARGV.empty?
+end
+
+error_proc["Error: Must specify -m if using -M"] if migrate_ver && !migrate_dir
+error_proc["Error: Cannot specify #{exclusive_options.map{|v| "-#{v}"}.join(' and ')} together"] if exclusive_options.length > 1
+
+connect_proc = lambda do |database|
+  db_opts = {:test=>test, :loggers=>loggers}
+  if database.nil? || database.empty?
+    Sequel.connect('mock:///', db_opts)
+  elsif File.exist?(database)
+    require 'yaml'
+    env ||= "development"
+    db_config = YAML.load_file(database)
+    db_config = db_config[env] || db_config[env.to_sym] || db_config
+    db_config.keys.each{|k| db_config[k.to_sym] = db_config.delete(k)}
+    Sequel.connect(db_config, db_opts)
+  else
+    Sequel.connect(database, db_opts)
+  end
+end
+
+begin
+  $:.unshift(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib')))
+  require 'sequel'
+  if show_version
+    puts "sequel #{Sequel.version}"
+    unless db || code
+      exit
+    end
+  end
+
+  DB = connect_proc[db]
+  load_dirs.each{|d| d.is_a?(Array) ? require(d.first) : Dir["#{d}/**/*.rb"].each{|f| load(f)}}
+  if migrate_dir
+    extra_proc.call
+    Sequel.extension :migration, :core_extensions
+    Sequel::Migrator.apply(DB, migrate_dir, migrate_ver)
+    exit
+  end
+  if dump_migration
+    extra_proc.call
+    DB.extension :schema_dumper
+    puts DB.dump_schema_migration(:same_db=>dump_migration==:same_db)
+    exit
+  end
+  if dump_schema
+    extra_proc.call
+    DB.extension :schema_caching
+    DB.tables.each{|t| DB.schema(Sequel::SQL::Identifier.new(t))}
+    DB.dump_schema_cache(dump_schema)
+    exit
+  end
+  if copy_databases
+    Sequel.extension :migration
+    DB.extension :schema_dumper
+
+    db2 = ARGV.shift
+    error_proc["Error: Must specify database connection string or path to yaml file as second argument for database you want to copy to"] if db2.nil? || db2.empty?
+    extra_proc.call
+    start_time = Time.now
+    TO_DB = connect_proc[db2]
+    same_db = DB.database_type==TO_DB.database_type
+    index_opts = {:same_db=>same_db}
+    index_opts[:index_names] = :namespace if !DB.global_index_namespace? && TO_DB.global_index_namespace?
+
+    puts "Databases connections successful"
+    schema_migration = eval(DB.dump_schema_migration(:indexes=>false, :same_db=>same_db))
+    index_migration = eval(DB.dump_indexes_migration(index_opts))
+    fk_migration = eval(DB.dump_foreign_key_migration(:same_db=>same_db))
+    puts "Migrations dumped successfully"
+
+    schema_migration.apply(TO_DB, :up)
+    puts "Tables created"
+
+    puts "Begin copying data"
+    DB.transaction do
+      TO_DB.transaction do
+        DB.tables.each do |table|
+          puts "Begin copying records for table: #{table}"
+          time = Time.now
+          to_ds = TO_DB.from(table)
+          j = 0
+          DB.from(table).each do |record|
+            if Time.now - time > 5
+              puts "Status: #{j} records copied" 
+              time = Time.now
+            end
+            to_ds.insert(record)
+            j += 1
+          end
+          puts "Finished copying #{j} records for table: #{table}"
+        end
+      end
+    end
+    puts "Finished copying data"
+
+    puts "Begin creating indexes"
+    index_migration.apply(TO_DB, :up)
+    puts "Finished creating indexes"
+
+    puts "Begin adding foreign key constraints"
+    fk_migration.apply(TO_DB, :up)
+    puts "Finished adding foreign key constraints"
+
+    if TO_DB.database_type == :postgres
+      TO_DB.tables.each{|t| TO_DB.reset_primary_key_sequence(t)}
+      puts "Primary key sequences reset successfully"
+    end
+    puts "Database copy finished in #{Time.now - start_time} seconds"
+    exit
+  end
+  if code
+    extra_proc.call
+    eval(code)
+    exit
+  end
+rescue => e
+  raise e if backtrace
+  error_proc["Error: #{e.class}: #{e.message}\n#{e.backtrace.first}"]
+end
+
+if !ARGV.empty? 
+  ARGV.each{|v| load(v)}
+elsif !$stdin.isatty
+  eval($stdin.read)
+else
+  require 'irb'
+  puts "Your database is stored in DB..."
+  IRB.start
+end

data/vendor/bundle/gems/sequel-5.3.0/doc/advanced_associations.rdoc

@@ -0,0 +1,764 @@
+= Advanced Associations
+
+Sequel::Model's association support is very powerful and flexible, but using that power and flexibility
+often results in complexity.
+
+You should probably review the {Model Associations Basics and Options guide}[rdoc-ref:doc/association_basics.rdoc]
+before reviewing this guide.
+
+== Background: Sequel::Model association options
+
+There are a bunch of advanced association options that are available to
+handle more complex cases.  First we'll go over some of the simpler ones:
+
+All associations take a block that can be used to further filter/modify the
+default dataset.  There's also an :eager_block option if you want to use
+a different block when eager loading via <tt>Dataset#eager</tt>. Association blocks are
+useful for things like:
+
+  Artist.one_to_many :gold_albums, class: :Album do |ds|
+    ds.where{copies_sold > 500000}
+  end
+
+There are a whole bunch of options for changing how the association is eagerly
+loaded via <tt>Dataset#eager_graph</tt>: <tt>:graph_block</tt>, <tt>:graph_conditions</tt>,
+<tt>:graph_only_conditions</tt>, <tt>:graph_join_type</tt> (and <tt>:graph_join_table_*</tt> ones for
+JOINing to the join table in a many_to_many association).
+
+:graph_join_type :: The type of join to do (<tt>:inner</tt>, <tt>:left</tt>, <tt>:right</tt>)
+:graph_conditions :: Additional conditions to put on join (needs to be a
+                     hash or array of all two pairs).  Automatically assumes unqualified symbols
+                     or first element of the pair to be columns of the associated model, and
+                     unqualified symbols of the second element of the pair to be columns of the
+                     current model.
+:graph_block :: A block passed to +join_table+, allowing you to specify
+                conditions other than equality, or to use OR, or set up any arbitrary
+                condition.  The block is passed the associated table alias, current table 
+                alias, and an array of previous joins clause objects.
+:graph_only_conditions :: Use these conditions instead of the standard
+                          association conditions. This is necessary when you don't want to have an
+                          equal condition between the foreign key and primary key of the tables.
+                          You can also use this to have a JOIN USING (array of symbols), or a NATURAL
+                          or CROSS JOIN (nil, with the appropriate <tt>:graph_join_type</tt>).
+  
+These can be used like this:
+
+  # Makes Artist.eager_graph(:required_albums).all not return artists that
+  # don't have any albums
+  Artist.one_to_many :required_albums, class: :Album, graph_join_type: :inner
+  
+  # Makes sure all returned albums have the active flag set
+  Artist.one_to_many :active_albums, class: :Album, graph_conditions: {active: true}
+    
+  # Only returns albums that have sold more than 500,000 copies
+  Artist.one_to_many :gold_albums, class: :Album,
+    graph_block: proc{|j,lj,js| Sequel[j][:copies_sold] > 500000}
+    
+  # Handles the case where the tables are associated by a case insensitive name string
+  Artist.one_to_many :albums, key: :artist_name,
+    graph_only_conditions: nil,
+    graph_block: proc{|j,lj,js| {Sequel.function(:lower, Sequel[j][:artist_name])=>Sequel.function(:lower, Sequel[lj][:name])}}
+    
+  # Handles the case where both key columns have the name artist_name, and you want to use
+  # a JOIN USING
+  Artist.one_to_many :albums, key: :artist_name, graph_only_conditions: [:artist_name]
+  
+Remember, using +eager_graph+ is generally only necessary when you need to
+filter/order based on columns in an associated table, it is recommended to
+use +eager+ for eager loading if possible.
+
+One advantage of using +eager_graph+ is that you can easily filter/order
+on columns in an associated table on a per-query basis, using regular
+Sequel dataset methods.  For example, if you only want to retrieve artists
+who have albums that start with A, and eager load just those albums,
+ordered by the albums name, you can do:
+
+  albums = Artist.
+    eager_graph(:albums).
+    where{Sequel.like(albums[:name], 'A%')}.
+    order{albums[:name]}.
+    all
+
+For lazy loading (e.g. Model[1].association), the <tt>:dataset</tt> option can be used
+to specify an arbitrary dataset (one that uses different keys, multiple keys,
+joins to other tables, etc.).
+
+For eager loading via +eager+, the <tt>:eager_loader</tt> option can be used to specify
+how to eagerly load a complex association.  This is an extremely powerful
+option.  Though it can often be verbose (compared to other things in Sequel),
+it allows you complete control over how to eagerly load associations for a
+group of objects.
+
+:eager_loader should be a proc that takes a single hash argument, which will
+have at least the following keys:
+
+:id_map :: A mapping of key values to arrays of current model instances,
+           usage described below
+:rows :: An array of model objects
+:associations :: A hash of dependent associations to eagerly load
+:self :: The dataset that is doing the eager loading
+:eager_block :: A dynamic callback for this eager load.
+
+Since you are given all of the records, you can do things like filter on
+associations that are specified by multiple keys, or do multiple
+queries depending on the content of the records (which would be
+necessary for polymorphic associations).  Inside the <tt>:eager_loader</tt>
+proc, you should get the related objects and populate the
+associations cache for all objects in the array of records.  The hash
+of dependent associations is available for you to cascade the eager
+loading down multiple levels, but it is up to you to use it.
+
+The id_map is a performance enhancement that is used by the default
+association loaders and is also available to you.  It is a hash with keys
+foreign/primary key values, and values being arrays of current model
+objects having the foreign/primary key value associated with the key. 
+This may be hard to visualize, so I'll give an example.  Let's say you
+have the following associations
+
+  Album.many_to_one :artist
+  Album.one_to_many :tracks
+    
+and the following three albums in the database:
+
+  album1 = Album.create(:artist_id=>3) # id: 1
+  album2 = Album.create(:artist_id=>3) # id: 2
+  album3 = Album.create(:artist_id=>2) # id: 3
+
+If you try to eager load this dataset:
+
+  Album.eager(:artist, :tracks).all
+
+Then the id_map provided to the artist :eager_loader proc would be:
+
+  {3=>[album1, album2], 2=>[album3]}
+
+The artist id_map contains a mapping of artist_id values to arrays of
+album objects.  Since both album1 and album2 have the same artist_id,
+the are both in the array related to that key.  album3 has a different
+artist_id, so it is in a different array. Eager loading of artists is
+done by looking for any artist having one of the keys in the hash:
+
+  artists = Artist.where(:id=>id_map.keys).all
+
+When the artists are retrieved, you can iterate over them, find entries
+with matching keys, and manually associate them to the albums:
+
+  artists.each do |artist|
+    # Find related albums using the artist_id_map
+    if albums = id_map[artist.id]
+      # Iterate over the albums
+      albums.each do |album|
+        # Manually set the artist association for each album
+        album.associations[:artist] = artist
+      end
+    end
+  end
+
+The id_map provided to the tracks :eager_loader proc would be:
+
+  {1=>[album1], 2=>[album2], 3=>[album3]}
+
+Now the id_map contains a mapping of id values to arrays of album objects (in this
+case each array only has a single object, because id is the primary key).  So when
+looking for tracks to eagerly load, you only need to look for ones that have an
+album_id with one of the keys in the hash:
+
+  tracks = Track.where(:album_id=>id_map.keys).all
+
+When the tracks are retrieved, you can iterate over them, find entries with matching
+keys, and manually associate them to the albums:
+
+  tracks.each do |track|
+    if albums = id_map[track.album_id]
+      albums.each do |album|
+        album.associations[:tracks] << track
+      end
+    end
+  end
+
+=== Two basic example eager loaders
+
+Putting the code in the above examples together, you almost have enough for a basic
+working eager loader.  The main important thing that is missing is you need to set
+initial values for the eagerly loaded associations.  For the artist association, you
+need to initial the values to nil:
+
+  # rows here is the :rows entry in the hash passed to the eager loader
+  rows.each{|album| album.associations[:artist] = nil}
+  
+For the tracks association, you set the initial value to an empty array:
+
+  rows.each{|album| album.associations[:track] = []}
+
+These are done so that if an album currently being loaded doesn't have an associated
+artist or any associated tracks, the lack of them will be cached, so calling the
+artist or tracks method on the album will not do another database lookup.
+
+So putting everything together, the artist eager loader looks like:
+
+  Album.many_to_one :artist, :eager_loader=>(proc do |eo_opts|
+    eo_opts[:rows].each{|album| album.associations[:artist] = nil}
+    id_map = eo_opts[:id_map]
+    Artist.where(:id=>id_map.keys).all do |artist|
+      if albums = id_map[artist.id]
+        albums.each do |album|
+          album.associations[:artist] = artist
+        end
+      end
+    end
+  end)
+
+and the tracks eager loader looks like:
+
+  Album.one_to_many :tracks, :eager_loader=>(proc do |eo_opts|
+    eo_opts[:rows].each{|album| album.associations[:tracks] = []}
+    id_map = eo_opts[:id_map]
+    Track.where(:album_id=>id_map.keys).all do |track|
+      if albums = id_map[track.album_id]
+        albums.each do |album|
+          album.associations[:tracks] << track
+        end
+      end
+    end
+  end)
+
+Now, these are both overly simplistic eager loaders that don't respect cascaded
+associations or any of the association options.  But hopefully they both
+provide simple examples that you can more easily build and learn from, as 
+the custom eager loaders described later in this page are more complex.
+
+Basically, the eager loading steps can be broken down into:
+
+1. Set default association values (nil/[]) for each of the current objects
+2. Return just related associated objects by filtering the associated class
+   to include only rows with keys present in the id_map.
+3. Iterating over the returned associated objects, indexing into the id_map
+   using the foreign/primary key value in the associated object to get
+   current values associated to that specific object.
+4. For each of those current values, updating the cached association value to
+   include that specific object.
+
+Using the :eager_loader proc, you should be able to eagerly load all associations
+that can be eagerly loaded, even if Sequel doesn't natively support such eager
+loading.
+
+== Limited Associations
+
+Sequel supports specifying limits and/or offsets for associations:
+
+  Artist.one_to_many :first_10_albums, class: :Album, order: :release_date, limit: 10
+
+For retrieving the associated objects for a single object, this just uses
+a LIMIT:
+
+  artist.first_10_albums
+  # SELECT * FROM albums WHERE (artist_id = 1) LIMIT 10
+
+=== Eager Loading via eager
+
+However, if you want to eagerly load an association, you must use a different
+approach.  Sequel has 4 separate strategies for dealing with such cases.
+
+The default strategy used on all databases is a UNION-based approach, which
+will submit multiple subqueries in a UNION query:
+
+  Artist.where(id: [1,2]).eager(:first_10_albums).all
+  # SELECT * FROM (SELECT * FROM albums WHERE (artist_id = 1) LIMIT 10) UNION ALL
+  # SELECT * FROM (SELECT * FROM albums WHERE (artist_id = 2) LIMIT 10)
+
+This is the fastest way to load the associated objects on most databases, as long as
+there is an index on albums.artist_id.  Without an index it is probably the slowest
+approach, so make sure you have an index on the key columns.  If you cannot add an
+index, you'll want to manually specify the :eager_limit_strategy option as shown below.
+
+On PostgreSQL, for *_one associations that don't use an offset, you can
+choose to use a the distinct on strategy:
+
+  Artist.one_to_one :first_album, class: :Album, order: :release_date,
+    eager_limit_strategy: :distinct_on
+  Artist.where(id: [1,2]).eager(:first_album).all
+  # SELECT DISTINCT ON (albums.artist_id) *
+  # FROM albums
+  # WHERE (albums.artist_id IN (1, 2))
+  # ORDER BY albums.artist_id, release_date
+  
+Otherwise, if the database supports window functions, you can choose to use
+the window function strategy:
+
+  Artist.one_to_many :first_10_albums, class: :Album, order: :release_date, limit: 10,
+    eager_limit_strategy: :window_function
+  Artist.where(:id=>[1,2]).eager(:first_10_albums).all
+  # SELECT * FROM (
+  #   SELECT *, row_number() OVER (PARTITION BY albums.artist_id ORDER BY release_date) AS x_sequel_row_number_x
+  #   FROM albums
+  #   WHERE (albums.artist_id IN (1, 2))
+  # ) AS t1
+  # WHERE (x_sequel_row_number_x <= 10)
+  
+Alternatively, you can use the :ruby strategy, which will fall back to
+retrieving all records, and then will slice the resulting array to get
+the first 10 after retrieval.
+
+=== Dynamic Eager Loading Limits
+
+If you need to eager load variable numbers of records (with limits that aren't
+known at the time of the association definition), Sequel supports an
+:eager_limit dataset option that can be defined in an eager loading callback:
+
+  Artist.one_to_many :albums
+  Artist.where(id: [1, 2]).eager(albums: lambda{|ds| ds.order(:release_date).clone(eager_limit: 3)}).all
+  # SELECT * FROM (
+  #   SELECT *, row_number() OVER (PARTITION BY albums.artist_id ORDER BY release_date) AS x_sequel_row_number_x
+  #   FROM albums
+  #   WHERE (albums.artist_id IN (1, 2))
+  # ) AS t1
+  # WHERE (x_sequel_row_number_x <= 3)
+
+You can also customize the :eager_limit_strategy on a case-by-case basis by passing in that option in the same way:
+
+  Artist.where(id: [1, 2]).eager(albums: lambda{|ds| ds.order(:release_date).clone(eager_limit: 3, eager_limit_strategy: :ruby)}).all
+  # SELECT * FROM albums WHERE (albums.artist_id IN (1, 2)) ORDER BY release_date
+
+The :eager_limit and :eager_limit_strategy options currently only work when
+eager loading via #eager, not with #eager_graph.
+
+=== Eager Loading via eager_graph_with_options
+
+When eager loading an association via eager_graph (which uses JOINs), the
+situation is similar.  While the UNION-based strategy cannot be used as
+you don't know the records being eagerly loaded in advance, Sequel can use
+a variant of the other 3 strategies.  By default it retrieves all records
+and then does the array slice in ruby.  As eager_graph does not support
+options, to use an eager_graph limit strategy you have to use the
+eager_graph_with_options method with the :limit_strategy option.
+
+The :distinct_on strategy uses DISTINCT ON in a subquery and JOINs that
+subquery:
+
+  Artist.eager_graph_with_options(:first_album, limit_strategy: :distinct_on).all
+  # SELECT artists.id, artists.name, first_album.id AS first_album_id,
+  #        first_album.name AS first_album_name, first_album.artist_id,
+  #        first_album.release_date
+  # FROM artists 
+  # LEFT OUTER JOIN (
+  #   SELECT DISTINCT ON (albums.artist_id) *
+  #   FROM albums
+  #   ORDER BY albums.artist_id, release_date
+  # ) AS first_album ON (first_album.artist_id = artists.id)
+
+The :window_function approach JOINs to a nested subquery using a window
+function:
+
+  Artist.eager_graph_with_options(:first_10_albums, limit_strategy: :window_function).all
+  # SELECT artists.id, artists.name, first_10_albums.id AS first_10_albums_id,
+  #        first_10_albums.name AS first_10_albums_name, first_10_albums.artist_id,
+  #        first_10_albums.release_date
+  # FROM artists 
+  # LEFT OUTER JOIN (
+  #   SELECT id, name, artist_id, release_date
+  #   FROM (
+  #     SELECT *, row_number() OVER (PARTITION BY tracks.album_id ORDER BY release_date) AS x_sequel_row_number_x
+  #     FROM albums
+  #   ) AS t1 WHERE (x_sequel_row_number_x <= 10)
+  # ) AS first_10_albums ON (first_10_albums.artist_id = artists.id)
+
+The :correlated_subquery approach JOINs to a nested subquery using a correlated
+subquery:
+
+  Artist.eager_graph_with_options(:first_10_albums, :limit_strategy=>:correlated_subquery).all
+  # SELECT artists.id, artists.name, first_10_albums.id AS first_10_albums_id,
+  #        first_10_albums.name AS first_10_albums_name, first_10_albums.artist_id,
+  #        first_10_albums.release_date
+  # FROM artists 
+  # LEFT OUTER JOIN (
+  #   SELECT *
+  #   FROM albums
+  #   WHERE albums.id IN (
+  #     SELECT t1.id
+  #     FROM tracks AS t1
+  #     WHERE (t1.album_id = tracks.album_id)
+  #     ORDER BY release_date
+  #     LIMIT 10
+  #   )
+  # ) AS first_10_albums ON (first_10_albums.artist_id = artists.id)
+
+The reason that Sequel does not automatically use the :distinct_on, :window function
+or :correlated_subquery strategy for eager_graph is that it can perform much worse than the
+default of just doing the array slicing in ruby.  If you are only using eager_graph to
+return a few records, it may be cheaper to get all of their associated records and filter
+them in ruby as opposed to computing the set of limited associated records for all rows.
+
+It's recommended to only use an eager_graph limit strategy if you have benchmarked
+it against the default behavior and found it is faster for your use case.
+
+=== Filtering By Associations
+
+In order to return correct results, Sequel automatically uses a limit strategy when
+using filtering by associations with limited associations, if the database supports
+it.  As in the eager_graph case, the UNION-based strategy doesn't work.  Unlike
+in the eager and eager_graph cases, the array slicing in ruby approach does not work,
+you must use an SQL-based strategy.  Sequel will select an appropriate default
+strategy based on the database you are using, and you can override it using the
+:filter_limit_strategy option.
+
+The :distinct_on strategy:
+
+  Artist.where(first_album: Album[1]).all
+  # SELECT *
+  # FROM artists
+  # WHERE (artists.id IN (
+  #   SELECT albums.artist_id
+  #   FROM albums
+  #   WHERE ((albums.artist_id IS NOT NULL) AND (albums.id IN (
+  #     SELECT DISTINCT ON (albums.artist_id) albums.id
+  #     FROM albums
+  #     ORDER BY albums.artist_id, release_date
+  #   )) AND (albums.id = 1))))
+
+The :window_function strategy:
+
+  Artist.where(first_10_albums: Album[1]).all
+  # SELECT *
+  # FROM artists
+  # WHERE (artists.id IN (
+  #   SELECT albums.artist_id
+  #   FROM albums
+  #   WHERE ((albums.artist_id IS NOT NULL) AND (albums.id IN (
+  #     SELECT id FROM (
+  #       SELECT albums.id, row_number() OVER (PARTITION BY albums.artist_id ORDER BY release_date) AS x_sequel_row_number_x
+  #       FROM albums
+  #     ) AS t1
+  #     WHERE (x_sequel_row_number_x <= 10)
+  #   )) AND (albums.id = 1))))
+
+The :correlated_subquery strategy:
+
+  Artist.where(first_10_albums: Album[1]).all
+  # SELECT *
+  # FROM artists
+  # WHERE (artists.id IN (
+  #   SELECT albums.artist_id
+  #   FROM albums
+  #   WHERE ((albums.artist_id IS NOT NULL) AND (albums.id IN (
+  #     SELECT t1.id
+  #     FROM albums AS t1
+  #     WHERE (t1.artist_id = albums.artist_id)
+  #     ORDER BY release_date
+  #     LIMIT 1
+  #   )) AND (albums.id = 1))))
+
+Note that filtering by limited associations does not work on MySQL, as MySQL does not support
+any of the strategies.  It's also not supported when using composite keys on databases
+that don't support window functions and don't support multiple columns in IN.
+
+=== Additional Association Types
+
+While the above examples for limited associations showed one_to_many and one_to_one associations,
+it's just because those are the simplest examples.  Sequel supports all of the same features for
+many_to_many and one_through_one associations that are enabled by default, as well as the
+many_through_many and one_through_many associations that are added by the many_through_many
+plugin.
+
+== More advanced association examples 
+
+=== Association extensions
+
+All associations come with an <tt><i>association</i>_dataset</tt> method that can be further filtered or
+otherwise modified:
+
+  class Author < Sequel::Model
+    one_to_many :authorships
+  end
+  Author.first.authorships_dataset.where{number < 10}.first
+ 
+You can extend a dataset with a module using the <tt>:extend</tt> association option.  You can reference
+the model object that created the association dataset via the dataset's
++model_object+ method, and the related association reflection via the dataset's
++association_reflection+ method:
+
+  module FindOrCreate
+    def find_or_create(vals)
+      first(vals) || model.create(vals.merge(association_reflection[:key]=>model_object.id))
+    end
+  end
+  class Author < Sequel::Model
+    one_to_many :authorships, extend: FindOrCreate
+  end
+  Author.first.authorships_dataset.find_or_create(name: 'Blah', number: 10)
+
+=== many_to_many associations through model tables
+
+The many_to_many association can be used even when the join table is a table used for a
+model.  The only requirement is the join table has foreign keys to both the current
+model and the associated model.  Anytime there is a one_to_many association from model A to
+model B, and model B has a many_to_one association to model C, you can use a many_to_many
+association from model A to model C.
+
+  class Author < Sequel::Model
+    one_to_many :authorships
+    many_to_many :books, join_table: :authorships
+  end
+
+  class Authorship < Sequel::Model
+    many_to_one :author
+    many_to_one :book
+  end
+
+  @author = Author.first
+  @author.books
+
+=== many_to_many for three-level associations
+
+You can even use a many_to_many association between model A and model C if model A has a
+one_to_many association to model B, and model B has a one_to_many association to model C.
+You just need to use the appropriate :right_key and :right_primary_key options.  And in
+the reverse direction from model C to model A, you can use a one_through_one association
+using the :left_key and :left_primary_key options.
+
+  class Firm < Sequel::Model
+    one_to_many :clients
+    many_to_many :invoices, join_table: :clients, right_key: :id, right_primary_key: :client_id
+  end 
+
+  class Client < Sequel::Model
+    many_to_one :firm
+    one_to_many :invoices
+  end
+
+  class Invoice < Sequel::Model
+    many_to_one :client
+    one_through_one :firm, join_table: :clients, left_key: :id, left_primary_key: :client_id
+  end
+
+  Firm.first.invoices
+  Invoice.first.firm
+
+To handle cases where there are multiple join tables, you can use the many_through_many
+plugin that ships with Sequel.
+
+=== Polymorphic Associations
+
+Sequel discourages the use of polymorphic associations, which is the reason they
+are not supported by default.  All polymorphic associations can be made non-polymorphic
+by using additional tables and/or columns instead of having a column
+containing the associated class name as a string.
+
+Polymorphic associations break referential integrity and are significantly more
+complex than non-polymorphic associations, so their use is not recommended unless
+you are stuck with an existing design that uses them.
+
+If you must use them, look for the sequel_polymorphic external plugin, as it makes using
+polymorphic associations in Sequel about as easy as it is in ActiveRecord.  However,
+here's how they can be done using Sequel's custom associations (the sequel_polymorphic
+external plugin is just a generic version of this code):
+
+  class Asset < Sequel::Model
+    many_to_one :attachable, reciprocal: :assets,
+      setter: (lambda do |attachable|
+        self[:attachable_id] = (attachable.pk if attachable)
+        self[:attachable_type] = (attachable.class.name if attachable)
+      end),
+      dataset: (proc do
+        klass = attachable_type.constantize
+        klass.where(klass.primary_key=>attachable_id)
+      end),
+      eager_loader: (lambda do |eo|
+        id_map = {}
+        eo[:rows].each do |asset|
+          asset.associations[:attachable] = nil 
+          ((id_map[asset.attachable_type] ||= {})[asset.attachable_id] ||= []) << asset
+        end
+        id_map.each do |klass_name, id_map|
+          klass = klass_name.constantize
+          klass.where(klass.primary_key=>id_map.keys).all do |attach|
+            id_map[attach.pk].each do |asset|
+              asset.associations[:attachable] = attach
+            end
+          end
+        end
+      end)
+  end 
+
+  class Post < Sequel::Model
+    one_to_many :assets, key: :attachable_id, reciprocal: :attachable, conditions: {attachable_type: 'Post'},
+      adder: lambda{|asset| asset.update(attachable_id: pk, attachable_type: 'Post')},
+      remover: lambda{|asset| asset.update(attachable_id: nil, attachable_type: nil)},
+      clearer: lambda{assets_dataset.update(attachable_id: nil, attachable_type: nil)}
+  end
+
+  class Note < Sequel::Model
+    one_to_many :assets, key: :attachable_id, reciprocal: :attachable, conditions: {attachable_type: 'Note'},
+      adder: lambda{|asset| asset.update(attachable_id: pk, attachable_type: 'Note')},
+      remover: lambda{|asset| asset.update(attachable_id: nil, attachable_type: nil)},
+      clearer: lambda{assets_dataset.update(attachable_id: nil, attachable_type: nil)}
+  end
+
+  @asset.attachable = @post
+  @asset.attachable = @note
+
+=== Joining on multiple keys
+
+Let's say you have two tables that are associated with each other with multiple
+keys.  This can be handled using Sequel's built in composite key support for
+associations:
+
+  # Both of these models have an album_id, number, and disc_number fields.
+  # All FavoriteTracks have an associated track, but not all tracks have an
+  # associated favorite track
+  
+  class Track < Sequel::Model
+    many_to_one :favorite_track, key: [:disc_number, :number, :album_id], primary_key: [:disc_number, :number, :album_id]
+  end
+  class FavoriteTrack < Sequel::Model
+    one_to_one :tracks, key: [:disc_number, :number, :album_id], primary_key: [:disc_number, :number, :album_id]
+  end
+
+=== Tree - All Ancestors and Descendents
+
+Let's say you want to store a tree relationship in your database, it's pretty
+simple:
+
+  class Node < Sequel::Model
+    many_to_one :parent, class: self
+    one_to_many :children, key: :parent_id, class: self
+  end
+  
+You can easily get a node's parent with node.parent, and a node's children with
+node.children.  You can even eager load the relationship up to a certain depth:
+
+  # Eager load three generations of generations of children for a given node 
+  Node.where(id: 1).eager(children: {children: :children}).all.first
+  # Load parents and grandparents for a group of nodes
+  Node.where{id < 10}.eager(parent: :parent).all
+
+What if you want to get all ancestors up to the root node, or all descendents,
+without knowing the depth of the tree?
+
+  class Node < Sequel::Model
+    many_to_one :ancestors, class: self,
+     eager_loader: (lambda do |eo|
+      # Handle cases where the root node has the same parent_id as primary_key
+      # and also when it is NULL
+      non_root_nodes = eo[:rows].reject do |n| 
+        if [nil, n.pk].include?(n.parent_id)
+          # Make sure root nodes have their parent association set to nil
+          n.associations[:parent] = nil 
+          true
+        else
+          false
+        end 
+      end 
+      unless non_root_nodes.empty?
+        id_map = {}
+        # Create an map of parent_ids to nodes that have that parent id
+        non_root_nodes.each{|n| (id_map[n.parent_id] ||= []) << n}
+        # Doesn't cause an infinte loop, because when only the root node
+        # is left, this is not called.
+        Node.where(id: id_map.keys).eager(:ancestors).all do |node|
+          # Populate the parent association for each node
+          id_map[node.pk].each{|n| n.associations[:parent] = node}
+        end 
+      end 
+    end)
+    many_to_one :descendants, eager_loader: (lambda do |eo|
+      id_map = {}
+      eo[:rows].each do |n| 
+        # Initialize an empty array of child associations for each parent node
+        n.associations[:children] = []
+        # Populate identity map of nodes
+        id_map[n.pk] = n 
+      end 
+      # Doesn't cause an infinite loop, because the :eager_loader is not called
+      # if no records are returned.  Exclude id = parent_id to avoid infinite loop
+      # if the root note is one of the returned records and it has parent_id = id
+      # instead of parent_id = NULL.
+      Node.where(parent_id: id_map.keys).exclude(id: :parent_id).eager(:descendants).all do |node|
+        # Get the parent from the identity map
+        parent = id_map[node.parent_id]
+        # Set the child's parent association to the parent 
+        node.associations[:parent] = parent
+        # Add the child association to the array of children in the parent
+        parent.associations[:children] << node
+      end 
+    end)
+  end
+
+Note that Sequel ships with an rcte_tree plugin that does all of the above and more:
+
+  class Node < Sequel::Model
+    plugin :rcte_tree
+  end
+
+=== Joining multiple keys to a single key, through a third table
+
+Let's say you have a database of songs, lyrics, and artists.  Each song
+may or may not have a lyric (most songs are instrumental).  The lyric can be
+associated to an artist in each of four ways: composer, arranger, vocalist,
+or lyricist.  These may all be the same, or they could all be different, and
+none of them are required.  The songs table has a lyric_id field to associate
+it to the lyric, and the lyric table has four fields to associate it to the
+artist (composer_id, arranger_id, vocalist_id, and lyricist_id).
+
+What you want to do is get all songs for a given artist, ordered by the song's
+name, with no duplicates?
+
+  class Artist < Sequel::Model
+    one_to_many :songs, order: Sequel[:songs][:name],
+      dataset: proc{Song.select_all(:songs).join(:lyrics, id: :lyric_id, id=>[:composer_id, :arranger_id, :vocalist_id, :lyricist_id])},
+      eager_loader: (lambda do |eo|
+        h = eo[:id_map]
+        ids = h.keys
+        eo[:rows].each{|r| r.associations[:songs] = []}
+        Song.select_all(:songs).
+          select_append{[lyrics[:composer_id], lyrics[:arranger_id], lyrics[:vocalist_id], lyrics[:lyricist_id]]}.
+          join(:lyrics, id: :lyric_id){Sequel.or(composer_id: ids, arranger_id: ids, vocalist_id: ids, lyricist_id: ids)}.
+          order{songs[:name]}.all do |song|
+            [:composer_id, :arranger_id, :vocalist_id, :lyricist_id].each do |x|
+              recs = h[song.values.delete(x)]
+              recs.each{|r| r.associations[:songs] << song} if recs
+            end
+          end
+        eo[:rows].each{|r| r.associations[:songs].uniq!}
+      end)
+  end
+
+=== Statistics Associations (Sum of Associated Table Column)
+
+In addition to getting associated records, you can use Sequel's association support
+to get aggregate information for columns in associated tables (sums, averages, etc.).
+
+Let's say you have a database with projects and tickets.  A project can have many
+tickets, and each ticket has a number of hours associated with it.  You can use the
+association support to create a Project association that gives the sum of hours for all
+associated tickets.
+
+  class Project < Sequel::Model
+    one_to_many :tickets
+    many_to_one :ticket_hours, read_only: true, key: :id,
+     dataset: proc{Ticket.where(:project_id=>id).select{sum(hours).as(hours)}},
+     eager_loader: (lambda do |eo|
+      eo[:rows].each{|p| p.associations[:ticket_hours] = nil}
+      Ticket.where(project_id: eo[:id_map].keys).
+       select_group(:project_id).
+       select_append{sum(hours).as(hours)}.
+       all do |t|
+        p = eo[:id_map][t.values.delete(:project_id)].first
+        p.associations[:ticket_hours] = t
+       end
+     end)
+    # The association method returns a Ticket object with a single aggregate
+    # sum-of-hours value, but you want it to return an Integer/Float of just the
+    # sum of hours, so you call super and return just the sum-of-hours value.
+    # This works for both lazy loading and eager loading.
+    def ticket_hours
+      if s = super
+        s[:hours]
+      end
+    end
+  end
+  class Ticket < Sequel::Model
+    many_to_one :project
+  end
+
+Note that it is often better to use a sum cache instead of this approach.  You can implement
+a sum cache using +after_create+, +after_update+, and +after_delete+ hooks, or preferrably using a database trigger.