sequel 5.12.0 → 5.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d316ca35fb36d4b3777021b4e3d6c108036f0bb1197ab7c9efc4529012858d1
-  data.tar.gz: 7f0e338f35027945f84cfeb9d6d997114e098f46d74b7b2fc3e32db34c4f5925
+  metadata.gz: bc4068290931cd51d12ec42e40a1e383ffa9cc8448501970230ec0863fc1cc21
+  data.tar.gz: 16c549d0adcd8700bfb498bc2a459437a37c57a85d9048099336105efff376ad
 SHA512:
-  metadata.gz: 8d5f3c64cf5e6361ced90c90c0cfd8e3f35cfb50e2e5acfd7b25b79728dbf207bf673e03662ab72e9208cd283675e278f126d27d656a7e2f7ec0baec7330a0b4
-  data.tar.gz: c741e9fd139c5e8b13c0c434f66836bbecba900f03eecddf559f1992d4155bfcb2af1e846425d9f495fc442f09e79c82e1933dc3a362f81caced379ef608e248
+  metadata.gz: 3f6acb6af9670774bf87b19349e778cb7b967ac529bbd192ea3ce2b6790080c21afa4445faabe18de148cfcef894e5457924782fb5462289dc38ff9af4ab5fcb
+  data.tar.gz: e03cf594244024d41de805ef57bcdc545bd9bb247e34fcd48e1d6fba8c558f8dacc49828b5f529e465b9a5a6089e66adc5e1a8d43cf7029225556429aa97441b

data/CHANGELOG

