sequel 3.21.0 → 3.28.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,51 @@ 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+
+    * INSERT 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 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.  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+. 
 
 == Running Hooks
 
@@ -98,7 +108,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 +117,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 +193,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 +204,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+).

data/doc/opening_databases.rdoc

@@ -46,6 +46,13 @@ unless the first argument is a hash. So the following statements are equivalent
   DB = Sequel.postgres('blog', :host=>'localhost', :user=>'user', :password=>'password')
   DB = Sequel.postgres(:host=>'localhost', :user=>'user', :password=>'password', :database=>'blog')
 
+Note that using an adapter method forces the use of the specified adapter, not a database type, even
+though some adapters have the same name as the database type.  So if you
+want to connect to SQLite, for example, you can do so using the sqlite, do, dbi, jdbc, odbc, and swift adapters.
+If you want to connect to SQLite on JRuby using the jdbc adapter, you should not use <tt>Sequel.sqlite</tt>
+for example, as that uses the C-based sqlite3 gem. Instead, the <tt>Sequel.jdbc</tt> would be appropriate (though
+as mentioned below, using <tt>Sequel.connect</tt> is recommended instead of <tt>Sequel.jdbc</tt>). 
+
 == Passing a block to either method
 
 Both the Sequel.connect method and the specialized adapter methods take a block.  If you
@@ -145,10 +152,8 @@ the sqlite section below for details.
 
 Requires: db2/db2cli
 
-I'm not even sure exactly how this works, or if it works at all (I've never heard from
-anyone who attempted to use it).  It uses the SQL_HANDLE_DBC constant to
-get a handle, and respects the :database, :user, and :password options.  It doesn't
-appear to respect the :host or :port options.
+This is the older DB2 adapter.  It's recommended you try the ibmdb adapter
+instead for new DB2 work, as it is better supported.
 
 === dbi 
 
