sequel 3.21.0 → 3.41.0

data/doc/model_hooks.rdoc

@@ -4,7 +4,7 @@ This guide is based on http://guides.rubyonrails.org/activerecord_validations_ca
 
 == Overview
 
-Model hooks, also known as model callbacks, are used to specify actions that occur at a given point in a model instance's lifecycle, such as before or after the model object is saved, created, updated, destroyed, or validated.
+Model hooks, also known as model callbacks, are used to specify actions that occur at a given point in a model instance's lifecycle, such as before or after the model object is saved, created, updated, destroyed, or validated.  There are also around hooks for all types, which wrap the before hooks, the behavior, and the after hooks.
 
 == Basic Usage
 
@@ -23,41 +23,65 @@ The one important thing to note here is the call to +super+ inside the hook.  Wh
 
 Sequel calls hooks in the following order when saving/creating a new object (one that does not already exist in the database):
 
-* +before_validation+
-* +after_validation+
-* +before_save+
-* +before_create+
-* INSERT QUERY
-* +after_create+
-* +after_save+
+* +around_validation+
+  * +before_validation+
+  * +validate+ method called
+  * +after_validation+
+* +around_save+
+  * +before_save+
+  * +around_create+
+    * +before_create+
+    * INSERT QUERY
+    * +after_create+
+  * +after_save+
 
 Sequel calls hooks in the following order when saving an existing object:
 
-* +before_validation+
-* +after_validation+
-* +before_save+
-* +before_update+
-* UPDATE QUERY
-* +after_update+
-* +after_save+
+* +around_validation+
+  * +before_validation+
+  * +validate+ method called
+  * +after_validation+
+* +around_save+
+  * +before_save+
+  * +around_update+
+    * +before_update+
+    * UPDATE QUERY
+    * +after_update+
+  * +after_save+
 
-Note that all of the hook calls are the same, except that +before_create+ and +after_create+ are used for a new object, and +before_update+ and +after_update+ are used for an existing object.  Note that +before_save+ is called in both cases, before either +before_create+ or +before_update+, and that +after_save+ is also called in both cases, after either +after_create+ or +after_update+.
+Note that all of the hook calls are the same, except that +around_create+, +before_create+ and +after_create+ are used for a new object, and +around_update+, +before_update+ and +after_update+ are used for an existing object.  Note that +around_save+, +before_save+, and +after_save+ are called in both cases.
 
 Also note that the validation hooks are not called if the <tt>:validate => false</tt> option is passed to save.  However, the validation hooks are called if you call <tt>Model#valid?</tt> manually:
 
-* +before_validation+
-* VALIDATION HAPPENS
-* +after_validation+
+* +around_validation+
+  * +before_validation+
+  * +validate+ method called
+  * +after_validation+
 
 Sequel calls hooks in the following order when destroying an existing object:
 
-* +before_destroy+
-* DELETE QUERY
-* +after_destroy+
+* +around_destroy+
+  * +before_destroy+
+  * DELETE QUERY
+  * +after_destroy+
 
 Note that these hooks are only called when using <tt>Model#destroy</tt>, they are not called if you use <tt>Model#delete</tt>.
 
