sequel 4.2.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cab63d0878683dcadae2a2192c6969b1afd46a8d
-  data.tar.gz: c06204a0ba11736b055e57e109b7d8886014dd8e
+  metadata.gz: b5cf40a4c3d9c93b6ed7fa958db814a768fbc322
+  data.tar.gz: 06fb6c46cdf9af739fe547de06aedb598b46b11e
 SHA512:
-  metadata.gz: 03ea44b1eb6d126258b335e3e28935506360c8d1e2e54c773d26b9f5e795b71f6f8c27eb04ad1fe6dd0deb32d86c42b88ac11b6e9356b735dc54b791310e16d8
-  data.tar.gz: 7d4084003d7202c8507ae31746f0e941a23a187edd8f479b22994a100283b5671982ab877aa4cb72029a846a899e8e356be0f14c7161361994913963547de1a6
+  metadata.gz: 1d05bce34cc981ada0a4429d9cfbb861f8ad52b9fe83ae604f3ea0395f27deffe766e865d4a57e5ebd791df799215570f945b488fd6e7a317bd6b9f5d821e3bd
+  data.tar.gz: 7bd18b9518488d92f7b45024d93ae31b0b497580e681f65cbc1ee2f1a914f1c4f69a250fd1e4759ddcd37004a6ce4c4125f81cd61b11bf51428652bd7d97fefb

data/CHANGELOG