@@ -201,6 +206,13 @@ Requires: fb (using code at http://github.com/wishdev/fb)
 
 Does not support the :port option.
 
+=== ibmdb
+
+requires 'ibm_db'
+
+This connects to DB2 using IBM_DB.  This is the recommended adapter if you are
+using a C-based ruby to connect to DB2.
+
 === informix 
 
 Does not support the :host or :port options.  Depending on the configuration of your server
@@ -221,7 +233,7 @@ Requires: java
 Houses Sequel's JDBC support when running on JRuby.
 Support for individual database types is done using sub adapters.
 There are currently subadapters for PostgreSQL, MySQL, SQLite, H2,
-Oracle, MSSQL, JTDS, and AS400.  All except Oracle, MSSQL, and AS400 can load the
+Oracle, MSSQL, JTDS, AS400, and DB2.  All except Oracle, MSSQL, AS400, and DB2 can load the
 jdbc-* gem, for those you need to have the .jar in your CLASSPATH
 or load the Java class manually before calling Sequel.connect.
 
@@ -262,6 +274,8 @@ The following additional options are supported:
 
 === mysql 
 
+Requires: mysqlplus (or mysql if mysqlplus is not available)
+
 The MySQL adapter does not support the pure-ruby MySQL adapter that used to ship with
 ActiveRecord, it requires the native adapter.
 
@@ -278,6 +292,12 @@ The following additional options are supported:
 * :read_timeout - Set the timeout in seconds for reading back results to a query.
 * :connect_timeout - Set the timeout in seconds before a connection attempt is abandoned.
 
+=== mysql2
+
+This is a newer MySQL adapter that does typecasting in C, so it is often faster than the
+mysql adapter.  Supports the same additional options as the mysql adapter, except for :compress, and uses
+:timeout instead of :read_timeout and :connect_timeout.
+
 === odbc 
 
 The ODBC adapter allows you to connect to any database with the appropriate ODBC drivers installed.  
@@ -316,6 +336,8 @@ The following additional options are supported:
 
 === sqlite
 
+Requires: sqlite3
+
 As SQLite is a file-based database, the :host and :port options are ignored, and
 the :database option should be a path to the file.
 
@@ -353,16 +375,21 @@ Examples:
 
 === tinytds
 
+Requires: tiny_tds
+
 Because the underscore is not a valid character in a URI schema, the adapter
 is named tinytds instead of tiny_tds.  The connection options are passed directly
-to tiny_tds, except that the tiny_tds :dataserver and :username options are set to
-the Sequel :host and :user options.  The :host option should be an entry in the
-freetds.conf file, it's not currently possible to a host not present in the
-freetds.conf file.  Some options that you may want to set are
-:login_timeout, :timeout, :appname, and :encoding, see the tiny_tds README for details.
+to tiny_tds, except that the tiny_tds :username option is set to
+the Sequel :user option.  If you want to use an entry in the freetds.conf file, you
+should specify the :dataserver option with that name as the value.  Some other
+options that you may want to set are :login_timeout, :timeout, :tds_version, :azure,
+:appname, and :encoding, see the tiny_tds README for details.
+
 For highest performance, you should disable any identifier output method when
 using the tinytds adapter, which probably means disabling any identifier input method
 as well.  The default for Microsoft SQL Server is to :downcase identifiers on output
 and :upcase them on input, so the highest performance will require changing the setting
 from the default.
 
+The Sequel tinytds adapter requires tiny_tds >= 0.4.5, and if you are using FreeTDS
+0.91, you must at least be using 0.91rc2 (0.91rc1 does not work).

data/doc/prepared_statements.rdoc

@@ -3,15 +3,21 @@
 Sequel has support for prepared statements and bound variables.  No matter which
 database you are using, the Sequel prepared statement/bound variable API remains
 the same.  There is native support for prepared statements/bound variables on
-the following databases:
+the following adapters:
 
-* PostgreSQL (using the pg driver, requires type specifiers)
-* MySQL (prepared statements only, as the ruby mysql driver doesn't support
-  bound variables)
-* SQLite
-* JDBC
+* ibmdb (prepared statements only)
+* jdbc
+* mysql (prepared statements only)
+* mysql2 (prepared statements only)
+* postgres (when using the pg driver, may require type specifiers)
+* sqlite
+* tinytds
 
-Support on other databases is emulated via string interpolation.
+Support on other adapters is emulated via string interpolation.
+
+You can use the prepared_statements model plugin to automatically use prepared
+statements for some common model actions such as saving or deleting a model
+instance, or looking up a model based on a primary key.
 
 == Placeholders
 
@@ -74,9 +80,9 @@ and update queries, the hash to insert/update is passed to +prepare+:
 
 If you are using the ruby-postgres or postgres-pr driver, PostgreSQL uses the
 default emulated support.  If you are using ruby-pg, there is native support,
-but it requires type specifiers most of the time.  This is easy if you have
+but it may require type specifiers.  This is easy if you have
 direct control over the SQL string, but since Sequel abstracts that, the types
-have to be specified another way.  This is done by adding a __* suffix to the
+can be specified another way.  This is done by adding a __* suffix to the
 placeholder symbol (e.g. :$name__text, which will be compiled to "$1::text"
 in the SQL).  Prepared statements are always server side.
 
@@ -87,7 +93,7 @@ statements are cached per connection.
 
 === MySQL
 
-The MySQL ruby driver does not support bound variables, so the the bound
+The MySQL ruby driver does not support bound variables, so the bound
 variable methods fall back to string interpolation.  It uses server side
 prepared statements.
 

data/doc/reflection.rdoc

@@ -16,13 +16,19 @@ In some cases, the adapter scheme will be the same as the database to which you
 
 == Tables in the Database
 
-On many database types/adapters, Database#tables exists and gives an array of table name symbols:
+Database#tables gives an array of table name symbols:
+
+  DB.tables # [:table1, :table2, :table3, ...]
+
+== Views in the Database
+
+Database#views and gives an array of view name symbols:
 
   DB.tables # [:table1, :table2, :table3, ...]
 
 == Indexes on a table
 
-On a few database types/adapters, Database#indexes takes a table name gives a hash of index information.  Keys are index names, values are subhashes with the keys :columns and :unique :
+Database#indexes takes a table name gives a hash of index information.  Keys are index names, values are subhashes with the keys :columns and :unique :
 
   DB.indexes(:table1) # {:index1=>{:columns=>[:column1], :unique=>false}, :index2=>{:columns=>[:column2, :column3], :unique=>true}}
 

data/doc/release_notes/3.22.0.txt

@@ -0,0 +1,39 @@
+= New Features
+
+* Support COLLATE in column definitions.  At least MySQL and Microsoft
+  SQL Server support them, and PostgreSQL 9.1 should as well.
+
+* When connecting to Microsoft SQL Server, you can use the
+  mssql_unicode_strings accessor to turn of the default usage
+  of unicode strings (N'') and use regular strings (''). This
+  can improve performance, but changes the behavior.  It's
+  set to true by default for backwards compatibility.  You can
+  change it at both the dataset and database level:
+
+    DB.mssql_unicode_strings = false # default for datasets
+    dataset.mssql_unicode_strings = false # just this dataset
+
+* In the oracle adapter, if Sequel.application_timezone is :utc, set
+  the timezone for the connection to use the 00:00 timezone.
+
+= Other Improvements
+
+* In the single_table_inheritance plugin, correctly handle a
+  multi-level class hierarchy so that loading instances from a
+  middle level of the hierarchy can return instances of subclasses.
+
+* Don't use a schema when creating a temporary table, even if
+  default_schema is set.
+
+* Fix the migrator when a default_schema is used.
+
+* In the ado adapter, assume a connection to SQL Server if the
+  :conn_string is given and doesn't indicate Access/Jet.
+
+* Fix fetching rows in the tinytds adapter when the
+  identifier_output_method is nil.
+
+* The tinytds adapter now checks for disconnect errors, but it might
+  not be reliable until the next release of tiny_tds.
+
+* The odbc adapter now handles ODBC::Time instances correctly.

data/doc/release_notes/3.23.0.txt

@@ -0,0 +1,172 @@
+= New Features
+
+* Sequel now allows dynamic customization for eager loading.
+  Previously, the parameters for eager loading were fixed at
+  association creation time.  Now, they can be modified at query
+  time.  To dynamically modify an eager load, you use a hash with
+  the proc as the value. For example, if you have this code:
+
+    Artist.eager(:albums)
+
+  And you only want to eagerly load albums where the id is greater
+  than or equal to some number provided by the user, you do:
+
+    min = params[:min].to_i
+    Artist.eager(:albums=>proc{|ds| ds.where{id > min}})
+    
+  This also works when eager loading via eager_graph:
+  
+    Artist.eager_graph(:albums=>proc{|ds| ds.where{id > min}})
+  
+  For eager_graph, the dataset is the dataset to graph into the
+  current dataset, and filtering it will result in an SQL query
+  that joins to a subquery.
+  
+  You can also use dynamic customization while cascading to also
+  eagerly load dependent associations, by making the hash value
+  a single entry hash with a proc key and the value being the
+  dependent associations to eagerly load. For example, if you want
+  to eagerly load tracks for those albums:
+
+    Artist.eager(:albums=>{proc{|ds| ds.where{id > min}}=>:tracks})
+
+* Sequel also now allows dynamic customization for regular
+  association loading.  Previously, this was possible by using the
+  association's dataset:
+
+    albums = artist.albums_dataset.filter{id > min}
+
+  However, then there was no handling of caching, callbacks, or
+  reciprocals.  For example:
+
+    albums.each{|album| album.artist}
+    
+  Would issue one query per album to get the artist, because the
+  reciprocal association was not set.  Now you can provide a
+  block to the association method:
+  
+    albums = artist.albums{|ds| ds.filter{id > min}}
+    
+  This block is called with the dataset used to retrieve the
+  associated objects, and should return a modified version of that
+  dataset.
+  
+  Note that ruby 1.8.6 doesn't allow blocks to take block arguments,
+  so you have to pass the block as a separate proc argument to the
+  association method if you are still using 1.8.6.
+
+* Sequel now supports filtering by associations.  This wasn't
+  previously supported as filtering is a dataset level feature and
+  associations are a model level feature, and datasets do not depend
+  on models.  Now, model datasets have the ability to filter by
+  associations.  For example, to get all albums for a given artist,
+  you could do:
+  
+    artist = Artist[1]
+    Album.filter(:artist=>artist)
+    
+  Since the above can also be accomplished with:
+  
+    artist.albums
+    
+  this may not seem like a big improvement, but it allows you to
+  filter on multiple associations simultaneously:
+  
+    Album.filter(:artist=>artist, :publisher=>publisher)
+    
+  For simple many_to_one associations, the above is just a simpler
+  way to do:
+  
+    Album.filter(:artist_id=>artist.id, :publisher_id=>publisher.id)
+    
+  Sequel supports this for all association types, including
+  many_to_many and many_through_many, where a subquery is used, and
+  it also works when composite key associations are used:
+  
+    Album.filter(:artist=>artist, :tags=>tag)
+    
+  This will give you the albums for that artist that are also tagged
+  with that tag.  To provide multiple values for the same
+  association, mostly useful for many_to_many associations, you can
+  either use separate filter calls or specify the conditions as an
+  array:
+  
+    Album.filter(:tags=>tag1).filter(:tags=>tag2)
+    Album.filter([[:tags, tag1], [:tags, tag2]])
+
+* A columns_introspection extension has been added that makes
+  datasets attempt to guess their columns in some cases instead of
+  issuing a database query.  This can improve performance in cases
+  where the columns are needed implicitly, such as graphing.  After
+  loading the extension, you can enable the support for specific
+  datasets by extending them with Sequel::ColumnIntrospection.  To
+  enable introspection for all datasets, use:
+  
+    Sequel::Dataset.introspect_all_columns
+
+* A serialization_modification_detection plugin has been added.
+  Previously, Sequel could not detect modifications made to
+  serialized objects.  It could detect modification if you assigned
+  a new value:
+  
+    model.hash_column = model.hash_column.merge(:foo=>:bar)
+    
+  but not if you just modified the object directly:
+  
+    model.hash_columns[:foo] = :bar
+    
+  With this plugin, such modifications can be detected, at a
+  potentially significant performance cost.
+
+= Other Improvements
+
+* When using a migration directory containing both older integer
+  migrations and newer timestamp migrations, where some integer
+  migrations have not been applied, make sure to apply the remaining
+  integer migrations before the timestamp migrations.  Previously,
+  they could be applied out of order due to a lexicographic sort
+  being used instead of a numeric sort.
+
+* If a model does not select all columns from its table, the
+  insert_select optimization is no longer used.  Previously,
+  creating a new model object for such a model could result in the
+  object containing columns that the model does not select.
+
+* You can now use :select=>[] as an option for many_to_many
+  associations to select all columns from both the associated
+  table and the join table.  Previously, this raised an error and
+  required you do :select=>'*'.lit as a workaround.  The default
+  remains to select all columns in the associated table and none
+  from the join table.
+
+* The xml_serializer plugin now handles namespaced models by
+  using __ instead of / as the namespace separator.  Previously, /
+  was used and caused problems as it is not valid XML.
+  
+* The :eager_grapher association option can now accept a proc that
+  takes a single hash of options instead of a fixed 3 arguments.
+  This is the recommended way going forward of writing custom
+  :eager_graphers, and all of the internal ones have been converted.
+  The previous way of using 3 arguments is still supported.
+  
+* A bug in the identity_map plugin for many_to_one associations
+  without full association reflection information has been fixed.
+
+* Sequel is now using GitHub Issues for issue tracking.  Old issues
+  have been migrated from Google Code.
+
+= Backwards Compatibility
+
+* The filter by associations support breaks backward compatibilty for
+  users who previously added an sql_literal instance method to
+  Sequel::Model.  Usually, that was done to for reasons similar to
+  but inferior than the filter by association support.  The following
+  code can be used as a temporary workaround until you can modify
+  your program to use the new filter by associations support:
+  
+    Sequel::Model::Associations::DatasetMethods.
+      send(:remove_method, :complex_expression_sql)
+
+* The private Sequel::Model#_load_associated_objects method now takes
+  an additional, optional options hash.  Plugins that override that
+  method need to be modified.