sequel 2.10.0 → 2.11.0

data/doc/release_notes/2.11.0.txt

@@ -0,0 +1,215 @@
+Optimizations
+-------------
+
+* Model.[] was optimized to use static SQL in cases where doing so
+  should result in the same output.  This should result in a 30-40%
+  performance increase.  Since this can be the most significant or
+  only method call in a web application action, this has potential
+  to significantly enhance the performance of web application code.
+  
+  In order for this optimization to have an effect, you need to
+  make sure that you are calling set_dataset with a Symbol and
+  not a Dataset object:
+  
+    # Optimized:
+    class Foo < Sequel::Model; end
+    class Foo < Sequel::Model(:foos); end
+    class Foo < Sequel::Model
+      set_dataset :foos
+    end
+    
+    # Not Optimized, but otherwise equivalent:
+    class Foo < Sequel::Model(Model.db[:foos]); end
+    class Foo < Sequel::Model
+      set_dataset db[:foos]
+    end
+  
+* Dataset#literal was refactored for performance reasons to make
+  overriding it in subclasses unnecessary.  The changes made result
+  in a 20-25% performance increase.  Sequel can spend about 10% of
+  it's time in Dataset#literal, so this may be only a 2% overall
+  performance improvement.
+
+New Features
+------------
+
+* Association datasets now know about the model objects that created
+  them, as well as the related association reflection.  This makes
+  association extensions much more powerful.  For example, you can
+  now create generic association extensions such as:
+  
+    module FindOrCreate
+      def find_or_create(vals)
+        first(vals) || association_reflection.associated_class. \
+         create(vals.merge(association_reflection[:key]=> \
+           model_object.id))
+      end
+    end
+    
+  The above will work for any standard one_to_many association:
+  
+    Artist.one_to_many :albums, :extend=>FindOrCreate
+    # Create an album named Foo related to this artist,
+    # unless such an album already exists
+    Artist.first.albums_dataset.find_or_create(:name=>'Foo')
+    
+  Before, the only way to do the above was to use a closure inside
+  the :dataset option proc, which couldn't be done generically
+  for multiple associations.
+  
+* A :conditions association option was added, which allows simple
+  filters to be set up without defining :graph_conditions and
+  an association block:
+  
+    # 2.10.0
+    one_to_many(:japanese_verses, :class=>:Verse, \
+     :graph_conditions=>{:languageid=>3})do |ds|
+       ds.filter(:languageid=>3)
+    end
+    # 2.11.0
+    one_to_many(:japanese_verses, :class=>:Verse, \
+       :conditions=>{:languageid=>3})
+
+* A :clone association option was added, which allows you to clone
+  an existing association.  This is most useful when you are dealing
+  with a legacy schema and had to define the same options redundantly
+  for each type of association. You can now do:
+  
+    many_to_many :deputies, :class=>:Employee, \
+     :join_table=>:employeecurrentaudits, :left_key=>:currentauditid, \
+     :right_key=>:employeeid, :order=>[:firstname, :lastname] do |ds|
+      ds.filter(:active).filter(:capacity=>1)
+    end
+    many_to_many :project_managers, :clone=>:deputies do |ds|
+      ds.filter(:active).filter(:capacity=>2)
+    end
+    many_to_many :team_leaders, :clone=>:deputies do |ds|
+      ds.filter(:active).filter(:capacity=>3)
+    end
+    
+  All of the above would use the same :class, :join_table, :left_key,
+  :right_key, and :order options.  If you don't provide an
+  association block, but you are cloning an association that has one,
+  the cloned association's block is used.  You can use the
+  :block=>nil option to not use a block even if the cloned
+  association has a block.
+
+* Dataset#select, #select_more, #order, #order_more, and #get all
+  take a block that yields a Sequel::SQL::VirtualRow instance,
+  similar to the behavior of filter. This allows for the easier
+  use of SQL functions on Ruby 1.9:
+  
+    # 2.10.0
+    dataset.select(:prettify.sql_function(:name))
+    # 2.11.0
+    dataset.select{|o| o.prettify(:name)}
+
+* String#lit can now accept arguments and return an SQL literal
+  string.  This allows you to do things that were previously hard
+  or at least unnecessarily verbose.  For example, you can now
+  easily use the SQL standard SUBSTRING function:
+  
+    column = :user
+    pattern = params[:pattern]
+    dataset.select{|o| o.substring('? from ?'.lit(column, pattern))}
+    
+* A validates_inclusion_of validation method was added to Model. You
+  can provide a Range or an Array in the :in option to specify the
+  allowed values:
+  
+    validates_inclusion_of :value, :in=>1..5
+    validates_inclusion_of :weekday, :in=>%w'Monday Tuesday ...'
+
+* Dataset#with_sql was added, which returns a copy of the dataset
+  with static SQL.  This is useful if you want to keep the same
+  row_proc/graph/transform/etc., but want to use your own custom
+  SQL.
+
+Other Improvements
+------------------
+
+* You can now use Sequel's database independent types when casting:
+
+    dataset.select(:number.cast(String))
+  
+  Among other things, the default cast types for cast_string and
+  cast_numeric now work in the MySQL adapter.
+
+* Model#set_associated_object was added.  The many_to_one association
+  setter method calls it.  This allows you to easily override the
+  association setters for all many_to_one associations of a class
+  by modifying a single method. 
+  
+* Typecasting invalid date strings now raises a
+  Sequel::Error::InvalidValue instead of an argument error, which
+  means that you can use raise_on_typecast_failure = false and not
+  have an error raised when an invalid date format is used.
+  
+* String#to_sequel_blob was added and should now be used instead
+  of String#to_blob.  sqlite3-ruby defines String#to_blob
+  differently, which could cause problems.
+  
+* Blob columns are now fully supported in the SQLite adapter, with
+  the hex escape syntax being used for input, and returning columns
+  of type Sequel::SQL::Blob on output.
+  
+* The SQLite adapter drop_column support is now significantly more
+  robust.
+  
+* The SQLite adapter now supports rename_column.
+  
+* The MySQL adapter now supports stored procedures with multiple
+  arguments.
+  
+* The MySQL adapter can now not use a compressed connection to the
+  server via the :compress=>false option.
+  
+* The MySQL adapter now sets a default timeout of 30 days to the
+  database connection, you can change it via the :timeout option,
+  which accepts a number of seconds.
+  
+* The MySQL adapter now sets SQL_AUTO_IS_NULL to false by default,
+  you can use the :auto_is_null=>true option to not do this.
+  
+* The MySQL adapter now sets the encoding option on the database
+  connection itself, so it works across reconnects.
+
+* Sequel itself no longer uses String#lit or Symbol#* internally, so
+  it shouldn't break if another library defines them.
+
+* The default index name is now generated correctly if a non-String
+  or Symbol column is used.
+  
+* Some ruby -w warnings have been fixed.
+
+* INSERTs are now sent to the master database instead of the slave
+  database(s) if using a master/slave database configuration and
+  PostgreSQL 8.2+ or Firebird.
+  
+* DateTime literalization has been fixed in the Firebird adapter.
+  
+* Date literalization has been fixed in the H2 JDBC subadapter.
+  
+* Release notes for versions from 1.0 to the present are now included
+  in the Sequel repository and the RDoc documentation, see
+  http://sequel.rubyforge.org/rdoc/files/doc/release_notes/
+
+Backwards Compatibilty
+----------------------
+
+* The optimization of Model.[] may break if you modify the model's
+  dataset behind its back.  Always use Model.set_dataset if you
+  want to change a Model's dataset.
+  
+* Sequel::Dataset::UnsupportedExceptIntersect and
+  Sequel::Dataset::UnsupportedExceptIntersectAll will now only be
+  defined if you are using an adapter that requires them.
+  
+* The private Model#cache_delete_unless_new method has been removed.
+
+* Sequel::SQL::IrregularFunction was removed, as it was a bad hack
+  that is not used by Sequel anymore.  Unless you were instantiating
+  it directly or using a plugin/extension that did, this shouldn't
+  affect you.  Using a Sequel::SQL::Function with a 
+  Sequel::SQL::PlaceholderLiteralString is recommended instead, see
+  the substring example above.