-<tt>Sequel::Model</tt> does support one additional hook, +after_intialize+, which is called after the model object has been initalized.  It can be used to set default attribute values for new objects, since by default new <tt>Sequel::Model</tt> objects have no attributes, and the attributes are not filled in until the model object is saved.  You should be careful when you are using +after_initialize+, since it is called for every created record.  So if you run a query that returns 1000 model objects, it will be called 1000 times.
+<tt>Sequel::Model</tt> does support a few additional hooks. One is +after_intialize+, which is called after the model object has been initalized.  It can be used to set default attribute values for new objects, since by default new <tt>Sequel::Model</tt> objects have no attributes, and the attributes are not filled in until the model object is saved.  You should be careful when you are using +after_initialize+, since it is called for every created record.  So if you run a query that returns 1000 model objects, it will be called 1000 times.  If you only want to change the behavior for new records, you can override the +initialize_set+ private method, which is called with the hash passed to +initialize+.
+
+== Special Hook-Related Instance Variables
+
+For after_save hooks, a @was_new instance variable is present that indicates whether the record was a new record that was just inserted, or an existing record that was updated.  Sequel marks a record as existing as soon as it inserts the record, so in an after_save or after_create hook, the instance is no longer considered new.  You have to check @was_new to see if the record was inserted.  This exists so that you don't have to have separate after_create and after_update hooks that are mostly the same and only differ slightly depending on whether the record was a new record.
+
+For after_update hooks, a @columns_updated instance variable is present that is a hash of the values used to update the row (keys are column symbols, values are column values).  This should be used by any code that wants to check what columns and values were used during the update.  You can't just check the current values of the instance, since Sequel offers ways to manually specify which columns to use during the save.
+
+== Transaction-related Hooks
+
+There are four other model hooks that <tt>Sequel::Model</tt> supports, all related to transactions.  These are +after_commit+, +after_rollback+, +after_destroy_commit+, and +after_destroy_rollback+.  +after_commit+ is called after the transaction in which you saved the object commits, only if it commits.  +after_rollback+ is called after the transaction in which you saved the object rolls back, if it rolls back.  +after_destroy_commit+ is called after the transaction in which you destroyed the object commits, if it commits.  +after_destroy_rollback+ is called after the transaction in which you destroyed the object rolls back, if it rolls back.
+
+If you aren't using transactions when saving or destroying model objects, and there isn't a currently open transaction, +after_commit+ and +after_destroy_commit+ will be called after +after_save+ and +after_destroy+, respectively, and +after_rollback+ and +after_destroy_rollback+ won't be called at all.
+
+The purpose of these hooks is dealing with external systems that are interacting with the same database.  For example, let's say you have a model that stores a picture, and you have a background job library that makes thumbnails of all of the pictures.  So when a model object is created, you want to add a background job that will create the thumbnail for the picture.  If you used after_save for this and transactions are being used, you are subject to a race condition where the background job library will check the database table for the record before the transaction that saved the record commits, and it won't be able to see the record's data.  Using after_commit, you are guaranteed that the background job library will not get notified of the record until after the transaction commits and the data is viewable.
 
 == Running Hooks
 
@@ -65,10 +89,10 @@ Sequel does not provide a simple way to turn off the running of save/create/upda
 
 However, you should note that there are plenty of ways to modify the database without saving a model object.  One example is by using plain datasets, or one of the model's dataset methods:
 
-  Album.filter(:name=>'RF').update(:copies_sold=>:copies_sold + 1)
+  Album.where(:name=>'RF').update(:copies_sold=>:copies_sold + 1)
   # UPDATE albums SET copies_sold = copies_sold + 1 WHERE name = 'RF'
 
-In this case, the +update+ method is called on the dataset returned by <tt>Album.filter</tt>.  Even if there is only a single object with the name RF, this will not call any hooks.  If you want model hooks to be called, you need to make sure to operate on a model object:
+In this case, the +update+ method is called on the dataset returned by <tt>Album.where</tt>.  Even if there is only a single object with the name RF, this will not call any hooks.  If you want model hooks to be called, you need to make sure to operate on a model object:
 
   album = Album.first(:name=>'RF')
   album.update(:copies_sold=>album.copies_sold + 1)
@@ -98,7 +122,7 @@ If you want to insert a row into the model's table without running the creation
 
 == Halting Hook Processing
 
