sequel 4.49.0 → 5.3.0

data/doc/transactions.rdoc

@@ -3,6 +3,7 @@
 Sequel uses autocommit mode by default for all of its database adapters, so in general in Sequel if you want to use database transactions, you need to be explicit about it.  There are a few cases where transactions are used implicitly by default:
 
 * Dataset#import to insert many records at once
+* Dataset#paged_each to iterate over large datasets in batches
 * Model#save
 * Model#destroy
 * Migrations if the database supports transactional schema
@@ -35,16 +36,16 @@ If any other exception is raised, the transaction is rolled back, and the except
   end # ROLLBACK
   # ArgumentError raised
 
-If you want Sequel::Rollback exceptions to be reraised, use the <tt>:rollback => :reraise</tt> option:
+If you want Sequel::Rollback exceptions to be reraised, use the <tt>rollback: :reraise</tt> option:
 
-  DB.transaction(:rollback => :reraise) do # BEGIN
+  DB.transaction(rollback: :reraise) do # BEGIN
     raise Sequel::Rollback
   end # ROLLBACK
   # Sequel::Rollback raised
 
-If you always want to rollback (useful for testing), use the <tt>:rollback => :always</tt> option:
+If you always want to rollback (useful for testing), use the <tt>rollback: :always</tt> option:
 
-  DB.transaction(:rollback => :always) do # BEGIN
+  DB.transaction(rollback: :always) do # BEGIN
     DB[:foo].insert(1) # INSERT
   end # ROLLBACK
   # no exception raised
@@ -86,17 +87,17 @@ You can nest calls to transaction, which by default just reuses the existing tra
     end
   end # COMMIT
 
-You can use the <tt>:savepoint => true</tt> option in the inner transaction to explicitly use a savepoint (if the database supports it):
+You can use the <tt>savepoint: true</tt> option in the inner transaction to explicitly use a savepoint (if the database supports it):
 
   DB.transaction do # BEGIN
-    DB.transaction(:savepoint => true) do # SAVEPOINT
+    DB.transaction(savepoint: true) do # SAVEPOINT
       DB[:foo].insert(1) # INSERT
     end # RELEASE SAVEPOINT
   end # COMMIT
 
-You can use the <tt>:auto_savepoint => true</tt> option in the outer transaction to explicitly use a savepoint in the inner transaction (if the database supports it):
+You can use the <tt>auto_savepoint: true</tt> option in the outer transaction to explicitly use a savepoint in the inner transaction (if the database supports it):
 
-  DB.transaction(:auto_savepoint => true) do # BEGIN
+  DB.transaction(auto_savepoint: true) do # BEGIN
     DB.transaction do # SAVEPOINT
       DB[:foo].insert(1) # INSERT
     end # RELEASE SAVEPOINT
@@ -105,7 +106,7 @@ You can use the <tt>:auto_savepoint => true</tt> option in the outer transaction
 If a Sequel::Rollback exception is raised inside the savepoint block, it will only rollback to the savepoint:
 
   DB.transaction do # BEGIN
-    DB.transaction(:savepoint => true) do # SAVEPOINT
+    DB.transaction(savepoint: true) do # SAVEPOINT
       raise Sequel::Rollback
     end # ROLLBACK TO SAVEPOINT
     # no exception raised
@@ -114,7 +115,7 @@ If a Sequel::Rollback exception is raised inside the savepoint block, it will on
 Other exceptions, unless rescued inside the outer transaction block, will rollback the savepoint and the outer transactions, since they are reraised by the transaction code:
 
   DB.transaction do # BEGIN
-    DB.transaction(:savepoint => true) do # SAVEPOINT
+    DB.transaction(savepoint: true) do # SAVEPOINT
       raise ArgumentError
     end # ROLLBACK TO SAVEPOINT
   end # ROLLBACK
@@ -126,7 +127,7 @@ Sequel supports database prepared transactions on PostgreSQL, MySQL, and H2.  Wi
 
 To use prepared transactions in Sequel, you provide a string as the value of the :prepare option:
 
-  DB.transaction(:prepare => 'foo') do # BEGIN
+  DB.transaction(prepare: 'foo') do # BEGIN
     DB[:foo].insert(1) # INSERT
   end # PREPARE TRANSACTION 'foo'
    
@@ -140,9 +141,9 @@ or roll the prepared transaction back:
 
 == Transaction Isolation Levels
 