@@ -1,3 +1,13 @@
+=== 5.13.0 (2018-10-01)
+
+* Support :single_value type in prepared statements (rintaun) (#1547)
+
+* Make Model.all in static_cache plugin accept a block (AlexWayfer, jeremyevans) (#1543)
+
+* Add constant_sql_override extension for overriding SQL used for constants such as CURRENT_TIMESTAMP (celsworth) (#1538)
+
+* Do not cache from_self datasets if options are given (jeremyevans)
+
 === 5.12.0 (2018-08-31)
 
 * Make constraint_validations extension respect Database#constraint_validations_table setting (jeremyevans)

data/README.rdoc

@@ -9,7 +9,7 @@ toolkit for Ruby.
   records to Ruby objects and handling associated records.
 * Sequel supports advanced database features such as prepared
   statements, bound variables, savepoints, two-phase commit,
-  transaction isolation, master/slave configurations, and
+  transaction isolation, primary/replica configurations, and
   database sharding.
 * Sequel currently has adapters for ADO, Amalgalite, 
   IBM_DB, JDBC, MySQL, Mysql2, ODBC, Oracle,

data/doc/mass_assignment.rdoc

@@ -15,13 +15,13 @@ and you call a mass assignment method with a hash:
 
 the mass assignment method will go through each key in the hash, append <tt>=</tt> to it to determine the
 setter method, and if the setter method is defined and access to it is not restricted, Sequel will call the
-setter method with the hash value.  So if we assume that the posts table has subject and text columns, what
+setter method with the hash value.  So if we assume that the posts table has title and body columns, what
 the above mass assignment call actually does is:
- 
+
   post.title=('T')
   post.body=('B')
 
-By default, there are two types of setter methods that are restricted.  
+By default, there are two types of setter methods that are restricted.
 The first is methods like <tt>typecast_on_assignment=</tt> and <tt>==</tt>, which don't affect columns.
 These methods cannot be enabled for mass assignment.
 The second is primary key setters.

data/doc/opening_databases.rdoc

@@ -83,7 +83,7 @@ These options are shared by all adapters unless otherwise noted.
 :log_connection_info :: Whether to include connection information in log messages (false by default)
 :log_warn_duration :: The amount of seconds after which the queries are logged at :warn level
 :password :: The password for the user account
-:servers :: A hash with symbol keys and hash or proc values, used with master/slave/partitioned database configurations
+:servers :: A hash with symbol keys and hash or proc values, used with primary/replica and sharded database configurations
 :sql_log_level :: The level at which to issue queries to the loggers (:info by default)
 :test :: Whether to test that a valid database connection can be made (true by default)
 :user :: The user account name to use logging in

data/doc/release_notes/5.13.0.txt

@@ -0,0 +1,27 @@
+= New Features
+
+* A constant_sql_override Database extension has been added, allowing
+  for overriding the SQL used by constants such as
+  Sequel::CURRENT_TIMESTAMP.  This can be used to force
+  CURRENT_TIMESTAMP to be literalized at a particular time zone:
+
+    DB.extension :constant_sql_override
+    DB.set_constant_sql(Sequel::CURRENT_TIMESTAMP,
+      "CURRENT_TIMESTAMP AT TIME ZONE 'UTC'")
+
+* Prepared statements now support the :single_value type, which
+  returns the first column value in the dataset.
+
+    prep_stmt = DB[:table].select(:column).prepare(:single_value, :ps)
+    prep_stmt.call
+    # PREPARE ps AS SELECT column FROM table LIMIT 1;
+    # EXECUTE ps;
+    # => 42
+
+= Other Improvements
+
+* Dataset#from_self will no longer use a cached dataset if any options
+  are given, as that can result in incorrect behavior.
+
+* Model.all in the static_cache plugin now accepts a block, mirroring
+  the API when the static_cache plugin is not used.

data/doc/sharding.rdoc

@@ -1,7 +1,7 @@
-= Read-Only Slaves/Writable Master and Database Sharding
+= Primary/Replica Configurations and Database Sharding
 
-Sequel has support for read only slave databases
-with a writable master database, as well as database sharding (where you can
+Sequel has support for primary/replica configurations (writable primary
+database with read only replicas databases), as well as database sharding (where you can
 pick a server to use for a given dataset).  Support for both
 features is database independent, and should work for all database adapters
 that ship with Sequel.
@@ -13,7 +13,7 @@ option.  Using the :servers database option makes Sequel use a connection pool
 class that supports sharding, and the minimum required to enable sharding
 support is to use the empty hash:
 
-  DB=Sequel.connect('postgres://master_server/database', servers: {})
+  DB=Sequel.connect('postgres://primary_server/database', servers: {})
 
 In most cases, you are probably not going to want to use an empty hash.  Keys in the server hash are
 not restricted to type, but the general recommendation is to use a symbol
@@ -28,69 +28,69 @@ a :host entry in each shard's hash.
 Note that all servers should have the same schema for all
 tables you are accessing, unless you really know what you are doing.
 
-== Master and Slave Database Configurations
+== Primary and Replica Database Configurations
 
-=== Single Read-Only Slave, Single Master
+=== Single Primary, Single Replica
 
-To use a single, read-only slave that handles SELECT queries, the following
+To use a single, read-only replica that handles SELECT queries, the following
 is the simplest configuration:
 
-  DB=Sequel.connect('postgres://master_server/database', 
-    servers: {read_only: {host: 'slave_server'}})
+  DB=Sequel.connect('postgres://primary_server/database', 
+    servers: {read_only: {host: 'replica_server'}})
 
-This will use the slave_server for SELECT queries and master_server for
+This will use the replica_server for SELECT queries and primary_server for
 other queries.
 
 If you want to ensure your queries are going to a specific database, you
 can force this for a given query by using the .server method and passing 
 the symbol name defined in the connect options. For example:
 
-  # Force the SELECT to run on the master
+  # Force the SELECT to run on the primary server
   DB[:users].server(:default).all
 
-  # Force the DELETE to run on the read-only slave
+  # Force the DELETE to run on the read-only replica
   DB[:users].server(:read_only).delete
 
-=== Multiple Read-Only Slaves, Single Master
+=== Single Primary, Multiple Replicas
 
-Let's say you have 4 slave database servers with names slave_server0,
-slave_server1, slave_server2, and slave_server3.
+Let's say you have 4 replica servers with names replica_server0,
+replica_server1, replica_server2, and replica_server3.
 
   num_read_only = 4
   read_only_host = rand(num_read_only)
   read_only_proc = proc do |db|
-    {host: "slave_server#{(read_only_host+=1) % num_read_only}"}
+    {host: "replica_server#{(read_only_host+=1) % num_read_only}"}
   end
-  DB=Sequel.connect('postgres://master_server/database',
+  DB=Sequel.connect('postgres://primary_server/database',
     servers: {read_only: read_only_proc})
 
-This will use one of the slave servers for SELECT queries and use the
-master server for other queries.  It's also possible to pick a random host
+This will use one of the replica servers for SELECT queries and use the
+primary server for other queries.  It's also possible to pick a random host
 instead of using the round robin approach presented above, but that can result
 in less optimal resource usage.
 
-=== Multiple Read-Only Slaves, Multiple Masters
+=== Multiple Primary, Multiple Replicas
 
-This involves the same basic idea as the multiple slaves, single master, but
-it shows that the master database is named :default.  So for 4 masters and
-4 slaves:
+This involves the same basic idea as the multiple replicas, single primary, but
+it shows that the primary database is named :default.  So for 4 primary servers and
+4 replica servers:
 
   num_read_only = 4
   read_only_host = rand(num_read_only)
   read_only_proc = proc do |db|
-    {host: "slave_server#{(read_only_host+=1) % num_read_only}"}
+    {host: "replica_server#{(read_only_host+=1) % num_read_only}"}
   end
   num_default = 4
   default_host = rand(num_default)
   default_proc = proc do |db|
-    {host: "master_server#{(default_host+=1) % num_default}"}
+    {host: "primary_server#{(default_host+=1) % num_default}"}
   end
-  DB=Sequel.connect('postgres://master_server/database',
+  DB=Sequel.connect('postgres://primary_server/database',
     servers: {default: default_proc, read_only: read_only_proc})
   
 == Sharding
 
-There is specific support in Sequel for handling master/slave database
+There is specific support in Sequel for handling primary/replica database
 combinations, with the only necessary setup being the database configuration.
 However, since sharding is always going to be implementation dependent, Sequel
 supplies the basic infrastructure, but you have to tell it which server to use
@@ -210,7 +210,7 @@ need to do that, call the server method explicitly on the dataset used to retrie
 model objects.
 
 The with_server method also supports a second argument for the default read_only server
-to use, which can be useful if you are mixing sharding and master/slave servers:
+to use, which can be useful if you are mixing sharding and primary/replica servers:
 
   DB.extension :server_block
   DB.with_server(:a, :a_read_only) do

data/lib/sequel/adapters/ado.rb

@@ -253,8 +253,8 @@ module Sequel
           recordset.GetRows.transpose.each do |field_values|
             h = {}
 
-            cols.each do |name, cp, i|
-              h[name] = if (v = field_values[i]) && cp
+            cols.each do |name, cp, index|
+              h[name] = if (v = field_values[index]) && cp
                 cp[v]
               else
                 v

data/lib/sequel/connection_pool/sharded_single.rb

@@ -19,9 +19,9 @@ class Sequel::ShardedSingleConnectionPool < Sequel::ConnectionPool
     add_servers(opts[:servers].keys) if opts[:servers]
   end
   
-  # Adds new servers to the connection pool. Primarily used in conjunction with master/slave
-  # or shard configurations. Allows for dynamic expansion of the potential slaves/shards
-  # at runtime. servers argument should be an array of symbols. 
+  # Adds new servers to the connection pool. Primarily used in conjunction with primary/replica
+  # or sharded configurations. Allows for dynamic expansion of the potential replicas/shards
+  # at runtime. +servers+ argument should be an array of symbols. 
   def add_servers(servers)
     servers.each{|s| @servers[s] = s}
   end

data/lib/sequel/connection_pool/sharded_threaded.rb

@@ -28,8 +28,8 @@ class Sequel::ShardedThreadedConnectionPool < Sequel::ThreadedConnectionPool
     add_servers(opts[:servers].keys) if opts[:servers]
   end
   
-  # Adds new servers to the connection pool.  Allows for dynamic expansion of the potential slaves/shards
-  # at runtime. servers argument should be an array of symbols. 
+  # Adds new servers to the connection pool.  Allows for dynamic expansion of the potential replicas/shards
+  # at runtime. +servers+ argument should be an array of symbols. 
   def add_servers(servers)
     sync do
       servers.each do |server|

data/lib/sequel/core.rb

@@ -116,7 +116,7 @@ module Sequel
   # terminates, or use the <tt>keep_reference: false</tt> Database option.
   #
   # For details, see the {"Connecting to a Database" guide}[rdoc-ref:doc/opening_databases.rdoc].
-  # To set up a master/slave or sharded database connection, see the {"Master/Slave Databases and Sharding" guide}[rdoc-ref:doc/sharding.rdoc].
+  # To set up a primary/replica or sharded database connection, see the {"Primary/Replica Database Configurations and Sharding" guide}[rdoc-ref:doc/sharding.rdoc].
   def self.connect(*args, &block)
     Database.connect(*args, &block)
   end

data/lib/sequel/database/misc.rb

@@ -281,7 +281,7 @@ module Sequel
     end
 
     # Whether this database instance uses multiple servers, either for sharding
-    # or for master/slave.
+    # or for primary/replica configurations.
     def sharded?
       @sharded
     end

data/lib/sequel/database/schema_generator.rb

@@ -81,7 +81,8 @@ module Sequel
         constraint(nil, *args, &block)
       end
 
-      # Add a column with the given name, type, and opts      #
+      # Add a column with the given name, type, and opts:
+      #
       #   column :num, :integer
       #   # num INTEGER
       #
@@ -158,7 +159,7 @@ module Sequel
         nil
       end
       
-      # Add a foreign key in the table that references another table. See column
+      # Add a foreign key in the table that references another table. See #column
       # for available options.
       #
       #   foreign_key(:artist_id) # artist_id INTEGER
@@ -241,7 +242,7 @@ module Sequel
         nil
       end
       
-      # Add a column with the given type, name, and opts.  See +column+ for available
+      # Add a column with the given type, name, and opts.  See #column for available
       # options.
       def method_missing(type, name = nil, opts = OPTS)
         name ? column(name, type, opts) : super

data/lib/sequel/dataset/prepared_statements.rb

@@ -91,7 +91,7 @@ module Sequel
       end
       
       # The type of prepared statement, should be one of :select, :first,
-      # :insert, :update, or :delete
+      # :insert, :update, :delete, or :single_value
       def prepared_type
         @opts[:prepared_type]
       end
@@ -144,7 +144,7 @@ module Sequel
         when :select, :all, :each
           # Most common scenario, so listed first.
           select_sql
-        when :first
+        when :first, :single_value
           clone(:limit=>1).select_sql
         when :insert_select
           insert_select_sql(*prepared_modify_values)
@@ -205,6 +205,8 @@ module Sequel
           when :map, :as_hash, :to_hash, :to_hash_groups
             public_send(*prepared_type, &block) 
           end
+        when :single_value
+          single_value
         else
           raise Error, "unsupported prepared statement type used: #{prepared_type.inspect}"
         end
@@ -290,7 +292,7 @@ module Sequel
           ds = ds.clone(:recorder=>pl)
 
           case type
-          when :first
+          when :first, :single_value
             ds.limit(1)
           when :update, :insert, :insert_select, :delete
             ds.with_sql(:"#{type}_sql", *values)
@@ -339,7 +341,7 @@ module Sequel
       clone(:bind_vars=>bind_vars)
     end
     
-    # For the given type (:select, :first, :insert, :insert_select, :update, or :delete),
+    # For the given type (:select, :first, :insert, :insert_select, :update, :delete, or :single_value),
     # run the sql with the bind variables specified in the hash.  +values+ is a hash passed to
     # insert or update (if one of those types is used), which may contain placeholders.
     #

data/lib/sequel/dataset/query.rb

@@ -291,7 +291,7 @@ module Sequel
         c
       end
 
-      cache ? cached_dataset(:_from_self_ds, &pr) : pr.call
+      opts.empty? ? cached_dataset(:_from_self_ds, &pr) : pr.call
     end
 
     # Match any of the columns to any of the patterns. The terms can be

data/lib/sequel/extensions/constant_sql_override.rb

@@ -0,0 +1,65 @@
+# frozen-string-literal: true
+#
+# The constant_sql_override extension allows you to change the SQL
+# generated for Sequel constants.
+#
+# One possible use-case for this is to have Sequel::CURRENT_TIMESTAMP use UTC time when
+# you have Sequel.database_timezone = :utc, but the database uses localtime when
+# generating CURRENT_TIMESTAMP.
+#
+# You can set SQL overrides with Database#set_constant_sql:
+#
+#   DB.set_constant_sql(Sequel::CURRENT_TIMESTAMP, "CURRENT_TIMESTAMP AT TIME ZONE 'UTC'")
+#
+# Now, using Sequel::CURRENT_TIMESTAMP will use your override instead:
+#
+#   Album.where(released_at: Sequel::CURRENT_TIMESTAMP).sql
+#   # => SELECT "albums.*" FROM "albums" WHERE ("released_at" = CURRENT_TIMESTAMP AT TIME ZONE 'UTC')
+#
+# To use this extension, first load it into your Sequel::Database instance:
+#
+#   DB.extension :constant_sql_override
+#
+# Related module: Sequel::ConstantSqlOverride
+
+#
+module Sequel
+  module ConstantSqlOverride
+    module DatabaseMethods
+      # Create the initial empty hash of constant sql overrides.
+      def self.extended(db)
+        db.instance_exec do
+          @constant_sqls ||= {}
+          extend_datasets(DatasetMethods)
+        end
+      end
+
+      # Hash mapping constant symbols to SQL.  For internal use only.
+      attr_reader :constant_sqls # :nodoc:
+
+      # Set the SQL to use for the given Sequel::SQL::Constant
+      def set_constant_sql(constant, override)
+        @constant_sqls[constant.constant] = override
+      end
+
+      # Freeze the constant_sqls hash to prevent adding new overrides.
+      def freeze
+        @constant_sqls.freeze
+        super
+      end
+    end
+
+    module DatasetMethods
+      # Use overridden constant SQL
+      def constant_sql_append(sql, constant)
+        if constant_sql = db.constant_sqls[constant]
+          sql << constant_sql
+        else
+          super
+        end
+      end
+    end
+  end
+
+  Database.register_extension(:constant_sql_override, ConstantSqlOverride::DatabaseMethods)
+end

data/lib/sequel/model/associations.rb

@@ -2641,7 +2641,7 @@ module Sequel
       #   Album.eager(:artist, :genre).all
       #   Album.eager_graph(:artist, :genre).all
       #   Album.eager(:artist).eager(:genre).all
-      #   Album.eager_graph(:artist).eager(:genre).all
+      #   Album.eager_graph(:artist).eager_graph(:genre).all
       #   Artist.eager(albums: :tracks).all
       #   Artist.eager_graph(albums: :tracks).all
       #   Artist.eager(albums: {tracks: :genre}).all
@@ -2674,13 +2674,79 @@ module Sequel
         end
 
         # Adds one or more INNER JOINs to the existing dataset using the keys and conditions
-        # specified by the given association.  The following methods also exist for specifying
-        # a different type of JOIN:
+        # specified by the given association(s).  Take the same arguments as eager_graph, and
+        # operates similarly, but only adds the joins as opposed to making the other changes
+        # (such as adding selected columns and setting up eager loading).
+        #
+        # The following methods also exist for specifying a different type of JOIN:
         #
         # association_full_join :: FULL JOIN
         # association_inner_join :: INNER JOIN
         # association_left_join :: LEFT JOIN
         # association_right_join :: RIGHT JOIN
+        #
+        # Examples:
+        #
+        #   # For each album, association_join load the artist
+        #   Album.association_join(:artist).all
+        #   # SELECT *
+        #   # FROM albums
+        #   # INNER JOIN artists AS artist ON (artists.id = albums.artist_id)
+        #
+        #   # For each album, association_join load the artist, using a specified alias
+        #   Album.association_join(Sequel[:artist].as(:a)).all
+        #   # SELECT *
+        #   # FROM albums
+        #   # INNER JOIN artists AS a ON (a.id = albums.artist_id)
+        #
+        #   # For each album, association_join load the artist and genre
+        #   Album.association_join(:artist, :genre).all
+        #   Album.association_join(:artist).association_join(:genre).all
+        #   # SELECT *
+        #   # FROM albums
+        #   # INNER JOIN artists AS artist ON (artist.id = albums.artist_id)
+        #   # INNER JOIN genres AS genre ON (genre.id = albums.genre_id)
+        #
+        #   # For each artist, association_join load albums and tracks for each album
+        #   Artist.association_join(albums: :tracks).all
+        #   # SELECT *
+        #   # FROM artists 
+        #   # INNER JOIN albums ON (albums.artist_id = artists.id)
+        #   # INNER JOIN tracks ON (tracks.album_id = albums.id)
+        #
+        #   # For each artist, association_join load albums, tracks for each album, and genre for each track
+        #   Artist.association_join(albums: {tracks: :genre}).all
+        #   # SELECT *
+        #   # FROM artists 
+        #   # INNER JOIN albums ON (albums.artist_id = artists.id)
+        #   # INNER JOIN tracks ON (tracks.album_id = albums.id)
+        #   # INNER JOIN genres AS genre ON (genre.id = tracks.genre_id)
+        #
+        #   # For each artist, association_join load albums with year > 1990
+        #   Artist.association_join(albums: proc{|ds| ds.where{year > 1990}}).all
+        #   # SELECT *
+        #   # FROM artists 
+        #   # INNER JOIN (
+        #   #   SELECT * FROM albums WHERE (year > 1990)
+        #   # ) AS albums ON (albums.artist_id = artists.id)
+        #
+        #   # For each artist, association_join load albums and tracks 1-10 for each album
+        #   Artist.association_join(albums: {tracks: proc{|ds| ds.where(number: 1..10)}}).all
+        #   # SELECT *
+        #   # FROM artists 
+        #   # INNER JOIN albums ON (albums.artist_id = artists.id)
+        #   # INNER JOIN (
+        #   #   SELECT * FROM tracks WHERE ((number >= 1) AND (number <= 10))
+        #   # ) AS tracks ON (tracks.albums_id = albums.id)
+        #
+        #   # For each artist, association_join load albums with year > 1990, and tracks for those albums
+        #   Artist.association_join(albums: {proc{|ds| ds.where{year > 1990}}=>:tracks}).all
+        #   # SELECT *
+        #   # FROM artists 
+        #   # INNER JOIN (
+        #   #   SELECT * FROM albums WHERE (year > 1990)
+        #   # ) AS albums ON (albums.artist_id = artists.id)
+        #   # INNER JOIN tracks ON (tracks.album_id = albums.id)
         def association_join(*associations)
           association_inner_join(*associations)
         end
@@ -2760,6 +2826,56 @@ module Sequel
         #
         # Each association's order, if defined, is respected.
         # If the association uses a block or has an :eager_block argument, it is used.
+        #
+        # To modify the associated dataset that will be used for the eager load, you should use a
+        # hash for the association, with the key being the association name symbol, and the value being
+        # a callable object that is called with the associated dataset and should return a modified
+        # dataset.  If that association also has dependent associations, instead of a callable object,
+        # use a hash with the callable object being the key, and the dependent association(s) as the value.
+        #
+        # Examples:
+        #
+        #   # For each album, eager load the artist
+        #   Album.eager(:artist).all
+        #   # SELECT * FROM albums
+        #   # SELECT * FROM artists WHERE (id IN (...))
+        #
+        #   # For each album, eager load the artist and genre
+        #   Album.eager(:artist, :genre).all
+        #   Album.eager(:artist).eager(:genre).all
+        #   # SELECT * FROM albums
+        #   # SELECT * FROM artists WHERE (id IN (...))
+        #   # SELECT * FROM genres WHERE (id IN (...))
+        #
+        #   # For each artist, eager load albums and tracks for each album
+        #   Artist.eager(albums: :tracks).all
+        #   # SELECT * FROM artists
+        #   # SELECT * FROM albums WHERE (artist_id IN (...))
+        #   # SELECT * FROM tracks WHERE (album_id IN (...))
+        #
+        #   # For each artist, eager load albums, tracks for each album, and genre for each track
+        #   Artist.eager(albums: {tracks: :genre}).all
+        #   # SELECT * FROM artists
+        #   # SELECT * FROM albums WHERE (artist_id IN (...))
+        #   # SELECT * FROM tracks WHERE (album_id IN (...))
+        #   # SELECT * FROM genre WHERE (id IN (...))
+        #
+        #   # For each artist, eager load albums with year > 1990
+        #   Artist.eager(albums: proc{|ds| ds.where{year > 1990}}).all
+        #   # SELECT * FROM artists
+        #   # SELECT * FROM albums WHERE ((year > 1990) AND (artist_id IN (...)))
+        #
+        #   # For each artist, eager load albums and tracks 1-10 for each album
+        #   Artist.eager(albums: {tracks: proc{|ds| ds.where(number: 1..10)}}).all
+        #   # SELECT * FROM artists
+        #   # SELECT * FROM albums WHERE (artist_id IN (...))
+        #   # SELECT * FROM tracks WHERE ((number >= 1) AND (number <= 10) AND (album_id IN (...)))
+        #
+        #   # For each artist, eager load albums with year > 1990, and tracks for those albums
+        #   Artist.eager(albums: {proc{|ds| ds.where{year > 1990}}=>:tracks}).all
+        #   # SELECT * FROM artists
+        #   # SELECT * FROM albums WHERE ((year > 1990) AND (artist_id IN (...)))
+        #   # SELECT * FROM albums WHERE (artist_id IN (...))
         def eager(*associations)
           opts = @opts[:eager]
           association_opts = eager_options_for_associations(associations)
@@ -2788,6 +2904,78 @@ module Sequel
         #
         # Like +eager+, you need to call +all+ on the dataset for the eager loading to work.  If you just
         # call +each+, it will yield plain hashes, each containing all columns from all the tables.
+        #
+        # To modify the associated dataset that will be joined to the current dataset, you should use a
+        # hash for the association, with the key being the association name symbol, and the value being
+        # a callable object that is called with the associated dataset and should return a modified
+        # dataset.  If that association also has dependent associations, instead of a callable object,
+        # use a hash with the callable object being the key, and the dependent association(s) as the value.
+        # 
+        # You can specify an alias by providing a Sequel::SQL::AliasedExpression object instead of
+        # an a Symbol for the assocation name.
+        #
+        # Examples:
+        #
+        #   # For each album, eager_graph load the artist
+        #   Album.eager_graph(:artist).all
+        #   # SELECT ...
+        #   # FROM albums
+        #   # LEFT OUTER JOIN artists AS artist ON (artists.id = albums.artist_id)
+        #
+        #   # For each album, eager_graph load the artist, using a specified alias
+        #   Album.eager_graph(Sequel[:artist].as(:a)).all
+        #   # SELECT ...
+        #   # FROM albums
+        #   # LEFT OUTER JOIN artists AS a ON (a.id = albums.artist_id)
+        #
+        #   # For each album, eager_graph load the artist and genre
+        #   Album.eager_graph(:artist, :genre).all
+        #   Album.eager_graph(:artist).eager_graph(:genre).all
+        #   # SELECT ...
+        #   # FROM albums
+        #   # LEFT OUTER JOIN artists AS artist ON (artist.id = albums.artist_id)
+        #   # LEFT OUTER JOIN genres AS genre ON (genre.id = albums.genre_id)
+        #
+        #   # For each artist, eager_graph load albums and tracks for each album
+        #   Artist.eager_graph(albums: :tracks).all
+        #   # SELECT ...
+        #   # FROM artists 
+        #   # LEFT OUTER JOIN albums ON (albums.artist_id = artists.id)
+        #   # LEFT OUTER JOIN tracks ON (tracks.album_id = albums.id)
+        #
+        #   # For each artist, eager_graph load albums, tracks for each album, and genre for each track
+        #   Artist.eager_graph(albums: {tracks: :genre}).all
+        #   # SELECT ...
+        #   # FROM artists 
+        #   # LEFT OUTER JOIN albums ON (albums.artist_id = artists.id)
+        #   # LEFT OUTER JOIN tracks ON (tracks.album_id = albums.id)
+        #   # LEFT OUTER JOIN genres AS genre ON (genre.id = tracks.genre_id)
+        #
+        #   # For each artist, eager_graph load albums with year > 1990
+        #   Artist.eager_graph(albums: proc{|ds| ds.where{year > 1990}}).all
+        #   # SELECT ...
+        #   # FROM artists 
+        #   # LEFT OUTER JOIN (
+        #   #   SELECT * FROM albums WHERE (year > 1990)
+        #   # ) AS albums ON (albums.artist_id = artists.id)
+        #
+        #   # For each artist, eager_graph load albums and tracks 1-10 for each album
+        #   Artist.eager_graph(albums: {tracks: proc{|ds| ds.where(number: 1..10)}}).all
+        #   # SELECT ...
+        #   # FROM artists 
+        #   # LEFT OUTER JOIN albums ON (albums.artist_id = artists.id)
+        #   # LEFT OUTER JOIN (
+        #   #   SELECT * FROM tracks WHERE ((number >= 1) AND (number <= 10))
+        #   # ) AS tracks ON (tracks.albums_id = albums.id)
+        #
+        #   # For each artist, eager_graph load albums with year > 1990, and tracks for those albums
+        #   Artist.eager_graph(albums: {proc{|ds| ds.where{year > 1990}}=>:tracks}).all
+        #   # SELECT ...
+        #   # FROM artists 
+        #   # LEFT OUTER JOIN (
+        #   #   SELECT * FROM albums WHERE (year > 1990)
+        #   # ) AS albums ON (albums.artist_id = artists.id)
+        #   # LEFT OUTER JOIN tracks ON (tracks.album_id = albums.id)
         def eager_graph(*associations)
           eager_graph_with_options(associations)
         end
@@ -3207,7 +3395,6 @@ module Sequel
         # Hash with table alias symbol keys and [limit, offset] values
         attr_reader :limit_map
         
-        # Hash with table alias symbol keys and callable values used to create model instances
         # The table alias symbol for the primary model
         attr_reader :master
         

data/lib/sequel/model/base.rb

@@ -1287,11 +1287,11 @@ module Sequel
       #     a.update(:name=>'A')
       #   end
       #
-      #  a = Artist[2]
-      #  Artist.db.transaction do
-      #    a.lock!('FOR NO KEY UPDATE')
-      #    a.update(:name=>'B')
-      #  end
+      #   a = Artist[2]
+      #   Artist.db.transaction do
+      #     a.lock!('FOR NO KEY UPDATE')
+      #     a.update(:name=>'B')
+      #   end
       def lock!(style=:update)
         _refresh(this.lock_style(style)) unless new?
         self
@@ -1551,8 +1551,8 @@ module Sequel
         update_restricted(hash, :default)
       end
   
-      # Update the instances values by calling +set_fields+ with the arguments, then
-      # saves any changes to the record.  Returns self.
+      # Update the instance's values by calling set_fields with the arguments, then
+      # calls save_changes.
       #
       #   artist.update_fields({name: 'Jim'}, [:name])
       #   # UPDATE artists SET name = 'Jim' WHERE (id = 1)

data/lib/sequel/plugins/static_cache.rb

@@ -72,14 +72,12 @@ module Sequel
         # A frozen ruby hash holding all of the model's frozen instances, keyed by frozen primary key.
         attr_reader :cache
 
-        # An array of all of the model's frozen instances, without issuing a database
-        # query.
-        def all
-          if @static_cache_frozen
-            @all.dup
-          else
-            map{|o| o}
-          end
+        # An array of all of the model's instances, without issuing a database
+        # query. If a block is given, yields each instance to the block.
+        def all(&block)
+          array = @static_cache_frozen ? @all.dup : to_a
+          array.each(&block) if block
+          array
         end
 
         # If a block is given, multiple arguments are given, or a single

data/lib/sequel/plugins/tactical_eager_loading.rb

@@ -60,6 +60,9 @@ module Sequel
     #   # SELECT * FROM artists WHERE name > 'N' AND id IN (...)
     #   albums.first.artists(eager: lambda{|ds| ds.where(Sequel[:name] > 'N')})
     #
+    # Note that the :eager option only takes effect if the association
+    # has not already been loaded for the model.
+    #
     # The tactical_eager_loading plugin also allows transparent eager
     # loading when calling association methods on associated objects
     # eagerly loaded via Dataset#eager_graph.  This can reduce N queries
@@ -100,6 +103,12 @@ module Sequel
     # loaded by eager_graph will only take place if the associated classes
     # also use the tactical_eager_loading plugin.
     #
+    # When using this plugin, calling association methods on separate
+    # instances of the same result set is not thread-safe, because this
+    # plugin attempts to modify all instances of the same result set
+    # to eagerly set the associated objects, and having separate threads
+    # modify the same model instance is not thread-safe.
+    #
     # Usage:
     #
     #   # Make all model subclass instances use tactical eager loading (called before loading subclasses)

data/lib/sequel/version.rb

@@ -6,7 +6,7 @@ module Sequel
 
   # The minor version of Sequel.  Bumped for every non-patch level
   # release, generally around once a month.
-  MINOR = 12
+  MINOR = 13
 
   # The tiny version of Sequel.  Usually 0, only bumped for bugfix
   # releases that fix regressions from previous versions.

data/spec/core/dataset_spec.rb

@@ -2330,6 +2330,11 @@ describe "Dataset#from_self" do
     @ds.from_self(:alias=>:some_name, :column_aliases=>[:c1, :c2]).sql.must_equal 'SELECT * FROM (SELECT name FROM test LIMIT 1) AS some_name(c1, c2)'
   end
   
+  it "should use the user-specified alias" do
+    @ds.from_self(:alias=>:some_name).sql.must_equal 'SELECT * FROM (SELECT name FROM test LIMIT 1) AS some_name'
+    @ds.from_self(:alias=>:some_name1).sql.must_equal 'SELECT * FROM (SELECT name FROM test LIMIT 1) AS some_name1'
+  end
+  
   it "should use the user-specified alias for joins" do
     @ds.from_self(:alias=>:some_name).inner_join(:posts, :alias=>:name).sql.must_equal \
       'SELECT * FROM (SELECT name FROM test LIMIT 1) AS some_name INNER JOIN posts ON (posts.alias = some_name.name)'
@@ -3836,6 +3841,7 @@ describe "Dataset prepared statements and bound variables " do
     @ds.filter(:num=>:$n).call([:to_hash, :a, :b], :n=>1)
     @ds.filter(:num=>:$n).call([:to_hash_groups, :a, :b], :n=>1)
     @ds.filter(:num=>:$n).call(:first, :n=>1)
+    @ds.filter(:num=>:$n).call(:single_value, :n=>1)
     @ds.filter(:num=>:$n).call(:delete, :n=>1)
     @ds.filter(:num=>:$n).call(:update, {:n=>1, :n2=>2}, :num=>:$n2)
     @ds.call(:insert, {:n=>1}, :num=>:$n)
@@ -3849,6 +3855,7 @@ describe "Dataset prepared statements and bound variables " do
       'SELECT * FROM items WHERE (num = 1)',
       'SELECT * FROM items WHERE (num = 1)',
       'SELECT * FROM items WHERE (num = 1) LIMIT 1',
+      'SELECT * FROM items WHERE (num = 1) LIMIT 1',
       'DELETE FROM items WHERE (num = 1)',
       'UPDATE items SET num = 2 WHERE (num = 1)',
       'INSERT INTO items (num) VALUES (1)',
@@ -3865,13 +3872,14 @@ describe "Dataset prepared statements and bound variables " do
     pss << @ds.filter(:num=>:$n).prepare([:to_hash, :a, :b], :sh)
     pss << @ds.filter(:num=>:$n).prepare([:to_hash_groups, :a, :b], :shg)
     pss << @ds.filter(:num=>:$n).prepare(:first, :fn)
+    pss << @ds.filter(:num=>:$n).prepare(:single_value, :svn)
     pss << @ds.filter(:num=>:$n).prepare(:delete, :dn)
     pss << @ds.filter(:num=>:$n).prepare(:update, :un, :num=>:$n2)
     pss << @ds.prepare(:insert, :in, :num=>:$n)
     pss << @ds.prepare(:insert_pk, :inp, :num=>:$n)
     pss << @ds.prepare(:insert_select, :ins, :num=>:$n)
-    @db.prepared_statements.keys.sort_by{|k| k.to_s}.must_equal [:ah, :dn, :en, :fn, :in, :inp, :ins, :sh, :shg, :sm, :sn, :un]
-    [:en, :sn, :sm, :ah, :sh, :shg, :fn, :dn, :un, :in, :inp, :ins].each_with_index{|x, i| @db.prepared_statements[x].must_equal pss[i]}
+    @db.prepared_statements.keys.sort_by{|k| k.to_s}.must_equal [:ah, :dn, :en, :fn, :in, :inp, :ins, :sh, :shg, :sm, :sn, :svn, :un]
+    [:en, :sn, :sm, :ah, :sh, :shg, :fn, :svn, :dn, :un, :in, :inp, :ins].each_with_index{|x, i| @db.prepared_statements[x].must_equal pss[i]}
     @db.call(:en, :n=>1){}
     @db.call(:sn, :n=>1)
     @db.call(:sm, :n=>1)
@@ -3879,6 +3887,7 @@ describe "Dataset prepared statements and bound variables " do
     @db.call(:sh, :n=>1)
     @db.call(:shg, :n=>1)
     @db.call(:fn, :n=>1)
+    @db.call(:svn, :n=>1)
     @db.call(:dn, :n=>1)
     @db.call(:un, :n=>1, :n2=>2)
     @db.call(:in, :n=>1)
@@ -3892,6 +3901,7 @@ describe "Dataset prepared statements and bound variables " do
       'SELECT * FROM items WHERE (num = 1)',
       'SELECT * FROM items WHERE (num = 1)',
       'SELECT * FROM items WHERE (num = 1) LIMIT 1',
+      'SELECT * FROM items WHERE (num = 1) LIMIT 1',
       'DELETE FROM items WHERE (num = 1)',
       'UPDATE items SET num = 2 WHERE (num = 1)',
       'INSERT INTO items (num) VALUES (1)',
@@ -4032,6 +4042,7 @@ describe Sequel::Dataset::UnnumberedArgumentMapper do
     @ps << @ds.prepare(:select, :s)
     @ps << @ds.prepare(:all, :a)
     @ps << @ds.prepare(:first, :f)
+    @ps << @ds.prepare(:single_value, :sv)
     @ps << @ds.prepare(:delete, :d)
     @ps << @ds.prepare(:insert, :i, :num=>:$n)
     @ps << @ds.prepare(:update, :u, :num=>:$n)
@@ -4046,6 +4057,7 @@ describe Sequel::Dataset::UnnumberedArgumentMapper do
     @db.sqls.must_equal ["SELECT * FROM items WHERE (num = ?) -- args: [1]",
       "SELECT * FROM items WHERE (num = ?) -- args: [1]",
       "SELECT * FROM items WHERE (num = ?) LIMIT 1 -- args: [1]",
+      "SELECT * FROM items WHERE (num = ?) LIMIT 1 -- args: [1]",
       "DELETE FROM items WHERE (num = ?) -- args: [1]",
       "INSERT INTO items (num) VALUES (?) -- args: [1]",
       "UPDATE items SET num = ? WHERE (num = ?) -- args: [1, 1]"]

data/spec/extensions/constant_sql_override_spec.rb

@@ -0,0 +1,18 @@
+require_relative "spec_helper"
+
+describe "constant_sql_override extension" do
+  before do
+    @db = Sequel.mock.extension(:constant_sql_override)
+  end
+
+  it 'overrides configured constants' do
+    @db.set_constant_sql(Sequel::CURRENT_TIMESTAMP, "CURRENT TIMESTAMP AT TIME ZONE 'UTC'")
+    @db[:tbl].where(foo: Sequel::CURRENT_TIMESTAMP).first
+    @db.sqls.must_equal ["SELECT * FROM tbl WHERE (foo = CURRENT TIMESTAMP AT TIME ZONE 'UTC') LIMIT 1"]
+  end
+
+  it 'freezes the constant_sqls hash' do
+    @db.freeze
+    @db.constant_sqls.frozen?.must_equal true
+  end
+end

data/spec/extensions/static_cache_spec.rb

@@ -122,6 +122,10 @@ describe "Sequel::Plugins::StaticCache" do
       @c.map.frozen?.must_equal false
     end
 
+    it "should have map without a block return an Enumerator" do
+      @c.map.class.must_equal Enumerator
+    end
+
     it "should have map with a block and argument raise" do
       proc{@c.map(:id){}}.must_raise(Sequel::Error)
     end
@@ -148,6 +152,14 @@ describe "Sequel::Plugins::StaticCache" do
       @c.all.must_equal [@c1, @c2]
     end
 
+    it "should have all receiving block" do
+      a = []
+      b = @c.all { |o| a << o }
+      a.must_equal [@c1, @c2]
+      a.must_equal b
+      @db.sqls.must_equal []
+    end
+
     it "should have as_hash/to_hash without arguments run without a query" do
       a = @c.to_hash
       a.must_equal(1=>@c1, 2=>@c2)

data/spec/integration/prepared_statement_test.rb

@@ -21,6 +21,7 @@ describe "Prepared Statements and Bound Arguments" do
     @ds.filter(:numb=>:$n).call(:select, :n=>10).must_equal [{:id=>1, :numb=>10}]
     @ds.filter(:numb=>:$n).call(:all, :n=>10).must_equal [{:id=>1, :numb=>10}]
     @ds.filter(:numb=>:$n).call(:first, :n=>10).must_equal(:id=>1, :numb=>10)
+    @ds.select(:numb).filter(:numb=>:$n).call(:single_value, :n=>10).must_equal(10)
     @ds.filter(:numb=>:$n).call([:map, :numb], :n=>10).must_equal [10]
     @ds.filter(:numb=>:$n).call([:as_hash, :id, :numb], :n=>10).must_equal(1=>10)
     @ds.filter(:numb=>:$n).call([:to_hash, :id, :numb], :n=>10).must_equal(1=>10)
@@ -39,20 +40,24 @@ describe "Prepared Statements and Bound Arguments" do
     @ds.filter(:numb=>:$n).bind(:n=>10).call(:select).must_equal [{:id=>1, :numb=>10}]
     @ds.filter(:numb=>:$n).bind(:n=>10).call(:all).must_equal [{:id=>1, :numb=>10}]
     @ds.filter(:numb=>:$n).bind(:n=>10).call(:first).must_equal(:id=>1, :numb=>10)
+    @ds.select(:numb).filter(:numb=>:$n).bind(:n=>10).call(:single_value).must_equal(10)
     
     @ds.bind(:n=>10).filter(:numb=>:$n).call(:select).must_equal [{:id=>1, :numb=>10}]
     @ds.bind(:n=>10).filter(:numb=>:$n).call(:all).must_equal [{:id=>1, :numb=>10}]
     @ds.bind(:n=>10).filter(:numb=>:$n).call(:first).must_equal(:id=>1, :numb=>10)
+    @ds.bind(:n=>10).select(:numb).filter(:numb=>:$n).call(:single_value).must_equal(10)
   end
   
   it "should allow overriding variables specified with #bind" do
     @ds.filter(:numb=>:$n).bind(:n=>1).call(:select, :n=>10).must_equal [{:id=>1, :numb=>10}]
     @ds.filter(:numb=>:$n).bind(:n=>1).call(:all, :n=>10).must_equal [{:id=>1, :numb=>10}]
     @ds.filter(:numb=>:$n).bind(:n=>1).call(:first, :n=>10).must_equal(:id=>1, :numb=>10)
+    @ds.select(:numb).filter(:numb=>:$n).bind(:n=>1).call(:single_value, :n=>10).must_equal(10)
     
     @ds.filter(:numb=>:$n).bind(:n=>1).bind(:n=>10).call(:select).must_equal [{:id=>1, :numb=>10}]
     @ds.filter(:numb=>:$n).bind(:n=>1).bind(:n=>10).call(:all).must_equal [{:id=>1, :numb=>10}]
     @ds.filter(:numb=>:$n).bind(:n=>1).bind(:n=>10).call(:first).must_equal(:id=>1, :numb=>10)
+    @ds.select(:numb).filter(:numb=>:$n).bind(:n=>1).bind(:n=>10).call(:single_value).must_equal(10)
   end
 
   it "should support placeholder literal strings with call" do
@@ -160,6 +165,8 @@ describe "Prepared Statements and Bound Arguments" do
     @db.call(:select_n, :n=>10).must_equal [{:id=>1, :numb=>10}]
     @ds.filter(:numb=>:$n).prepare(:first, :select_n)
     @db.call(:select_n, :n=>10).must_equal(:id=>1, :numb=>10)
+    @ds.select(:numb).filter(:numb=>:$n).prepare(:single_value, :select_n)
+    @db.call(:select_n, :n=>10).must_equal(10)
     @ds.filter(:numb=>:$n).prepare([:map, :numb], :select_n)
     @db.call(:select_n, :n=>10).must_equal [10]
     @ds.filter(:numb=>:$n).prepare([:as_hash, :id, :numb], :select_n)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequel
 version: !ruby/object:Gem::Version
-  version: 5.12.0
+  version: 5.13.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-31 00:00:00.000000000 Z
+date: 2018-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -196,6 +196,7 @@ extra_rdoc_files:
 - doc/release_notes/5.10.0.txt
 - doc/release_notes/5.11.0.txt
 - doc/release_notes/5.12.0.txt
+- doc/release_notes/5.13.0.txt
 files:
 - CHANGELOG
 - MIT-LICENSE
@@ -278,6 +279,7 @@ files:
 - doc/release_notes/5.10.0.txt
 - doc/release_notes/5.11.0.txt
 - doc/release_notes/5.12.0.txt
+- doc/release_notes/5.13.0.txt
 - doc/release_notes/5.2.0.txt
 - doc/release_notes/5.3.0.txt
 - doc/release_notes/5.4.0.txt
@@ -384,6 +386,7 @@ files:
 - lib/sequel/extensions/columns_introspection.rb
 - lib/sequel/extensions/connection_expiration.rb
 - lib/sequel/extensions/connection_validator.rb
+- lib/sequel/extensions/constant_sql_override.rb
 - lib/sequel/extensions/constraint_validations.rb
 - lib/sequel/extensions/core_extensions.rb
 - lib/sequel/extensions/core_refinements.rb
@@ -590,6 +593,7 @@ files:
 - spec/extensions/composition_spec.rb
 - spec/extensions/connection_expiration_spec.rb
 - spec/extensions/connection_validator_spec.rb
+- spec/extensions/constant_sql_override_spec.rb
 - spec/extensions/constraint_validations_plugin_spec.rb
 - spec/extensions/constraint_validations_spec.rb
 - spec/extensions/core_refinements_spec.rb