@@ -1,3 +1,31 @@
+=== 4.3.0 (2013-10-02)
+
+* Fix literalization of empty blobs on MySQL (jeremyevans) (#715)
+
+* Ensure Dataset#page_count in pagination extension is at least one (jeremyevans) (#714)
+
+* Recognize another disconnect error in the jdbc/as400 adapter (jeremyevans)
+
+* Make Dataset#qualify and Sequel.delay work together (jeremyevans)
+
+* Recognize citext type as string on PostgreSQL (isc) (#710)
+
+* Support composite keys in the rcte_tree plugin (jeremyevans)
+
+* Support composite keys in the tree plugin (jeremyevans)
+
+* Make Migrator.migrator_class public (robertjpayne, jeremyevans) (#708)
+
+* Make PostgreSQL empty array literalization work correctly on PostgreSQL <8.4 (jeremyevans)
+
+* Add Sequel extensions guide (jeremyevans)
+
+* Add model plugins guide (jeremyevans)
+
+* Add error_sql Database extension, allowing DatabaseError#sql to return SQL query that caused underlying exception (jeremyevans)
+
+* Make Dataset#each_page in pagination extension return enumerator if no block is given (justinj) (#702)
+
 === 4.2.0 (2013-09-01)
 
 * Support custom :flags option in mysql2 adapter (jeremyevans) (#700)

data/doc/extensions.rdoc

@@ -0,0 +1,84 @@
+= Sequel Extensions
+
+Sequel has an official extension system, for adding global, Database, and Dataset extensions.
+
+== Global Extensions
+
+Global extensions can add or modify the behavior of any part of Sequel.  Technically, they are not limited to affecting Sequel, as they can also modify code outside of Sequel (e.g. the blank extension).  However, extensions that modify things outside of Sequel generally do so only for backwards compatibility.
+
+Global extensions are loaded via <tt>Sequel.extension</tt>:
+
+  Sequel.extension :named_timezones
+
+What this does is require the relevent extension from <tt>sequel/extensions/named_timezones</tt> somewhere in the ruby path.  Actually, that is all that does.  Global extensions are just a simpler, consistent way to require code that modifies Sequel.
+
+== Database Extensions
+
+Database extensions should add or modify the behavior of a single <tt>Sequel::Database</tt> instance.  They are loaded via <tt>Sequel::Database#extension</tt>:
+
+  DB.extension :server_block
+
+The first thing that this does is load the relevent extension globally.  However, Database extensions should be structured in a way that loading the relevent extension globally just adds a module with the related behavior, it doesn't modify any other state.  After loading the extension globally, it modifies the related <tt>Sequel::Database</tt> object to modify it's behavior, usually by extending it with a module.
+
+If you want a Database extension loaded into all future Database instances, you can use <tt>Sequel::Database.extension</tt>:
+
+  Sequel::Database.extension :server_block
+
+All future <tt>Sequel::Database</tt> instances created afterward will then automatically have the server_block extension loaded.
+
+== Dataset Extensions
+
+Dataset extensions should add or modify the behavior of a single <tt>Sequel::Dataset</tt> instance.  They are loaded via <tt>Sequel::Dataset#extension</tt> or <tt>Sequel::Dataset#extension!</tt>.  <tt>Sequel::Dataset#extension</tt> returns a modifies copy of the dataset that includes the extension (similar to how most dataset query methods work):
+
+  ds = DB[:a].extension(:columns_introspection)
+
+<tt>Sequel::Dataset#extension!</tt> modifies a dataset to include the extension (similar to how dataset mutation methods work):
+  
+  ds = DB[:a]
+  ds.extension!(:columns_introspection)
+
+It is recommended you only use <tt>Sequel::Dataset#extension!</tt> if you have good reasons to.
+
+The first thing loading a Dataset extension does is load the relevent extension globally.  Similar to Database extensions, loading a Dataset extension globally should not affect state other than maybe adding a module.  After loading the extension globally, it modifies the related <tt>Sequel::Dataset</tt> instance to modify its behavior.
+
+If you want to load an extension into all future datasets for a given <tt>Sequel::Database</tt> instance, you can also load it as a Database extension:
+
+  DB.extension :columns_introspection
+
+Likewise, if you want to load an extension into all future datasets for all future databases, you can load it via <tt>Sequel::Database.extension</tt>:
+
+  Sequel::Database.extension :columns_introspection
+  
+== Creating Global Extensions
+
+If you want to create a global extension, you just need to store your code so that you can require it via <tt>sequel/extensions/extension_name</tt>.  Then users can load it via:
+
+  Sequel.extension :extension_name
+
+It is recommended you only create a global extension if what you want to do would not work as a Database or Dataset extension.
+
+== Creating Database Extensions
+
+Creating Database extensions is similar to global extensions in terms of creating the file.  However, somewhere in the file, you need to call <tt>Sequel::Database.register_extension</tt>.  Usually you would call this with the module that will be added to the related <tt>Sequel::Database</tt> instance when the extension is loaded.  For example, the server_block extension uses something like:
+
+  Sequel::Database.register_extension(:server_block, Sequel::ServerBlock)
+
+The first argument is the name of the extension as a symbol, and the second is the module.
+
+In some cases, just extending the <tt>Sequel::Database</tt> instance with a module is not sufficient.  So <tt>Sequel::Database.register_extension</tt> also accepts a proc instead of a second argument.  This proc is called with the <tt>Sequel::Database</tt> instance, and can then run any related code:
+
+  Sequel::Database.register_extension(:arbitrary_servers){|db| db.pool.extend(Sequel::ArbitraryServers)}
+
+== Creating Dataset Extensions
+
+Creating Dataset extensions is very similar to creating Database extensions, but instead of calling <tt>Sequel::Database.register_extension</tt>, you call <tt>Sequel::Dataset.register_extension</tt>.  In general, you would call this with the module that will be added to the related <tt>Sequel::Dataset</tt> instance when the extension is loaded.  For example, the columns_introspection extension uses something like:
+
+  Sequel::Dataset.register_extension(:columns_introspection, Sequel::ColumnsIntrospection)
+
+The first argument is the name of the extension as a symbol, and the second is the module.  When you call the <tt>Sequel::Dataset.register_extension</tt> method with a module, it in turn calls <tt>Sequel::Database.register_extension</tt> and adds a Database extension that loads this Dataset extension into all future Datasets created from the Database.
+
+You can also call <tt>Sequel::Dataset.register_extension</tt> with a proc:
+
+  Sequel::Dataset.register_extension(:extension_name){|ds| ...}
+
+Note that if you use a proc, a corresponding Database extension will not be created automatically (you can still call <tt>Sequel::Database.register_extension</tt> manually in this case).

data/doc/model_plugins.rdoc

@@ -0,0 +1,270 @@
+= Model Plugins
+
+Sequel::Model (and Sequel in general) is designed around the idea of a small core, to which application-specific behavior can easily be added.  Sequel::Model implements this design using a plugin system.  Plugins are modules that include submodules for model class methods, model instance methods, and model dataset methods.  All plugins can override the class, instance, and dataset methods added by earlier plugins, and call super to get the behavior before the plugin was added.
+
+== Default Plugins
+
+The Sequel::Model class is completely empty by default, in that it has no class methods or instance methods.  Sequel::Model is itself a plugin, and it is the first plugin loaded, and it is loaded into itself (meta!).  So methods in Sequel::Model::ClassMethods become Sequel::Model class methods, methods in Sequel::Model::InstanceMethods become Sequel::Model instance methods, and methods in Sequel::Model::DatasetMethods become Sequel::Model dataset methods. The Sequel::Model plugin is often referred to as the base plugin. 
+
+By default, the Sequel::Model class also has the Sequel::Model::Associations plugin loaded by default, though it is possible to disable this. 
+
+== Loading Plugins
+
+Loading a plugin into a model class is generally as simple as calling the Sequel::Model.plugin method with the name of the plugin, for example:
+
+  Sequel::Model.plugin :subclasses
+
+What is does is require the <tt>sequel/plugins/subclasses</tt> file, and then assumes that that file defines the <tt>Sequel::Plugins::Subclasses</tt> plugin module.
+
+It's possible to pass module instances to the plugin method to load plugins that are stored in arbitrary files or namespaces:
+
+  Sequel::Model.plugin MyApp::Plugins::Foo
+
+In the examples shown above, the plugin is loaded into Sequel::Model, which means it is loaded into all subclasses that are created afterward.  With many plugins, you are not going to want to add them to Sequel::Model, but to a specific subclass:
+
+  class Node < Sequel::Model
+    plugin :tree
+  end
+
+Doing this, only Node and future subclasses of Node will have the tree plugin loaded.
+
+== Plugin Arguments/Options
+
+Some plugins require arguments and/or support options.  For example, the single_table_inheritance plugin requires an argument containing the column that specifies the class to use, and options:
+
+  class Employee < Sequel::Model
+    plugin :single_table_inheritance, :type_id, :model_map=>{1=>:Staff, 2=>:Manager}
+  end
+
+You should read the documentation for the plugin to determine if it requires arguments and what if any options are supported.
+
+== Creating Plugins
+
+The simplest possible plugin is an empty module in a file stored in <tt>sequel/plugins/plugin_name</tt> somewhere in ruby's load path:
+
+  module Sequel
+    module Plugins
+      module PluginName
+      end
+    end
+  end
+
+Well, technically, that's not the simplest possible plugin, but it is the simplest one you can load by name.  The absolute simplest plugin would be an empty module:
+
+  Sequel::Model.plugin Module.new
+
+== Example Formatting
+
+In general, loading plugins by module instead of by name is not recommended, so this guide will assume that plugins are loaded by name.  For simplicity, we'll also use the following format for example plugin code (and assume a plugin named Foo stored in <tt>sequel/plugins/foo</tt>):
+
+  module Sequel::Plugins::Foo
+  end
+
+This saves 4 lines per example.  However, it's recommended that you use the nested example displayed earlier for production code.
+
+The examples also assume that the following model class exists:
+
+  class Bar < Sequel::Model
+  end
+
+== Adding Class Methods
+
+If you want your plugin to add class methods to the model class it is loaded into, define a ClassMethods module under the plugin module:
+
+  module Sequel::Plugins::Foo
+    module ClassMethods
+      def a
+        1
+      end
+    end
+  end
+
+This allows a plugin user to do:
+
+  Bar.plugin :foo
+  Bar.a # => 1
+
+== Adding Instance Methods
+
+If you want your plugin to add instance methods to the model class it is loaded into, define an InstanceMethods module under the plugin module:
+
+  module Sequel::Plugins::Foo
+    module InstanceMethods
+      def a
+        1
+      end
+    end
+  end
+
+This allows a plugin user to do:
+
+  Bar.plugin :foo
+  Bar.new.a # => 1
+
+== Adding Dataset Methods
+
+If you want your plugin to add methods to the dataset of the model class it is loaded into, define a DatasetMethods module under the plugin module:
+
+  module Sequel::Plugins::Foo
+    module DatasetMethods
+      def a
+        1
+      end
+    end
+  end
+
+This allows a plugin user to do:
+
+  Bar.plugin :foo
+  Bar.dataset.a # => 1
+
+== Calling super to get Previous Behavior
+
+No matter if you are dealing with class, instance, or dataset methods, you can call super inside the method to get the previous behavior.  This makes it easy to hook into the method, add your own behavior, but still (optionally?) get the previous behavior:
+
+  module Sequel::Plugins::Foo
+    module InstanceMethods
+      def save
+        if allow_saving?
+          super
+        else
+          raise Sequel::Error, 'saving not allowed for this object'
+        end
+      end
+
+      private
+
+      def allow_saving?
+        `pom` =~ /Waxing/
+      end
+    end
+  end
+
+== Running Code When the Plugin is Loaded
+
+Some plugins require more than just adding methods.  Any plugin that requires state is going to have to initialize that state and store it somewhere.  If you want to run code when a plugin is loaded (usually to initialize state, but possibly for other reasons), there are two methods you can define to do so.  The first method is apply, and it is called only the first time the plugin is loaded into the class, before it is loaded into the class.  This is generally only used if a plugin depends on another plugin or for initializing state.  You define this method as a singleton method of the plugin module:
+
+  module Sequel::Plugins::Foo
+    def self.apply(model)
+      model.instance_eval do
+        plugin :plugin_that_foo_depends_on
+        @foo_states = {}
+      end
+    end
+  end
+
+The other method is called configure, and it is called everytime the plugin is loaded into the class, after it is loaded into the class:
+
+  module Sequel::Plugins::Foo
+    def self.configure(model)
+      model.instance_eval do
+        @foo_state[:initial] = :baz
+      end
+    end
+  end
+
+Note that in the configure method, you know apply has already been called at least once (so @foo_state will definitely exist).
+
+If you want your plugin to take arguments and/or support options, you handle that by making your apply and configure methods take arguments and/or an options hash.  For example, if you want the user to be able to set the initial state via an option, you can do:
+
+  module Sequel::Plugins::Foo
+    def self.apply(model, opts={})
+      model.instance_eval do
+        plugin :plugin_foo_depends_on
+        @foo_states = {}
+      end
+    end
+
+    def self.configure(model, opts={})
+      model.instance_eval do
+        @foo_state[:initial] = opts[:initial_state] || :baz
+      end
+    end
+  end
+
+This allows a user of the plugin to do either of the following
+
+  Bar.plugin :foo
+  Bar.plugin :foo, :initial_state=>:quux
+
+If you want to require the initial state to be provided as an argument:
+
+  module Sequel::Plugins::Foo
+    def self.apply(model, initial_state)
+      model.instance_eval do
+        plugin :plugin_foo_depends_on
+        @foo_states = {}
+      end
+    end
+
+    def self.configure(model, initial_state)
+      model.instance_eval do
+        @foo_state[:initial] = initial_state
+      end
+    end
+  end
+
+This requires that the user of the plugin specify the argument:
+
+  Bar.plugin :foo, :quux
+
+In general you should only require plugin arguments if you absolutely must have a value and there is no good default.
+
+== Handling Subclasses
+
+Sequel::Model uses a copy-on-subclassing approach to model state.  So instead of model subclasses asking their parent class for a value if they don't have it defined, the value is automatically copied from the parent class to the subclass when the subclass is created.  While you can do this by overriding the inherited class method, there is a available shortcut that handles most cases:
+
+  module Sequel::Plugins::Foo
+    module ClassMethods
+      Sequel::Plugins.inherited_instance_variables(self, :@foo_state=>:dup)
+    end
+  end
+
+Inside the ClassMethods submodule, you call the Sequel::Plugins.inherited_instance_variables method with the first argument being self.  The second argument should be a hash describing how to copy the value from the parent class into the subclass.  The keys of this hash are instance variable names, including the @ symbol (e.g. :@foo_state).  The values of this hash describe how to copy it:
+
+nil :: Use the value directly.
+:dup :: Call dup on the value.
+:hash_dup :: Create a new hash with the same keys, but a dup of all the values.
+Proc :: An arbitrary proc that is called with the parent class value and should return the value to set into the subclass.
+
+== Handling Changes to the Model's Dataset
+
+In many plugins, if the model class changes the dataset, you need to change the state for the plugin.  While you can do this by overriding the set_dataset class method, there is an available shortcut:
+
+  module Sequel::Plugins::Foo
+    module ClassMethods
+      Sequel::Plugins.after_set_dataset(self, :set_foo_table)
+      
+      private
+
+      def set_foo_table
+        @foo_state[:table] = table_name
+      end
+    end
+  end
+
+With this code, any time the model's dataset changes, the state of the plugin will be updated to set the correct table name.
+
+== Making Dataset Methods Callable as Class Methods
+
+In some cases, when dataset methods are added, you want to also create a model class method that will call the dataset method, so you can write:
+
+  Model.method
+
+instead of:
+
+  Model.dataset.method
+
+There is an available shortcut that automatically creates the class methods:
+
+  module Sequel::Plugins::Foo
+    module ClassMethods
+      Sequel::Plugins.def_dataset_methods(self, :quux)
+    end
+
+    module DatasetMethods
+      def quux
+        2
+      end
+    end
+  end

data/doc/release_notes/4.3.0.txt

@@ -0,0 +1,40 @@
+= New Features
+
+* The tree and rcte_tree plugins now support composite keys.
+
+* An error_sql Database extension has been added.  This extension
+  adds the DatabaseError#sql method, which should return the
+  database query that caused the error.  This is useful for
+  drivers that don't include the SQL used as part of the error
+  message.
+
+= Other Improvements
+
+* Empty blobs are now literalized correctly on MySQL.
+
+* Empty arrays are now literalized correctly on PostgreSQL <8.4.
+
+* In the pagination extension, Dataset#page_count is now 1 even if
+  the dataset is empty.  This fixes issues with last_page? and
+  page_range returning bad values for empty datasets.
+
+* In the pagination extension, calling Dataset#each_page without a
+  block now returns an Enumerator.
+
+* Dataset#qualify and Sequel.delay now work together, qualifying
+  the object returned by the delayed evaluation.
+
+* Migrator.migrator_class is now a public method.
+
+* The PostgreSQL citext type is now recognized as a string.
+
+* Another disconnect error is now recognized in the jdbc/as400
+  adapter.
+
+* Guides about using and creating Sequel extensions and model
+  plugins have been added.
+
+= Backwards Compatibility
+
+* If you were expecting Dataset#page_count on a empty paginated
+  dataset to return 0, you need to update your code.

data/doc/testing.rdoc

@@ -163,5 +163,8 @@ The SEQUEL_INTEGRATION_URL environment variable specifies the Database connectio
 === Other
 
 SEQUEL_COLUMNS_INTROSPECTION :: Whether to run the specs with the columns_introspection extension loaded by default
+SEQUEL_CONNECTION_VALIDATOR :: Use the connection validator extension when running the specs
+SEQUEL_ERROR_SQL :: Use the error_sql extension when running the specs
+SEQUEL_NO_CHECK_SQLS :: Don't check for specific SQL syntax when running the specs
 SEQUEL_NO_PENDING :: Don't mark any specs as pending, try running all specs
 SKIPPED_TEST_WARN :: Warn when skipping any tests because libraries aren't available