-The SQL standard supports 4 isolation levels: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, and SERIALIZABLE.  Not all databases implement the levels as specified in the standard (or implement the levels at all), but on most databases, you can specify which transaction isolation level you want to use via the :isolation option to <tt>Database#transaction</tt>.  The isolation level is specified as one of the following symbols: :uncommitted, :committed, :repeatable, and :serializable.  Using this option make Sequel use the correct transaction isolation syntax for your database:
+The SQL standard supports 4 isolation levels: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, and SERIALIZABLE.  Not all databases implement the levels as specified in the standard (or implement the levels at all), but on most databases, you can specify which transaction isolation level you want to use via the :isolation option to <tt>Database#transaction</tt>.  The isolation level is specified as one of the following symbols: :uncommitted, :committed, :repeatable, and :serializable.  Using this option makes Sequel use the correct transaction isolation syntax for your database:
 
-  DB.transaction(:isolation => :serializable) do # BEGIN
+  DB.transaction(isolation: :serializable) do # BEGIN
     # SET TRANSACTION ISOLATION LEVEL SERIALIZABLE
     DB[:foo].insert(1) # INSERT
   end # COMMIT
@@ -151,8 +152,8 @@ The SQL standard supports 4 isolation levels: READ UNCOMMITTED, READ COMMITTED,
 
 Sequel offers the ability to automatically restart transactions if specific types of errors are detected.  For example, if you want to automatically restart a transaction if a serialization failure is detected:
 
-  DB.transaction(:isolation => :serializable, :retry_on=>[Sequel::SerializationFailure]) do
-    ModelClass.find_or_create(:name=>'Foo')
+  DB.transaction(isolation: :serializable, retry_on: [Sequel::SerializationFailure]) do
+    ModelClass.find_or_create(name: 'Foo')
   end
 
 At the serializable transaction isolation level, find_or_create may raises a Sequel::SerializationFailure exception if multiple threads simultaneously run that code.  With the :retry_on option set, the transaction will be automatically retried until it succeeds.
@@ -161,9 +162,9 @@ Note that automatic retrying should not be used unless the entire transaction
 block is idempotent, as otherwise it can cause non-idempotent
 behavior to execute multiple times.  For example, with the following code:
 
-  DB.transaction(:isolation => :serializable, :retry_on=>[Sequel::SerializationFailure]) do
+  DB.transaction(isolation: :serializable, retry_on: [Sequel::SerializationFailure]) do
     logger.info 'Ensuring existence of ModelClass with name Foo'
-    ModelClass.find_or_create(:name=>'Foo')
+    ModelClass.find_or_create(name: 'Foo')
   end
 
 The logger.info method will be called multiple times if there is a serialization failure.

data/doc/validations.rdoc

@@ -13,7 +13,7 @@ types of validations to your models.
 
 Validations are primarily useful for associating error messages to display to the user
 with specific attributes on the model.  It is also possible to use them to enforce
-data integrity for model instances, but that's not a recommended use unless
+data integrity for model instances, but that's not recommended unless
 the only way to modify the database is through model instances, or you have
 complex data integrity requirements that aren't possible to specify via
 database-level constraints.
@@ -30,19 +30,17 @@ be setting the size of the varchar column to 255, and using a CHECK constraint
 to ensure that all values have at least two characters.
 
 Unfortunately, sometimes there are situations where that is not possible.  For