data/doc/release_notes/2.2.0.txt

@@ -0,0 +1,253 @@
+The Most Powerful and Flexible Associations of Any Ruby ORM
+-----------------------------------------------------------
+
+Sequel can now support any association type supported by
+ActiveRecord, and many association types ActiveRecord doesn't
+support.
+
+Association callbacks (:before_add, :after_add, :before_remove,
+:after_remove) have been added, and work for all association
+types.  Each of the callback options can be a Symbol specifying an
+instance method that takes one argument (the associated object), or a
+Proc that takes two arguments (the current object and the associated
+object), or an array of Symbols and Procs.  Additionally, an
+:after_load callback is available, which is running after loading the
+associated record(s) from the database.
+
+Association extensions are now supported:
+
+  class FindOrCreate
+    def find_or_create(vals)
+      first(vals) || create(vals)
+    end
+  end
+  class Author < Sequel::Model
+    one_to_many :authorships, :extend=>FindOrCreate
+  end
+  Author.first.authorships_dataset.find_or_create(:name=>'Bob')
+
+Sequel has been able to support most has_many :through style
+associations since 1.3, via many_to_many (since it doesn't break on
+join tables that are also model tables, unlike ActiveRecord's
+has_and_belongs_to_many).  Now it can also support has_many :through
+style associations where it goes through a has_many association.
+
+Sequel can now support polymorphic associations.  Polymorphic
+associations are really a design flaw, so Sequel doesn't support them
+directly, but the tools that Sequel gives you make them pretty easy
+to implement.
+
+Sequel can also support associations that ActiveRecord does not.  For
+example, a belongs_to association where the column referenced in the
+associated table is not the primary key, an association that depends
+on multiple columns in each table, or even situations where the
+association has a column in the primary table that can be referenced
+by any of multiple columns in a second table that has a has_one style
+association with the table you want to associate with.
+
+Some of those associations can be supported for a single object using
+custom SQL in ActiveRecord, but none are supported when eager
+loading or allow further filtering.
+
+Not only can all of these cases be supported with Sequel::Model, all
+can be supported with eager loading, and can allow for further
+filtering. See
+http://sequel.rubyforge.org/files/sequel/doc/advanced_associations_rdoc.html
+for details and example code for all association types covered above.
+
+There have also been many additional options added for controlling
+eager loading via eager_graph.  Every part of the SQL JOINs can now
+be controlled via one of the options, so you can use JOIN USING,
+NATURAL JOIN, or arbitrary JOIN ON conditions.
+
+Finally, just to show off the power that Sequel gives you when eager
+loading, here is example code that will eagerly load all descendants
+and ancestors in a tree structure, without knowing the depth of the
+tree:
+
+  class Node < Sequel::Model
+    set_schema do
+      primary_key :id
+      foreign_key :parent_id, :nodes
+    end
+    create_table
+
+    many_to_one :parent
+    one_to_many :children, :key=>:parent_id
+
+    # Only useful when eager loading
+    many_to_one :ancestors, :eager_loader=>(proc do |key_hash, nodes,
+associations|
+      # Handle cases where the root node has the same parent_id as
+primary_key
+      # and also when it is NULL
+      non_root_nodes = nodes.reject do |n|
+        if [nil, n.pk].include?(n.parent_id)
+          # Make sure root nodes have their parent association set to
+nil
+          n.associations[:parent] = nil
+          true
+        else
+          false
+        end
+      end
+      unless non_root_nodes.empty?
+        id_map = {}
+        # Create an map of parent_ids to nodes that have that parent id
+        non_root_nodes.each{|n| (id_map[n.parent_id] ||= []) << n}
+        # Doesn't cause an infinte loop, because when only the root node
+        # is left, this is not called.
+        Node.filter(Node.primary_key=>id_map.keys).eager(:ancestors).all
+do |node|
+          # Populate the parent association for each node
+          id_map[node.pk].each{|n| n.associations[:parent] = node}
+        end
+      end
+    end)
+    many_to_one :descendants, :eager_loader=>(proc do |key_hash, nodes,
+associations|
+      id_map = {}
+      nodes.each do |n|
+        # Initialize an empty array of child associations for each
+parent node
+        n.associations[:children] = []
+        # Populate identity map of nodes
+        id_map[n.pk] = n
+      end
+      # Doesn't cause an infinite loop, because the :eager_loader is not
+called
+      # if no records are returned.  Exclude id = parent_id to avoid
+infinite loop
+      # if the root note is one of the returned records and it has
+parent_id = id
+      # instead of parent_id = NULL.
+      Node.filter(:parent_id=>id_map.keys).exclude(:id=>:parent_id).eager(:descendants).all
+do |node|
+        # Get the parent from the identity map
+        parent = id_map[node.parent_id]
+        # Set the child's parent association to the parent
+        node.associations[:parent] = parent
+        # Add the child association to the array of children in the
+parent
+        parent.associations[:children] << node
+      end
+    end)
+  end
+
+  nodes = Node.filter(:id < 10).eager(:ancestors, :descendants).all
+
+New Adapter Features
+--------------------
+
+* PostgreSQL bytea fields are now fully supported.
+
+* The PostgreSQL adapter now uses the safer connection-specific
+  string escaping if you are using ruby-pg.
+
+* The SQLite adapter supports drop_column and add_index.
+
+* You can now use URL parameters in the connection string, enabling
+  you to connect to PostgreSQL via a socket using
+  postgres://user:password@blah/database?host=/tmp
+
+Other New Features
+------------------
+
+* Dataset#graph now takes a block which it passes to join_table.
+
+* Symbol#identifier has been added, which can be used if another
+  library defines the same operator(s) on Symbol that Sequel defines.
+
+* Filter blocks now yield a VirtualRow instance, which can yield
+  Identifiers, QualifiedIdentifiers, or Functions.  Like
+  Symbol#identifier, this is useful if another library defines the
+  same operator(s) on Symbol that Sequel defines.
+
+* You can now call Model.to_hash to get an identity map for all
+  rows (before this required Model.dataset.to_hash).
+
+* A model that can get it's column information from the schema will
+  set it in the dataset, potentially saving many queries.
+
+* Model.validates_presence_of now works correctly for boolean
+  columns.
+
+Notable Bug Fixes
+-----------------
+
+* Caching now works with Model subclasses.
+
+* Model validation methods now work with source reloading.
+
+* The PostgreSQL adapter no longer raises an Error if you try to
+  insert a record with the primary key already specified.
+
+* Sequel no longer messes with the native MySQL adapter, so you can
+  use Sequel and ActiveRecord with MySQL in the same process.
+
+* Dataset#count now works correctly for limited dataset.
+
+* PostgreSQL Database#transaction method yields a connection, similar
+  to the other adapters.
+
+* Using a hash argument in #distinct, #order, or #group is treated
+  as an expression instead of a column alias.
+
+* Cloned datasets no longer ignore the existing columns unless it is
+  necessary.
+
+* The :quote_identifiers and :single_threaded Database options now
+  work correctly.
+
+Backwards Incompatible Changes
+------------------------------
+
+* ParseTree support, deprecated in 2.1.0, has been removed in 2.2.0.
+  You should use the expression filter syntax instead, perferably
+  without the block (though it can be used inside a block as well).
+  This usually involves the following types of changes:
+
+    filter{:x == :y} => filter(:x => :y)
+    filter{:x << :y} => filter(:x => :y)
+    filter{:x && :y} => filter(:x & :y) # Don't forget about change
+    filter{:x || :y} => filter(:x | :y) #  in operator precedence
+    filter{:x.like?('%blah%')} => filter(:x.like('%blah%'))
+    filter do => filter((:x > 1) & (:y < 2))
+      :x > 1
+      :y < 2
+    end
+
+* Attempts to save an invalid Model instance will raise an error by
+  default.  To revert to returning a nil value, use:
+
+    Sequel::Model.raise_on_save_failure = false # Global
+    Album.raise_on_save_failure = false # Class
+    album = Album.new
+    album.raise_on_save_failure = false # Instance
+
+  Note that before, save would return false where now it returns nil
+  if you disable raising on save failure.
+
+* Dataset#update no longer takes a block, as it's use of the block
+  depended on ParseTree.  With the introduction of the expression
+  syntax in 2.0.0, it's no longer necessary.  You should use a hash
+  with an expression as the value instead:
+
+    DB[:table].update(:column=>:column + 1)
+
+* validates_presence of now considers false as present instead of
+  absent.  This is so it works with boolean columns.
+
+* Dataset#graph ignores any previously selected columns when it is
+  called for the first time.
+
+* Dataset#columns ignores any filtering, ordering, or distinct
+  clauses.  This shouldn't cause issues unless you were using
+  SQL functions with side effects and expecting them to be called
+  when columns was called (unlikely at best).
+
+One significant point of note is that the 2.2.0 release will be the
+last release with both a sequel_core and sequel gem.  Starting
+with 2.3.0 they will be combined into one sequel gem.  You will still
+be able to get just the sequel_core part by requiring 'sequel_core',
+but they will be packaged together.