sequel 4.13.0 → 4.14.0

data/doc/release_notes/4.13.0.txt

@@ -96,7 +96,7 @@
   returning the unqualified version of a possibly qualified column.
 
 * The composition and serialization plugins now support validations
-  on the underlying columns.  Previously, the didn't update the
+  on the underlying columns.  Previously, they didn't update the
   underlying columns until after validations were performed.  This
   works better when using the auto_validations plugin.
 

data/doc/release_notes/4.14.0.txt

@@ -0,0 +1,68 @@
+= New Features
+
+* Delayed evaluation blocks can now accept the dataset literalizing
+  the delayed evaluation as an argument.  This makes it so the
+  delayed evaluation result can depend on the dataset doing the
+  literalization:
+
+    ds = DB[:a].where(Sequel.delay do |ds|
+      {Sequel.qualify(ds.first_source, :col)=>1}
+    end)
+    ds.sql          # SELECT * FROM a WHERE (a.col = 1)
+    ds.from(:b).sql # SELECT * FROM b WHERE (b.col = 1)
+
+* Database#create_trigger on PostgreSQL now supports a :when option
+  to create a filter for the trigger, so that it is only triggered
+  when the filter condition is true.
+
+* You can now override the cache key prefix in the caching plugin
+  by overriding the cache_key_prefix class method.  This can be
+  useful when using a table inheritance plugin.
+
+= Other Improvements
+
+* You can now pass arbitrary types to Dataset#where and related
+  methods.  Previously, if a type was not explicitly handled, an
+  exception would be raised.  Now you can pass any object that can
+  be literalized.  The only exception is that you can't pass
+  Numeric objects, since #where and similar methods should
+  only deal with boolean expressions.
+
+* association_join and related methods now work correctly if the
+  dataset already has an explicit selection.
+
+* A regression has been fixed in the class_table_inheritance plugin
+  when using a hierarchy of more than 2 levels, when using the
+  superclass to load a subclass instance more than 2 levels below,
+  and later attempting to load a column contained in one of the
+  middle tables.
+ 
+* When using _delete or _remove keys in the nested_attributes plugin
+  to remove existing associated objects, the associated objects are
+  now deleted from the cached association array at time of call.
+  This is for consistency when adding new associated objects, where
+  the new associated objects are added to the cached association
+  array at time of call.
+
+* The nested_attributes plugin now handles composite primary keys
+  correctly when working around validation issues for one_to_one
+  and one_to_many associations.
+
+* If exception A is raised during a transaction, and exception B
+  is raised while attempting to rollback the transaction, the
+  transaction code will now raise exception A instead of exception B.
+
+* An additional serialization failure is now detected on PostgreSQL.
+
+* An additional disconnect error is now recognized in the jdbc/jtds
+  adapter.
+
+* The code examples in the RDoc are now syntax highlighted, and
+  many minor fixes to the code examples in the RDoc were made.
+  Additionally, many other improvements were made to the RDoc.
+
+= Backwards Compatibility
+
+* Dataset#delayed_evaluation_sql_append now accepts the delayed
+  evaluation as an argument, instead of the callable contained by the
+  delayed evaluation.

data/doc/schema_modification.rdoc

@@ -32,7 +32,7 @@ convert to database types:
     String :a3, :fixed=>true            # char(255)
     String :a4, :fixed=>true, :size=>50 # char(50)
     String :a5, :text=>true             # text
-    File :b,                            # blob
+    File :b                             # blob
     Fixnum :c                           # integer
     Bignum :d                           # bigint
     Float :e                            # double precision

data/doc/sharding.rdoc

@@ -134,12 +134,12 @@ to assume the :default shard.  However, you can specify a
 different shard using the :servers_hash option when connecting
 to the database:
 
-  DB = Sequel.connect(..., :servers_hash=>Hash.new(:some_shard))
+  DB = Sequel.connect('postgres://...', :servers_hash=>Hash.new(:some_shard))
 
 You can also use this feature to raise an exception if an
 unconfigured shard is used:
 
