sequel 3.21.0 → 3.36.0

data/MIT-LICENSE

@@ -1,5 +1,5 @@
 Copyright (c) 2007-2008 Sharon Rosner
-Copyright (c) 2008-2011 Jeremy Evans
+Copyright (c) 2008-2012 Jeremy Evans
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

data/README.rdoc

@@ -12,15 +12,15 @@ toolkit for Ruby.
   two-phase commit, transaction isolation, master/slave
   configurations, and database sharding.
 * Sequel currently has adapters for ADO, Amalgalite, DataObjects,
-  DB2, DBI, Firebird, Informix, JDBC, MySQL, Mysql2, ODBC, OpenBase,
-  Oracle, PostgreSQL, SQLite3, Swift, and TinyTDS.
+  DB2, DBI, Firebird, IBM_DB, Informix, JDBC, MySQL, Mysql2, ODBC,
+  OpenBase, Oracle, PostgreSQL, SQLite3, Swift, and TinyTDS.
 
 == Resources
 
 * {Website}[http://sequel.rubyforge.org]
 * {Blog}[http://sequel.heroku.com]
 * {Source code}[http://github.com/jeremyevans/sequel]
-* {Bug tracking}[http://code.google.com/p/ruby-sequel/issues/list]
+* {Bug tracking}[http://github.com/jeremyevans/sequel/issues]
 * {Google group}[http://groups.google.com/group/sequel-talk]
 * {RDoc}[http://sequel.rubyforge.org/rdoc]
 
@@ -64,12 +64,14 @@ If you have any comments or suggestions please post to the Google group.
 
 == The Sequel Console
 
-Sequel includes an IRB console for quick access to databases. You can use it like this:
+Sequel includes an IRB console for quick access to databases (usually referred to as <tt>bin/sequel</tt>). You can use it like this:
 
   sequel sqlite://test.db # test.db in current directory
 
 You get an IRB session with the database object stored in DB.
 
+In addition to providing an IRB shell (the default behavior), bin/sequel also has support for migrating databases (-m and -M), dumping schema migrations (-d and -D), and copying databases (-C).
+
 == An Introduction
 
 Sequel is designed to take the hassle away from connecting to databases and manipulating them. Sequel deals with all the boring stuff like maintaining connections, formatting SQL correctly and fetching records so you can concentrate on your application.
@@ -573,7 +575,7 @@ You can execute custom code when creating, updating, or deleting records by defi
 
 Note the use of +super+ if you define your own hook methods.  Almost all <tt>Sequel::Model</tt> class and instance methods (not just hook methods) can be overridden safely, but you have to make sure to call +super+ when doing so, otherwise you risk breaking things.
 
-For the example above, you should probably use a database trigger if you can.  Hooks can be used for data integrity, but they will only enforce that integrity when you are modifying the database through model instances.  If you plan on allowing any other access to the database, it's best to use database triggers for data integrity.
+For the example above, you should probably use a database trigger if you can.  Hooks can be used for data integrity, but they will only enforce that integrity when you are modifying the database through model instances.  If you plan on allowing any other access to the database, it's best to use database triggers and constraints for data integrity.
 
 === Deleting records
 
@@ -681,9 +683,23 @@ Associations can be eagerly loaded via +eager+ and the <tt>:eager</tt> associati
   # Loads all people, their posts, their posts' tags, replies to those posts,
   # the person for each reply, the tag for each reply, and all posts and
   # replies that have that tag.  Uses a total of 8 queries.
-  Person.eager(:posts=>{:replies=>[:person, {:tags=>{:posts, :replies}}]}).all
+  Person.eager(:posts=>{:replies=>[:person, {:tags=>[:posts, :replies]}]}).all
+
+In addition to using +eager+, you can also use +eager_graph+, which will use a single query to get the object and all associated objects.  This may be necessary if you want to filter or order the result set based on columns in associated tables.  It works with cascading as well, the API is very similar.  Note that using +eager_graph+ to eagerly load multiple <tt>*_to_many</tt> associations will cause the result set to be a cartesian product, so you should be very careful with your filters when using it in that case.
+
+You can dynamically customize the eagerly loaded dataset by using using a proc.  This proc is passed the dataset used for eager loading, and should return a modified copy of that dataset:
+
+  # Eagerly load only replies containing 'foo'
+  Post.eager(:replies=>proc{|ds| ds.filter(text.like('%foo%'))}).all
+
+This also works when using +eager_graph+, in which case the proc is called with dataset to graph into the current dataset:
+
+  Post.eager_graph(:replies=>proc{|ds| ds.filter(text.like('%foo%'))}).all
+
+You can dynamically customize eager loads for both +eager+ and +eager_graph+ while also cascading, by making the value a single entry hash with the proc as a key, and the cascaded associations as the value:
 
-In addition to using +eager+, you can also use +eager_graph+, which will use a single query to get the object and all associated objects.  This may be necessary if you want to filter or order the result set based on columns in associated tables.  It works with cascading as well, the syntax is exactly the same.  Note that using eager_graph to eagerly load multiple *_to_many associations will cause the result set to be a cartesian product, so you should be very careful with your filters when using it in that case.
+  # Eagerly load only replies containing 'foo', and the person and tags for those replies
+  Post.eager(:replies=>{proc{|ds| ds.filter(text.like('%foo%'))}=>[:person, :tags]}).all
 
 === Extending the underlying dataset
 

data/Rakefile

@@ -1,11 +1,5 @@
 require "rake"
 require "rake/clean"
-require "rake/gempackagetask"
-begin
-  require "hanna/rdoctask"
-rescue LoadError
-  require "rake/rdoctask"
-end
 
 NAME = 'sequel'
 VERS = lambda do
@@ -13,24 +7,24 @@ VERS = lambda do
   Sequel.version
 end
 CLEAN.include ["**/.*.sw?", "sequel-*.gem", ".config", "rdoc", "coverage", "www/public/*.html", "www/public/rdoc*", '**/*.rbc']
-RDOC_DEFAULT_OPTS = ["--quiet", "--line-numbers", "--inline-source", '--title', 'Sequel: The Database Toolkit for Ruby']
-RDOC_OPTS = RDOC_DEFAULT_OPTS + ['--main', 'README.rdoc']
+SUDO = ENV['SUDO'] || 'sudo'
 
 # Gem Packaging and Release
 
 desc "Packages sequel"
 task :package=>[:clean] do |p|
-  sh %{gem build sequel.gemspec}
+  load './sequel.gemspec'
+  Gem::Builder.new(SEQUEL_GEMSPEC).build
 end
 
 desc "Install sequel gem"
 task :install=>[:package] do
-  sh %{sudo gem install ./#{NAME}-#{VERS.call} --local}
+  sh %{#{SUDO} gem install ./#{NAME}-#{VERS.call} --local}
 end
 
 desc "Uninstall sequel gem"
 task :uninstall=>[:clean] do
-  sh %{sudo gem uninstall #{NAME}}
+  sh %{#{SUDO} gem uninstall #{NAME}}
 end
 
 desc "Upload sequel gem to gemcutter"
@@ -40,7 +34,20 @@ end
 
 ### RDoc
 
-Rake::RDocTask.new do |rdoc|
+RDOC_DEFAULT_OPTS = ["--quiet", "--line-numbers", "--inline-source", '--title', 'Sequel: The Database Toolkit for Ruby']
+
+rdoc_task_class = begin
+  require "rdoc/task"
+  RDOC_DEFAULT_OPTS.concat(['-f', 'hanna'])
+  RDoc::Task
+rescue LoadError
+  require "rake/rdoctask"
+  Rake::RDocTask
+end
+
+RDOC_OPTS = RDOC_DEFAULT_OPTS + ['--main', 'README.rdoc']
+
+rdoc_task_class.new do |rdoc|
   rdoc.rdoc_dir = "rdoc"
   rdoc.options += RDOC_OPTS
   rdoc.rdoc_files.add %w"README.rdoc CHANGELOG MIT-LICENSE lib/**/*.rb doc/*.rdoc doc/release_notes/*.txt"
@@ -50,25 +57,25 @@ end
 
 desc "Make local version of website"
 task :website do
-  sh %{www/make_www.rb}
+  sh %{#{FileUtils::RUBY} www/make_www.rb}
 end
 
 desc "Make rdoc for website"
 task :website_rdoc=>[:website_rdoc_main, :website_rdoc_adapters, :website_rdoc_plugins]
 
-Rake::RDocTask.new(:website_rdoc_main) do |rdoc|
+rdoc_task_class.new(:website_rdoc_main) do |rdoc|
   rdoc.rdoc_dir = "www/public/rdoc"
   rdoc.options += RDOC_OPTS
   rdoc.rdoc_files.add %w"README.rdoc CHANGELOG MIT-LICENSE lib/*.rb lib/sequel/*.rb lib/sequel/{connection_pool,dataset,database,model}/*.rb doc/*.rdoc doc/release_notes/*.txt lib/sequel/extensions/migration.rb"
 end
 
-Rake::RDocTask.new(:website_rdoc_adapters) do |rdoc|
+rdoc_task_class.new(:website_rdoc_adapters) do |rdoc|
   rdoc.rdoc_dir = "www/public/rdoc-adapters"
   rdoc.options += RDOC_DEFAULT_OPTS + %w'--main Sequel'
   rdoc.rdoc_files.add %w"lib/sequel/adapters/**/*.rb"
 end
 
-Rake::RDocTask.new(:website_rdoc_plugins) do |rdoc|
+rdoc_task_class.new(:website_rdoc_plugins) do |rdoc|
   rdoc.rdoc_dir = "www/public/rdoc-plugins"
   rdoc.options += RDOC_DEFAULT_OPTS + %w'--main Sequel'
   rdoc.rdoc_files.add %w"lib/sequel/{extensions,plugins}/**/*.rb"
@@ -92,11 +99,13 @@ begin
     require "spec/rake/spectask"
     spec_class = Spec::Rake::SpecTask
     spec_files_meth = :spec_files=
+    spec_opts_meth = :spec_opts=
   rescue LoadError
     # RSpec 2
     require "rspec/core/rake_task"
     spec_class = RSpec::Core::RakeTask
     spec_files_meth = :pattern=
+    spec_opts_meth = :rspec_opts=
   end
 
   spec = lambda do |name, files, d|
@@ -105,26 +114,35 @@ begin
     desc d
     spec_class.new(name) do |t|
       t.send spec_files_meth, files
-      t.spec_opts = ENV['SEQUEL_SPEC_OPTS'].split if ENV['SEQUEL_SPEC_OPTS']
+      t.send spec_opts_meth, ENV['SEQUEL_SPEC_OPTS'].split if ENV['SEQUEL_SPEC_OPTS']
     end
   end
 
-  spec_with_cov = lambda do |name, files, d|
+  spec_with_cov = lambda do |name, files, d, &b|
     spec.call(name, files, d)
     t = spec.call("#{name}_cov", files, "#{d} with coverage")
     t.rcov = true
     t.rcov_opts = File.read("spec/rcov.opts").split("\n")
+    b.call(t) if b
+    t
   end
-  
+
   task :default => [:spec]
-  spec_with_cov.call("spec", Dir["spec/{core,model}/*_spec.rb"], "Run core and model specs")
+  spec_with_cov.call("spec", Dir["spec/{core,model}/*_spec.rb"], "Run core and model specs"){|t| t.rcov_opts.concat(%w'--exclude "lib/sequel/(adapters/([a-ln-z]|m[a-np-z])|extensions/core_extensions)"')}
   spec.call("spec_core", Dir["spec/core/*_spec.rb"], "Run core specs")
   spec.call("spec_model", Dir["spec/model/*_spec.rb"], "Run model specs")
-  spec_with_cov.call("spec_plugin", Dir["spec/extensions/*_spec.rb"], "Run extension/plugin specs")
+  spec.call("_spec_model_no_assoc", Dir["spec/model/*_spec.rb"].delete_if{|f| f =~ /association|eager_loading/}, '')
+  spec_with_cov.call("spec_plugin", Dir["spec/extensions/*_spec.rb"], "Run extension/plugin specs"){|t| t.rcov_opts.concat(%w'--exclude "lib/sequel/([a-z_]+\.rb|adapters|connection_pool|database|dataset|model)"')}
   spec_with_cov.call("spec_integration", Dir["spec/integration/*_test.rb"], "Run integration tests")
   
-  %w'postgres sqlite mysql informix oracle firebird mssql'.each do |adapter|
-    spec_with_cov.call("spec_#{adapter}", ["spec/adapters/#{adapter}_spec.rb"] + Dir["spec/integration/*_test.rb"], "Run #{adapter} specs")
+  %w'postgres sqlite mysql informix oracle firebird mssql db2'.each do |adapter|
+    spec_with_cov.call("spec_#{adapter}", ["spec/adapters/#{adapter}_spec.rb"] + Dir["spec/integration/*_test.rb"], "Run #{adapter} specs"){|t| t.rcov_opts.concat(%w'--exclude "lib/sequel/([a-z_]+\.rb|connection_pool|database|dataset|model|extensions|plugins)"')}
+  end
+
+  desc "Run model specs without the associations code"
+  task :spec_model_no_assoc do
+    ENV['SEQUEL_NO_ASSOCIATIONS'] = '1'
+    Rake::Task['_spec_model_no_assoc'].invoke
   end
 rescue LoadError
   task :default do
@@ -154,5 +172,5 @@ end
 
 desc "Check syntax of all .rb files"
 task :check_syntax do
-  Dir['**/*.rb'].each{|file| print `#{ENV['RUBY'] || :ruby} -c #{file} | fgrep -v "Syntax OK"`}
+  Dir['**/*.rb'].each{|file| print `#{FileUtils::RUBY} -c #{file} | fgrep -v "Syntax OK"`}
 end

data/bin/sequel

@@ -7,6 +7,7 @@ require 'sequel'
 db_opts = {:test=>true}
 copy_databases = nil
 dump_migration = nil
+dump_schema = nil
 echo = nil
 env = nil
 logfile = nil
@@ -14,6 +15,7 @@ migrate_dir = nil
 migrate_ver = nil
 backtrace = nil
 load_dirs = []
+exclusive_options = []
 
 opts = OptionParser.new do |opts|
   opts.banner = "Sequel: The Database Toolkit for Ruby"
@@ -39,10 +41,12 @@ opts = OptionParser.new do |opts|
   
   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|
@@ -67,6 +71,7 @@ opts = OptionParser.new do |opts|
   
   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|
@@ -81,6 +86,11 @@ opts = OptionParser.new do |opts|
     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
@@ -100,8 +110,7 @@ error_proc = lambda do |msg|
 end
 
 error_proc["Error: Must specify -m if using -M"] if migrate_ver && !migrate_dir
-error_proc["Error: Cannot specify -D or -d with -m"] if dump_migration && migrate_dir
-error_proc["Error: Cannot specify -C with -d, -D, or -m"] if copy_databases && (dump_migration || migrate_dir)
+error_proc["Error: Cannot specify #{exclusive_options.map{|v| "-#{v}"}.join(' and ')} together"] if exclusive_options.length > 1
 
 if logfile || echo
   require 'logger'
@@ -112,11 +121,7 @@ end
 
 connect_proc = lambda do |database|
   db = if database.nil? || database.empty?
-    db = Sequel::Database.new(:quote_identifiers=>false)
-    def db.connect(*args); Object.new; end
-    db.identifier_input_method = nil
-    db.identifier_output_method = nil
-    db
+    Sequel.connect('mock:///', db_opts)
   elsif File.exist?(database)
     require 'yaml'
     env ||= "development"
@@ -143,6 +148,12 @@ begin
     puts DB.dump_schema_migration(:same_db=>dump_migration==:same_db)
     exit
   end
+  if dump_schema
+    Sequel.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, :schema_dumper
 
@@ -151,10 +162,13 @@ begin
     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(: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)
@@ -186,6 +200,10 @@ begin
     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"

data/doc/active_record.rdoc

@@ -694,6 +694,7 @@ ActiveRecord Method :: Sequel Method
 +set_primary_key+ :: +set_primary_key+
 +sum+ :: +sum+
 +table_name+ :: +table_name+
++unescoped+ :: +unfiltered+
 
 === Class Methods without an Equivalent
 

data/doc/advanced_associations.rdoc

@@ -96,25 +96,168 @@ 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
-key_hash is a performance enhancement that is used by the default
+loading down multiple levels, but it is up to you to use it.
+
+The key_hash is a performance enhancement that is used by the default
 association loaders and is also available to you.  It is a hash with keys being
 foreign/primary key symbols in the current table, and the values
 being hashes where the key is foreign/primary key values and values
 being arrays of current model objects having the foreign/primary key
 value associated with the key.  This is hard to visualize, so I'll
-give an example:
-    
-  album1 = Album.load(:id=>1, :artist_id=>2)
-  album2 = Album.load(:id=>3, :artist_id=>2)
+give an example.  Let's say you have the following associations
+
   Album.many_to_one :artist
   Album.one_to_many :tracks
-  Album.eager(:band, :tracks).all
-  # The key_hash provided to the :eager_loader proc would be:
-  {:id=>{1=>[album1], 3=>[album2]}, :artist_id=>{2=>[album1, album2]}}
+    
+and the following two albums in the database:
+
+  album1 = Album.create(:artist_id=>3) # id: 1
+  album2 = Album.create(:artist_id=>3) # id: 2
+
+If you try to eager load this dataset:
+
+  Album.eager(:artist, :tracks).all
+
+Then the key_hash provided to the :eager_loader proc would be:
+
+  {:id=>{1=>[album1], 2=>[album2]}, :artist_id=>{3=>[album1, album2]}}
+
+Let's break down the reason for the makeup of this key_hash.  The hash has keys for
+each of foreign/primary keys used in the association.  In this case, the artist
+association needs the artist_id foreign key (since it is a many_to_one), and the
+tracks association needs the id primary key (since it is a one_to_many).
+
+If you only eagerly loaded the artist association:
+
+  Album.eager(:artist).all
+
+Then the key_hash would only contain artist_id information:
+
+  {:artist_id=>{3=>[album1, album2]}}
+ 
+Likewise, if you only eagerly loaded the tracks association:
+
+  Album.eager(:tracks).all
+
+Then the key_hash would only contain id information:
+
+  {:id=>{1=>[album1], 2=>[album2]}}
+
+Now, the eager loader for the artist association is only going to care about the
+value of the artist_id key in the hash, so it's going to do the equivalent of:
+
+  artist_id_map = key_hash[:artist_id] # {3=>[album1, album2]}
+
+The artist_id_map contains a mapping of artist_id values to arrays of
+album objects.  Since it only has a single entry with a key of 3, when eagerly
+loading the artists, you only need to look for artists that have an id of 3.
+
+  artists = Artist.where(:id=>artist_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 = artist_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
+
+Similarly, the eager loader for the tracks association is only going to care about the
+value of the id key in the hash:
 
-Using these options, you can build associations that Sequel doesn't natively support,
-and still be able to use the same eager loading features that you are used to.
+  id_map = key_hash[:id] # {1=>[album1], 2=>[album2]}
+
+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 of 1 or 2:
+
+  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:
+
+  :eager_loader=>(proc do |eo_opts|
+    eo_opts[:rows].each{|album| album.associations[:artist] = nil}
+    artist_id_map = eo_opts[:key_hash][:artist_id]
+    Artist.where(:id=>artist_id_map.keys).all do |artist|
+      if albums = artist_id_map[artist.id]
+        albums.each do |album|
+          album.associations[:artist] = artist
+        end
+      end
+    end
+  end)
+
+and the tracks eager loader looks like:
+
+  :eager_loader=>(proc do |eo_opts|
+    eo_opts[:rows].each{|album| album.associations[:tracks] = []}
+    id_map = eo_opts[:key_hash][:id]
+    Track.where(:id=>id_map.keys).all do |tracks|
+      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. Build a custom key map mapping foreign/primary key values to arrays of
+   current objects (using the key_hash)
+3. Return just related associated objects by filtering the associated class
+   to include only matching values
+4. Iterating over the returned associated objects, indexing into the custom key
+   map using the foreign/primary key value in the associated object to get
+   current values associated to that specific object.
+5. 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.
 
 == ActiveRecord associations
 
@@ -237,6 +380,23 @@ Sequel::Model:
 
   class Invoice < Sequel::Model
     many_to_one :client
+
+    # has_one :through equivalent 1
+    # eager load with :eager=>:firm option on :client association, and eager loading :client
+    def firm
+      client.firm if client
+    end
+
+    # has_one :through equivalent 2
+    # eager load the usual way
+    many_to_many :firms, :join_table=>:clients, :left_key=>:id, :left_primary_key=>:client_id, :right_key=>:firm_id
+    def firm
+      firms.first
+    end
+
+    # has_one :through equivalent 3
+    # eager loading requires custom :eager_loader proc
+    many_to_one :firm, :dataset=>proc{Firm.join(:clients, :firm_id=>:id, :id=>client_id).select_all(:firms)}
   end
 
   Firm.first.invoices