-Sequel uses a convention that if any <tt>before_*</tt> hook method returns false (but not nil), that the action will be canceled.  You can use this to implement validation-like behavior, that will run even if validations are skipped.  For example:
+Sequel uses a convention that if any <tt>before_*</tt> hook method returns false (but not nil), that the action will be canceled and a <tt>Sequel::HookFailed</tt> raised (or +nil+ to be returned by +save+ if +raise_on_save_failure+ is +false+).  You can use this to implement validation-like behavior, that will run even if validations are skipped.  For example:
 
   class Album < Sequel::Model
     def before_save
@@ -107,9 +131,9 @@ Sequel uses a convention that if any <tt>before_*</tt> hook method returns false
     end
   end
 
-While returning false is not really recommended, you should be aware of this behavior so that you do not inadvertently return false.
+While returning false is not really recommended, you should be aware of this behavior so that you do not inadvertently return false.  For around hooks, neglecting to call +super+ halts hook processing in the same way as returning +false+ in a before hook.  You can't halt hook processing in after hooks, since by then the main processing has already taken place.
 
-By default, Sequel runs hooks other than validation hooks inside a transaction, so if you abort the hook by returning false in a before hook or by raising an exception in the hook, Sequel will rollback the transaction.  However, note that the implicit use of transactions when saving and destroying model objects is conditional (it depends on the model instance's +use_transactions+ setting).
+By default, Sequel runs hooks other than validation hooks inside a transaction, so if you abort the hook by returning false in a before hook or by raising an exception in any hook, Sequel will rollback the transaction.  However, note that the implicit use of transactions when saving and destroying model objects is conditional (it depends on the model instance's +use_transactions+ setting and the <tt>:transaction</tt> option passed to save).
 
 == Conditional Hooks
 
@@ -183,6 +207,7 @@ This allows the following general principles to be true:
 
 * before hooks are run in reverse order of inclusion
 * after hooks are run in order of inclusion
+* returning false in any before hook will pass the false value down the hook method chain, halting the hook processing.
 
 So if you define the same before hook in both a model and a plugin that the model uses, the hooks will be called in this order:
 
@@ -193,6 +218,32 @@ So if you define the same before hook in both a model and a plugin that the mode
 
 Again, Sequel does not enforce that, and you are free to call +super+ in an order other than the recommended one (just make sure that you call it).
 
+== Around Hooks
+
+Around hooks should only be used if you cannot accomplish the same results with before and after hooks.  For example, if you want to catch database errors caused by the +INSERT+ or +UPDATE+ query when saving a model object and raise them as validation errors, you cannot use a before or after hook.  You have use an +around_save+ hook:
+
+  class Album < Sequel::Model
+    def around_save
+      super
+    rescue Sequel::DatabaseError => e
+      # parse database error, set error on self, and reraise a Sequel::ValidationFailed
+    end
+  end
+ 
+Likewise, let's say that upon retrieval, you associate an object with a file descriptor, and you want to ensure that the file descriptor is closed after the object is saved to the database.  Let's assume you are always saving the object and you are not using validations.  You could not use an +after_save+ hook safely, since if the database raises an error, the +after_save+ method will not be called.  In this case, an +around_save+ hook is also the correct choice:
+
+  class Album < Sequel::Model
+    def around_save
+      super
+    ensure
+      @file_descriptor.close
+    end
+  end
+
 == +hook_class_methods+
 
-While it's recommended to write your hooks as instance methods, Sequel ships with a +hook_class_methods+ plugin that allows you to define hooks via class methods. It exists mostly for legacy compatibility, but is still supported. 
+While it's recommended to write your hooks as instance methods, Sequel ships with a +hook_class_methods+ plugin that allows you to define hooks via class methods. It exists mostly for legacy compatibility, but is still supported.  However, it does not implement around hooks.
+
+== +instance_hooks+
+
+Sequel also ships with an +instance_hooks+ plugin that allows you to define before and after hooks on a per instance basis.  It's very useful as it allows you to delay action on an instance until before or after saving.  This can be important if you want to modify a group of related objects together (which is how the +nested_attributes+ plugin uses +instance_hooks+).