-example, if you are using MySQL and don't have control over the database configuration,
-it's possible that if you attempt to insert a string with 300 characters into a
-varchar(255) field, then MySQL may just silently truncate it for you, instead of
-raising an error.  In that case, it may be necessary to use a model validation
+example, if you don't have control over the schema and cannot add constraints,
+or you are using MySQL (which doesn't support CHECK constraints), it may be necessary to use a model validation
 to enforce the database integrity.
 
-Also, in some cases you may have data integrity requirements that are difficult to
+In some cases you may have data integrity requirements that are difficult to
 enforce via database constraints, especially if you are targetting multiple
 database types.
 
-Finally, validations are generally easier to write than database constraints,
+Validations are generally easier to write than database constraints,
 so if data integrity isn't of great importance, using validations to provide minimal
-data integrity is probably fine.
+data integrity may be acceptable.
 
 == Usage
 
@@ -71,11 +69,12 @@ saving of model objects passes through the +save+ method.  This means that all
 saving of model objects goes through the validation process.
 
 The only way to skip validations when saving a model object is to pass the
-<tt>:validate => false</tt> option to +save+. If you use that option, +save+ will
+<tt>validate: false</tt> option to +save+. If you use that option, +save+ will
 not attempt to validate the object before saving it.  
 
 Note that it's always possible to update the instance's database row without using
-+save+, by using a dataset to update it.  Validations will only be run if you call
++save+, by using a Sequel dataset to update it, or updating it via another program.
+Validations will only be run if you call
 +save+ on the model object, or another model method that calls +save+.  For example,
 the +create+ class method instantiates a new instance of the model, and then calls
 +save+, so it validates the object.  However, the +insert+ class method is a dataset
@@ -96,8 +95,8 @@ model instance is valid.  This method should not be overridden.  Instead, the
   end
 
   Album.new.valid? # false
-  Album.new(:name=>'').valid? # false
-  Album.new(:name=>'RF').valid? # true
+  Album.new(name: '').valid? # false
+  Album.new(name: 'RF').valid? # true
   
 If the <tt>valid?</tt> method returns false, you can call the +errors+ method to
 get an instance of <tt>Sequel::Model::Errors</tt> describing the errors on the model:
@@ -135,7 +134,7 @@ specifying validations like this:
     def validate
       super
       errors.add(:name, 'cannot be empty') if !name || name.empty?
-      errors.add(:name, 'is already taken') if name && new? && Album[:name=>name]
+      errors.add(:name, 'is already taken') if name && new? && Album[{name: name}]
       errors.add(:website, 'cannot be empty') if !website || website.empty?
       errors.add(:website, 'is not a valid URL') unless website =~ /\Ahttps?:\/\//
     end
@@ -149,7 +148,7 @@ You can call simple methods such as:
       super
       validates_presence [:name, :website]
       validates_unique :name
-      validates_format /\Ahttps?:\/\//, :website, :message=>'is not a valid URL'
+      validates_format /\Ahttps?:\/\//, :website, message: 'is not a valid URL'
     end
   end
 
@@ -168,7 +167,7 @@ The following methods are provided by +validation_helpers+:
 
 === +validates_presence+
 
-This is probably the most commonly used helper method, which checks if the specified attributes are not blank.  In general, if an object responds to <tt>blank?</tt>, it calls the method to determine if the object is blank.  Otherwise, nil is considered blank, empty strings or strings that just contain whitespace are blank, and objects that respond to <tt>empty?</tt> and return true are considered blank.  All other objects are considered non-blank for the purposes of +validates_presence+.  This means that +validates_presence+ is safe to use on boolean columns where you want to ensure that either true or false is used, but not NULL.
+This method checks that the specified attributes are not blank.  In general, if an object responds to <tt>blank?</tt>, it calls the method to determine if the object is blank.  Otherwise, nil is considered blank, empty strings or strings that just contain whitespace are blank, and objects that respond to <tt>empty?</tt> and return true are considered blank.  All other objects are considered non-blank for the purposes of +validates_presence+.  This means that +validates_presence+ is safe to use on boolean columns where you want to ensure that either true or false is used, but not NULL.
 
   class Album < Sequel::Model
     def validate
@@ -195,7 +194,7 @@ This is similar to +validates_presence+, but only checks for NULL/nil values, al
 
 === +validates_exact_length+, +validates_min_length+, +validates_max_length+, +validates_length_range+
 
-These methods all deal with ensuring that the length of the specified attribute matches the criteria specified by the first argument to the method.  +validates_exact_length+ is for checking that the length of the attribute is equal to that value, +validates_min_length+ is for checking that the length of the attribute is greater than or equal to that value, +validates_max_length+ is for checking that the length of the attribute is less than or equal to that value, and +validates_length_range+ is for checking that the length of the attribute falls in the value, which should be a range or another object that responds to <tt>include?</tt>.
+These methods all deal with ensuring that the length of the specified attribute matches the criteria specified by the first argument to the method.  +validates_exact_length+ is for checking that the length of the attribute is equal to that value, +validates_min_length+ is for checking that the length of the attribute is greater than or equal to that value, +validates_max_length+ is for checking that the length of the attribute is less than or equal to that value, and +validates_length_range+ is for checking that the length of the attribute falls in the value, which should be a range or an object that responds to <tt>include?</tt>.
  
 
   class Album < Sequel::Model
@@ -257,17 +256,17 @@ These methods check that the specified attributes can be valid integers or valid
 
 === +validates_schema_types+
 
-+validates_schema_types+ uses the database metadata for the model's table to determine which ruby type(s) should be used for the given database type, and calls +validates_type+ with that ruby type.  It's designed to be used with the <tt>raise_on_typecast_failure = false</tt> setting (the default starting in Sequel 4).  <tt>raise_on_typecast_failure = false</tt>, Sequel attempts to typecast values, but silently ignores any errors raised:
++validates_schema_types+ uses the database metadata for the model's table to determine which ruby type(s) should be used for the given database type, and calls +validates_type+ with that ruby type.  It's designed to be used with the default <tt>raise_on_typecast_failure = false</tt> setting, where Sequel will attempt to typecast values, but silently ignore any errors raised:
 
-  Album.raise_on_typecast_failure = false
   album = Album.new
+  album.copies_sold = '1'
+  album.copies_sold # => 1
   album.copies_sold = 'banana'
   album.copies_sold # => 'banana'
 
-When <tt>raise_on_typecast_failure = false</tt>, you can call +validates_schema_types+ with all columns.  If any of those columns has a value that doesn't match the type that Sequel expects, it's probably because the column was set and Sequel was not able to typecast it correctly, which means it probably isn't valid.  For example, let's say that you want to check that a couple of columns contain valid dates:
+In general, you can call +validates_schema_types+ with all columns.  If any of those columns has a value that doesn't match the type that Sequel expects, it's probably because the column was set and Sequel was not able to typecast it correctly, which means it probably isn't valid.  For example, let's say that you want to check that a couple of columns contain valid dates:
 
   class Album < Sequel::Model
-    self.raise_on_typecast_failure = false
     def validate
       super
       validates_schema_types [:release_date, :record_date]
@@ -282,7 +281,7 @@ When <tt>raise_on_typecast_failure = false</tt>, you can call +validates_schema_
   album.valid? # => false
   album.errors # => {:release_date=>["is not a valid date"]}
 
-For web applications, you usually want the <tt>raise_on_typecast_failure = false</tt> setting, so that you can accept all of the input without raising an error, and then present the user with all error messages.  Without the setting, if the user submits any invalid data, Sequel will immediately raise an error.  +validates_schema_types+ is helpful because it allows you to check for typecasting errors on columns, and provides a good default error message stating that the attribute is not of the expected type.
+For web applications, you usually want the default setting, so that you can accept all of the input without raising an error, and then present the user with all error messages.  If <tt>raise_on_typecast_failure = true</tt> is set and the user submits any invalid data, Sequel will immediately raise an error.  +validates_schema_types+ is helpful because it allows you to check for typecasting errors on columns, and provides a good default error message stating that the attribute is not of the expected type.
 
 === +validates_unique+
 
@@ -310,7 +309,7 @@ You can also include an options hash as the last argument.  Unlike the other val
 
 :dataset :: The base dataset to use for the unique query, defaults to the model's dataset
 :message :: The message to use
-:only_if_modified :: Only check the uniqueness if the object is new or one of the columns has been modified.
+:only_if_modified :: Only check the uniqueness if the object is new or one of the columns has been modified (true by default).
 :where :: A callable object where call takes three arguments, a dataset,
           the current object, and an array of columns, and should return
           a modified dataset that is filtered to include only rows with
@@ -323,17 +322,17 @@ You can also include an options hash as the last argument.  Unlike the other val
 
 == +validation_helpers+ Options
 
-All +validation_helpers+ methods except +validates_unique+ accept the following options:
+All other +validation_helpers+ methods accept the following options:
 
 === <tt>:message</tt>
 
-The most commonly used option, used to override the default validation message.  Can be either a string or a proc.  If a string, it is used directly.  If a proc, the proc is called and should return a string.  If the validation method takes an argument before the array of attributes, that argument is passed as an argument to the proc. The exception is the +validates_not_string+ method, which doesn't take an argument, but passes the schema type symbol as the argument to the proc.
+The <tt>:message</tt> option overrides the default validation error message.  Can be either a string or a proc.  If a string, it is used directly.  If a proc, the proc is called and should return a string.  If the validation method takes an argument before the array of attributes, that argument is passed as an argument to the proc.
 
   class Album < Sequel::Model
     def validate
       super
-      validates_presence :copies_sold, :message=>'was not given'
-      validates_min_length 3, :name, :message=>proc{|s| "should be more than #{s} characters"}
+      validates_presence :copies_sold, message: 'was not given'
+      validates_min_length 3, :name, message: lambda{|s| "should be more than #{s} characters"}
     end
   end
 
@@ -345,7 +344,7 @@ The <tt>:allow_nil</tt> option skips the validation if the attribute value is ni
     def validate
       super
       validates_presence :copies_sold
-      validates_integer :copies_sold, :allow_nil=>true
+      validates_integer :copies_sold, allow_nil: true
     end
   end
 
@@ -358,17 +357,13 @@ The <tt>:allow_blank</tt> is similar to the <tt>:allow_nil</tt> option, but inst
   class Album < Sequel::Model
     def validate
       super
-      validates_format /\Ahttps?:\/\//, :website, :allow_blank=>true
+      validates_format /\Ahttps?:\/\//, :website, allow_blank: true
     end
   end
   a = Album.new
   a.website = ''
   a.valid? # true
 
-If you are going to use <tt>:allow_blank</tt> you should make sure that all objects respond to the blank? method. Sequel ships with an extension that will do this for you:
-
-  Sequel.extension :blank
-
 === <tt>:allow_missing</tt>
 
 The <tt>:allow_missing</tt> option is different from the <tt>:allow_nil</tt> option, in that instead of checking if the attribute value is nil, it checks if the attribute is present in the model instance's values hash.   <tt>:allow_nil</tt> will skip the validation when the attribute is in the values hash and has a nil value and when the attribute is not in the values hash.  <tt>:allow_missing</tt> will only skip the validation when the attribute is not in the values hash.  If the attribute is in the values hash but has a nil value, <tt>:allow_missing</tt> will not skip it.
@@ -428,17 +423,26 @@ These are the default error messages for all of the helper methods in +validatio
 
 == Modifying the Default Options
 
-It's easy to modify the default options used by +validation_helpers+.  All of the default options are stored in the <tt>Sequel::Plugins::ValidationHelpers::DEFAULT_OPTIONS</tt> hash.  So you just need to modify that hash to change the default options.  One way to do that is to use <tt>merge!</tt> to update the hash:
-
-  Sequel::Plugins::ValidationHelpers::DEFAULT_OPTIONS.merge!(
-   :presence=>{:message=>'cannot be empty'},
-   :includes=>{:message=>'invalid option', :allow_nil=>true},
-   :max_length=>{:message=>lambda{|i| "cannot be more than #{i} characters"}, :allow_nil=>true},
-   :format=>{:message=>'contains invalid characters', :allow_nil=>true})
-
-This updates the default messages that will be used for the presence, includes, max_length, and format validations, and sets the default value of the <tt>:allow_nil</tt> option to true for the includes, max_length, and format validations.
+You can override <tt>Sequel::Model#default_validation_helpers_options</tt> private method to override the default settings on a per validation type basis:
 
-You can also override <tt>Sequel::Model#default_validation_helpers_options</tt> private method to override these settings on a per-model or even per-instance basis.
+  class Sequel::Model
+    private
+
+    def default_validation_helpers_options(type)
+      case type
+      when :presence
+        {message: 'cannot be empty'}
+      when :includes
+        {message: 'invalid option', allow_nil: true}
+      when :max_length
+        {message: lambda{|i| "cannot be more than #{i} characters"}, allow_nil: true}
+      when :format
+        {message: 'contains invalid characters', allow_nil: true}
+      else
+        super
+      end
+    end
+  end
 
 == Custom Validations
 
@@ -480,7 +484,7 @@ Let's say you want to add some default validations that apply to all of your mod
       super
       validates_format(/\A[^\x00-\x08\x0e-\x1f\x7f\x81\x8d\x8f\x90\x9d]*\z/n,
        model.string_columns,
-       :message=>"contains invalid characters")
+       message: "contains invalid characters")
     end
   end
 
@@ -547,9 +551,8 @@ Sequel ships with a +constraint_validations+ plugin and extension, that allows y
 
 === +auto_validations+
 
-Autovalidations uses the not null and type information obtained from parsing the database schema, and the unique index information from parsing the database's index information, and automatically setting up not_null, schema_types, and unique validations.  If you don't require customizing validation messages on a per-column basis, it can DRY up a lot of validation code.
+auto_validations uses the not null and type information obtained from parsing the database schema, and the unique index information from parsing the database's index information, and automatically setting up not_null, string length, schema type, and unique validations.  If you don't require customizing validation messages on a per-column basis, it can DRY up a lot of validation code.
 
 === +validation_class_methods+
 
 Sequel ships with the +validation_class_methods+ plugin, which uses class methods instead of instance methods to define validations.  It exists mostly for legacy compatibility, but it is still supported.
-