-  DB = Sequel.connect(..., :servers_hash=>Hash.new{raise ...})
+  DB = Sequel.connect('postgres://...', :servers_hash=>Hash.new{raise 'foo'})
 
 If you specify a :servers_hash option to raise an exception for non configured
 shards you should also explicitly specify a :read_only entry in your :servers option

data/doc/sql.rdoc

@@ -506,7 +506,7 @@ To select all columns in a table, Sequel supports the * method on identifiers wi
 
 Sequel allows the easy production of SQL CASE statements using the <tt>Sequel.case</tt> method.  The first argument is a hash or array of two element arrays representing the conditions, the second argument is the default value (ELSE).   The keys of the hash (or first element in each array) is the WHEN condition, and the values of the hash (or second element in each array) is the THEN result.  Here are some examples:
 
-  Sequel.case({:column=>1, 0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
+  Sequel.case({:column=>1}, 0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
   Sequel.case([[column, 1]], 0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
   Sequel.case({{:column=>nil}=>1}, 0) # (CASE WHEN (column IS NULL) THEN 1 ELSE 0 END)
 

data/doc/virtual_rows.rdoc

@@ -157,7 +157,7 @@ function without arguments, then call the * method on the function:
 To append the DISTINCT keyword before the method arguments, just call the
 distinct method on the returned Function:
 
-  ds.select{|o| o.count(o.col1).distinct)}
+  ds.select{|o| o.count(o.col1).distinct}
   ds.select{count(col1).distinct}
   # SELECT count(DISTINCT col1)
   
@@ -230,7 +230,7 @@ virtual row block to create a literal string:
 You can use this on a regular virtual row block too, but it
 doesn't look as nice:
 
-  ds.where{|o| o.>(:a, o.`('some SQL')}
+  ds.where{|o| o.>(:a, o.`('some SQL'))}
 
 == Returning multiple values
 

data/lib/sequel/adapters/jdbc/jtds.rb

@@ -26,6 +26,10 @@ module Sequel
           false
         end
 
+        def disconnect_error?(exception, opts)
+          super || exception.message =~ /\AInvalid state, the Connection object is closed\.\z/
+        end
+
         # Handle nil values by using setNull with the correct parameter type.
         def set_ps_arg_nil(cps, i)
           cps.setNull(i, cps.getParameterMetaData.getParameterType(i))

data/lib/sequel/adapters/mysql.rb

@@ -62,24 +62,24 @@ module Sequel
       # Connect to the database.  In addition to the usual database options,
       # the following options have effect:
       #
-      # * :auto_is_null - Set to true to use MySQL default behavior of having
-      #   a filter for an autoincrement column equals NULL to return the last
-      #   inserted row.
-      # * :charset - Same as :encoding (:encoding takes precendence)
-      # * :compress - Set to false to not compress results from the server
-      # * :config_default_group - The default group to read from the in
-      #   the MySQL config file.
-      # * :config_local_infile - If provided, sets the Mysql::OPT_LOCAL_INFILE
-      #   option on the connection with the given value.
-      # * :connect_timeout - Set the timeout in seconds before a connection
-      #   attempt is abandoned.
-      # * :encoding - Set all the related character sets for this
-      #   connection (connection, client, database, server, and results).
-      # * :read_timeout - Set the timeout in seconds for reading back results
-      #   to a query.
-      # * :socket - Use a unix socket file instead of connecting via TCP/IP.
-      # * :timeout - Set the timeout in seconds before the server will
-      #   disconnect this connection (a.k.a @@wait_timeout).
+      # :auto_is_null :: Set to true to use MySQL default behavior of having
+      #                  a filter for an autoincrement column equals NULL to return the last
+      #                  inserted row.
+      # :charset :: Same as :encoding (:encoding takes precendence)
+      # :compress :: Set to false to not compress results from the server
+      # :config_default_group :: The default group to read from the in
+      #                          the MySQL config file.
+      # :config_local_infile :: If provided, sets the Mysql::OPT_LOCAL_INFILE
+      #                         option on the connection with the given value.
+      # :connect_timeout :: Set the timeout in seconds before a connection
+      #                     attempt is abandoned.
+      # :encoding :: Set all the related character sets for this
+      #              connection (connection, client, database, server, and results).
+      # :read_timeout :: Set the timeout in seconds for reading back results
+      #                  to a query.
+      # :socket :: Use a unix socket file instead of connecting via TCP/IP.
+      # :timeout :: Set the timeout in seconds before the server will
+      #             disconnect this connection (a.k.a @@wait_timeout).
       def connect(server)
         opts = server_opts(server)
         conn = Mysql.init

data/lib/sequel/adapters/mysql2.rb

@@ -17,12 +17,12 @@ module Sequel
       # Connect to the database.  In addition to the usual database options,
       # the following options have effect:
       #
-      # * :auto_is_null - Set to true to use MySQL default behavior of having
-      #   a filter for an autoincrement column equals NULL to return the last
-      #   inserted row.
-      # * :charset - Same as :encoding (:encoding takes precendence)
-      # * :encoding - Set all the related character sets for this
-      #   connection (connection, client, database, server, and results).
+      # :auto_is_null :: Set to true to use MySQL default behavior of having
+      #                  a filter for an autoincrement column equals NULL to return the last
+      #                  inserted row.
+      # :charset :: Same as :encoding (:encoding takes precendence)
+      # :encoding :: Set all the related character sets for this
+      #              connection (connection, client, database, server, and results).
       #
       # The options hash is also passed to mysql2, and can include mysql2
       # options such as :local_infile.
@@ -61,7 +61,7 @@ module Sequel
         execute(sql, opts){|c| return c.last_id}
       end
 
-      # Return the version of the MySQL server two which we are connecting.
+      # Return the version of the MySQL server to which we are connecting.
       def server_version(server=nil)
         @server_version ||= (synchronize(server){|conn| conn.server_info[:id]} || super)
       end

data/lib/sequel/adapters/shared/mysql.rb

@@ -161,7 +161,7 @@ module Sequel
       # Return an array of symbols specifying table names in the current database.
       #
       # Options:
-      # * :server - Set the server to use
+      # :server :: Set the server to use
       def tables(opts=OPTS)
         full_tables('BASE TABLE', opts)
       end
@@ -178,7 +178,7 @@ module Sequel
       # Return an array of symbols specifying view names in the current database.
       #
       # Options:
-      # * :server - Set the server to use
+      # :server :: Set the server to use
       def views(opts=OPTS)
         full_tables('VIEW', opts)
       end
@@ -363,8 +363,8 @@ module Sequel
         end
 
         # Split column constraints into table constraints in some cases:
-        # * foreign key - Always
-        # * unique, primary_key - Only if constraint has a name
+        # foreign key - Always
+        # unique, primary_key - Only if constraint has a name
         generator.columns.each do |c|
           if t = c.delete(:table)
             same_table = t == name
@@ -733,7 +733,9 @@ module Sequel
       # Sets up the insert methods to use ON DUPLICATE KEY UPDATE
       # If you pass no arguments, ALL fields will be
       # updated with the new values.  If you pass the fields you
-      # want then ONLY those field will be updated.
+      # want then ONLY those field will be updated. If you pass a
+      # hash you can customize the values (for example, to increment
+      # a numeric field).
       #
       # Useful if you have a unique key and want to update
       # inserting rows that violate the unique key restriction.
@@ -749,6 +751,14 @@ module Sequel
       #   )
       #   # INSERT INTO tablename (name, value) VALUES (a, 1), (b, 2)
       #   # ON DUPLICATE KEY UPDATE value=VALUES(value)
+      #
+      #   dataset.on_duplicate_key_update(
+      #     :value => Sequel.lit('value + VALUES(value)')
+      #   ).multi_insert(
+      #     [{:name => 'a', :value => 1}, {:name => 'b', :value => 2}]
+      #   )
+      #   # INSERT INTO tablename (name, value) VALUES (a, 1), (b, 2)
+      #   # ON DUPLICATE KEY UPDATE value=value + VALUES(value)
       def on_duplicate_key_update(*args)
         clone(:on_duplicate_key_update => args)
       end

data/lib/sequel/adapters/shared/postgres.rb

@@ -161,59 +161,60 @@ module Sequel
       end
 
       # Creates the function in the database.  Arguments:
-      # * name : name of the function to create
-      # * definition : string definition of the function, or object file for a dynamically loaded C function.
-      # * opts : options hash:
-      #   * :args : function arguments, can be either a symbol or string specifying a type or an array of 1-3 elements:
-      #     * element 1 : argument data type
-      #     * element 2 : argument name
-      #     * element 3 : argument mode (e.g. in, out, inout)
-      #   * :behavior : Should be IMMUTABLE, STABLE, or VOLATILE.  PostgreSQL assumes VOLATILE by default.
-      #   * :cost : The estimated cost of the function, used by the query planner.
-      #   * :language : The language the function uses.  SQL is the default.
-      #   * :link_symbol : For a dynamically loaded see function, the function's link symbol if different from the definition argument.
-      #   * :returns : The data type returned by the function.  If you are using OUT or INOUT argument modes, this is ignored.
-      #     Otherwise, if this is not specified, void is used by default to specify the function is not supposed to return a value.
-      #   * :rows : The estimated number of rows the function will return.  Only use if the function returns SETOF something.
-      #   * :security_definer : Makes the privileges of the function the same as the privileges of the user who defined the function instead of
-      #     the privileges of the user who runs the function.  There are security implications when doing this, see the PostgreSQL documentation.
-      #   * :set : Configuration variables to set while the function is being run, can be a hash or an array of two pairs.  search_path is
-      #     often used here if :security_definer is used.
-      #   * :strict : Makes the function return NULL when any argument is NULL.
+      # name :: name of the function to create
+      # definition :: string definition of the function, or object file for a dynamically loaded C function.
+      # opts :: options hash:
+      #         :args :: function arguments, can be either a symbol or string specifying a type or an array of 1-3 elements:
+      #                  1 :: argument data type
+      #                  2 :: argument name
+      #                  3 :: argument mode (e.g. in, out, inout)
+      #         :behavior :: Should be IMMUTABLE, STABLE, or VOLATILE.  PostgreSQL assumes VOLATILE by default.
+      #         :cost :: The estimated cost of the function, used by the query planner.
+      #         :language :: The language the function uses.  SQL is the default.
+      #         :link_symbol :: For a dynamically loaded see function, the function's link symbol if different from the definition argument.
+      #         :returns :: The data type returned by the function.  If you are using OUT or INOUT argument modes, this is ignored.
+      #                     Otherwise, if this is not specified, void is used by default to specify the function is not supposed to return a value.
+      #         :rows :: The estimated number of rows the function will return.  Only use if the function returns SETOF something.
+      #         :security_definer :: Makes the privileges of the function the same as the privileges of the user who defined the function instead of
+      #                              the privileges of the user who runs the function.  There are security implications when doing this, see the PostgreSQL documentation.
+      #         :set :: Configuration variables to set while the function is being run, can be a hash or an array of two pairs.  search_path is
+      #                 often used here if :security_definer is used.
+      #         :strict :: Makes the function return NULL when any argument is NULL.
       def create_function(name, definition, opts=OPTS)
         self << create_function_sql(name, definition, opts)
       end
 
       # Create the procedural language in the database. Arguments:
-      # * name : Name of the procedural language (e.g. plpgsql)
-      # * opts : options hash:
-      #   * :handler : The name of a previously registered function used as a call handler for this language.
-      #   * :replace : Replace the installed language if it already exists (on PostgreSQL 9.0+).
-      #   * :trusted : Marks the language being created as trusted, allowing unprivileged users to create functions using this language.
-      #   * :validator : The name of previously registered function used as a validator of functions defined in this language.
+      # name :: Name of the procedural language (e.g. plpgsql)
+      # opts :: options hash:
+      #         :handler :: The name of a previously registered function used as a call handler for this language.
+      #         :replace :: Replace the installed language if it already exists (on PostgreSQL 9.0+).
+      #         :trusted :: Marks the language being created as trusted, allowing unprivileged users to create functions using this language.
+      #         :validator :: The name of previously registered function used as a validator of functions defined in this language.
       def create_language(name, opts=OPTS)
         self << create_language_sql(name, opts)
       end
 
       # Create a schema in the database. Arguments:
-      # * name : Name of the schema (e.g. admin)
-      # * opts : options hash:
-      #   * :if_not_exists : Don't raise an error if the schema already exists (PostgreSQL 9.3+)
-      #   * :owner : The owner to set for the schema (defaults to current user if not specified)
+      # name :: Name of the schema (e.g. admin)
+      # opts :: options hash:
+      #         :if_not_exists :: Don't raise an error if the schema already exists (PostgreSQL 9.3+)
+      #         :owner :: The owner to set for the schema (defaults to current user if not specified)
       def create_schema(name, opts=OPTS)
         self << create_schema_sql(name, opts)
       end
 
       # Create a trigger in the database.  Arguments:
-      # * table : the table on which this trigger operates
-      # * name : the name of this trigger
-      # * function : the function to call for this trigger, which should return type trigger.
-      # * opts : options hash:
-      #   * :after : Calls the trigger after execution instead of before.
-      #   * :args : An argument or array of arguments to pass to the function.
-      #   * :each_row : Calls the trigger for each row instead of for each statement.
-      #   * :events : Can be :insert, :update, :delete, or an array of any of those. Calls the trigger whenever that type of statement is used.  By default,
-      #     the trigger is called for insert, update, or delete.
+      # table :: the table on which this trigger operates
+      # name :: the name of this trigger
+      # function :: the function to call for this trigger, which should return type trigger.
+      # opts :: options hash:
+      #         :after :: Calls the trigger after execution instead of before.
+      #         :args :: An argument or array of arguments to pass to the function.
+      #         :each_row :: Calls the trigger for each row instead of for each statement.
+      #         :events :: Can be :insert, :update, :delete, or an array of any of those. Calls the trigger whenever that type of statement is used.  By default,
+      #                    the trigger is called for insert, update, or delete.
+      #         :when :: A filter to use for the trigger
       def create_trigger(table, name, function, opts=OPTS)
         self << create_trigger_sql(table, name, function, opts)
       end
@@ -234,39 +235,39 @@ module Sequel
       end
 
       # Drops the function from the database. Arguments:
-      # * name : name of the function to drop
-      # * opts : options hash:
-      #   * :args : The arguments for the function.  See create_function_sql.
-      #   * :cascade : Drop other objects depending on this function.
-      #   * :if_exists : Don't raise an error if the function doesn't exist.
+      # name :: name of the function to drop
+      # opts :: options hash:
+      #         :args :: The arguments for the function.  See create_function_sql.
+      #         :cascade :: Drop other objects depending on this function.
+      #         :if_exists :: Don't raise an error if the function doesn't exist.
       def drop_function(name, opts=OPTS)
         self << drop_function_sql(name, opts)
       end
 
       # Drops a procedural language from the database.  Arguments:
-      # * name : name of the procedural language to drop
-      # * opts : options hash:
-      #   * :cascade : Drop other objects depending on this function.
-      #   * :if_exists : Don't raise an error if the function doesn't exist.
+      # name :: name of the procedural language to drop
+      # opts :: options hash:
+      #         :cascade :: Drop other objects depending on this function.
+      #         :if_exists :: Don't raise an error if the function doesn't exist.
       def drop_language(name, opts=OPTS)
         self << drop_language_sql(name, opts)
       end
 
       # Drops a schema from the database.  Arguments:
-      # * name : name of the schema to drop
-      # * opts : options hash:
-      #   * :cascade : Drop all objects in this schema.
-      #   * :if_exists : Don't raise an error if the schema doesn't exist.
+      # name :: name of the schema to drop
+      # opts :: options hash:
+      #         :cascade :: Drop all objects in this schema.
+      #         :if_exists :: Don't raise an error if the schema doesn't exist.
       def drop_schema(name, opts=OPTS)
         self << drop_schema_sql(name, opts)
       end
 
       # Drops a trigger from the database.  Arguments:
-      # * table : table from which to drop the trigger
-      # * name : name of the trigger to drop
-      # * opts : options hash:
-      #   * :cascade : Drop other objects depending on this function.
-      #   * :if_exists : Don't raise an error if the function doesn't exist.
+      # table :: table from which to drop the trigger
+      # name :: name of the trigger to drop
+      # opts :: options hash:
+      #         :cascade :: Drop other objects depending on this function.
+      #         :if_exists :: Don't raise an error if the function doesn't exist.
       def drop_trigger(table, name, opts=OPTS)
         self << drop_trigger_sql(table, name, opts)
       end
@@ -482,6 +483,11 @@ module Sequel
         true
       end
 
+      # PostgreSQL 9.0+ supports trigger conditions.
+      def supports_trigger_conditions?
+        server_version >= 90000
+      end
+
       # PostgreSQL supports prepared transactions (two-phase commit) if
       # max_prepared_transactions is greater than 0.
       def supports_prepared_transactions?
@@ -708,9 +714,12 @@ module Sequel
       end
 
       EXCLUSION_CONSTRAINT_SQL_STATE = '23P01'.freeze
+      DEADLOCK_SQL_STATE = '40P01'.freeze
       def database_specific_error_class_from_sqlstate(sqlstate)
         if sqlstate == EXCLUSION_CONSTRAINT_SQL_STATE
           ExclusionConstraintViolation
+        elsif sqlstate == DEADLOCK_SQL_STATE
+          SerializationFailure
         else
           super
         end
@@ -841,7 +850,11 @@ module Sequel
       def create_trigger_sql(table, name, function, opts=OPTS)
         events = opts[:events] ? Array(opts[:events]) : [:insert, :update, :delete]
         whence = opts[:after] ? 'AFTER' : 'BEFORE'
-        "CREATE TRIGGER #{name} #{whence} #{events.map{|e| e.to_s.upcase}.join(' OR ')} ON #{quote_schema_table(table)}#{' FOR EACH ROW' if opts[:each_row]} EXECUTE PROCEDURE #{function}(#{Array(opts[:args]).map{|a| literal(a)}.join(', ')})"
+        if filter = opts[:when]
+          raise Error, "Trigger conditions are not supported for this database" unless supports_trigger_conditions?
+          filter = " WHEN #{filter_expr(filter)}"
+        end
+        "CREATE TRIGGER #{name} #{whence} #{events.map{|e| e.to_s.upcase}.join(' OR ')} ON #{quote_schema_table(table)}#{' FOR EACH ROW' if opts[:each_row]}#{filter} EXECUTE PROCEDURE #{function}(#{Array(opts[:args]).map{|a| literal(a)}.join(', ')})"
       end
 
       # DDL fragment for initial part of CREATE VIEW statement
@@ -1387,7 +1400,7 @@ module Sequel
       #
       # Options:
       # :cascade :: whether to use the CASCADE option, useful when truncating
-      #   tables with Foreign Keys.
+      #             tables with foreign keys.
       # :only :: truncate using ONLY, so child tables are unaffected
       # :restart :: use RESTART IDENTITY to restart any related sequences
       #