viking-sequel 3.10.0

data/doc/release_notes/3.10.0.txt

@@ -0,0 +1,286 @@
+New Features
+------------
+
+* A real one_to_one association was added to Sequel, replacing the
+  previous :one_to_one option of the one_to_many association.
+  
+  This is a fully backwards incompatible change, any code that uses
+  the :one_to_one option of one_to_many will be broken in Sequel
+  3.10.0, as that option now raises an exception.  Keeping backwards
+  compatibility was not possible, as even the name of the association
+  needs to be changed.  Here are the code changes you need to make:
+  
+  * The association definition needs to change from one_to_many to
+    one_to_one, with no :one_to_one option, and with the association
+    name changed from the plural form to the singular form:
+    
+      # Before
+      Lyric.one_to_many :songs, :one_to_one=>true
+      # After
+      Lyric.one_to_one :song
+      
+  * All usage of the association when eager loading or when getting
+    reflections need to use the new singular association name:
+    
+      # Before
+      Lyric.eager(:songs).all
+      Lyric.eager_graph(:songs).all
+      Lyric.association_reflection(:songs)
+      # After
+      Lyric.eager(:song).all
+      Lyric.eager_graph(:song).all
+      Lyric.association_reflection(:song)
+      
+  Any Sequel plugins or extensions that deal with the internals of
+  associations need to be made aware of the one_to_one association,
+  and how it is different than one_to_many's previous :one_to_one
+  option.  Here are some internal changes that may affect you:
+  
+  * one_to_one associations are now cached like many_to_one
+    associations instead of like one_to_many associations.  So the
+    cache includes the associated object or nil, instead of an array.
+    Note that this change means that all custom :eager_loader options
+    for one_to_one associations need to change to use this new
+    caching scheme.
+    
+  * The one_to_one association setter method is now handled similarly
+    to the many_to_one setter method, instead of using the internal
+    one_to_many association add method.
+    
+  * Instead of raising an error when multiple rows are returned,
+    one_to_one associations now use limit(1) to only return a single
+    row.
+    
+  There were some other fixes made during these changes:
+  
+  * The one_to_one setter now accepts nil to disassociate the record.
+    Previously, this raised an error.
+    
+  * If the one_to_one association already had a separate object
+    associated, and you assigned a different object in the setter
+    method, Sequel now disassociates the old object before
+    associating the new object, fixing some potential issues if there
+    is a UNIQUE constraint on the foreign key column.
+    
+  * Using the many_to_one association setter where the reciprocal
+    association is a one_to_one association with a currently
+    different cached associated object no longer raises an exception.
+  
+  * The nested_attributes and association_dependencies plugins
+    both now correctly handle one_to_one associations.
+
+  If you need any help migrating, please post on the Sequel Google
+  Group or ask in the #sequel IRC channel.
+
+* Both many_to_one and one_to_one associations now use before_set
+  and after_set callbacks instead of trying to make the one_to_many
+  and many_to_many associations' (before|after)_(add|remove)
+  callbacks work.
+  
+  This change makes the code simpler, makes writing callbacks easier,
+  and no longer requires Sequel to send a query to the database to
+  get the currently associated object in the many_to_one association
+  setter method (you can still do so manually in a before_set
+  callback if you want to).
+  
+* Dataset#for_update was added as a default dataset method.
+  Previously, it was only supported on PostgreSQL.  It has been
+  tested to work on PostgreSQL, MySQL, SQLite (where it is ignored),
+  H2, and MSSQL.
+  
+* Dataset#lock_style was added as a backbone for Dataset#for_update,
+  but allowing you to specify custom lock styles.  These can either
+  be symbols recognized by the adapters, or strings which are treated
+  as literal SQL.
+
+* Model#lock! was added, which uses Dataset#for_update to lock model
+  rows for specific instances.  Combined with the Dataset#for_update,
+  Sequel now has an equivalent to ActiveRecord's pessimistic locking
+  support.
+
+* A composition plugin was added, given similar functionality as
+  ActiveRecord's composed_of.
+  
+  The composition plugin allows you to easily define getter and
+  setter instance methods for a class where the backing data is
+  composed of other getters and decomposed to other setters.
+
+  A simple example of this is when you have a database table with
+  separate columns for year, month, and day, but where you want to
+  deal with Date objects in your ruby code.  This can be handled
+  with:
+
+    Model.composition :date, :mapping=>[:year, :month, :day]
+
+  The :mapping option is optional, but if not used, you need define
+  custom composition and decomposition procs via the :composer and
+  :decomposer options.
+
+  Note that when using the composition object, you should not modify
+  the underlying columns if you are also instantiating the
+  composition, as otherwise the composition object values will
+  override any underlying columns when the object is saved.
+
+* An rcte_tree plugin was added, which uses recursive common table
+  expressions to load all ancestors and descendants in a single
+  query.  If your database supports recursive common table
+  expressions (PostgreSQL 8.4+, MSSQL 2005+, newer versions of
+  Firebird), using recursive common table expressions to load
+  all ancestors and descendants is significantly faster than storing
+  trees as nested sets and using nested set queries.  Usage:
+  
+    Model.plugin :rcte_tree
+   
+    # Lazy loading
+    model = Model.first
+    model.parent
+    model.children
+    model.ancestors # Populates :parent association as well
+    model.descendants # Populates :children association as well
+   
+    # Eager loading - also populates the :parent and children 
+    # associations for all ancestors and descendants
+    Model.filter(:id=>[1, 2]).eager(:ancestors, :descendants).all
+   
+    # Eager loading children and grandchildren
+    Model.filter(:id=>[1, 2]).eager(:descendants=>2).all
+    # Eager loading children, grandchildren, and great grandchildren
+    Model.filter(:id=>[1, 2]).eager(:descendants=>3).all
+
+* Dataset#first_source_table was added, giving you the unaliased
+  version of the table for the first source.
+
+* Add Sequel::BasicObject.remove_methods!, useful on ruby 1.8 if you
+  require other libraries after Sequel that add methods to Object.
+  For example, if YAML is required after sequel, then the following
+  will raise an error:
+  
+    DB[:a].filter{x > y}
+    
+  because YAML adds the y method to all objects.  Now, you can call
+  Sequel::BasicObject.remove_methods!, which will remove those
+  methods from Sequel::BasicObject, allowing them to be used as
+  intended in the above DSL.
+
+* Sequel associations now accept an :eager_loader_key option, which
+  can be useful for associations to specify the column to use for the
+  key_hash for custom :eager_loaders.
+
+* A JDBC subadapter for the AS400 database was added.
+
+Other Improvements
+------------------
+
+* The one_to_one setter method and the one_to_many and many_to_many
+  remove_all methods now apply the association options (such as
+  filters) on the appropriate dataset:
+  
+    Artist.one_to_many :good_albums, :class=>:Album,
+     :conditions=>{:good=>true}
+    a = Artist[10]
+    a.remove_all_good_albums
+    # Before: WHERE artist_id = 10
+    # After:  WHERE artist_id = 10 AND good IS TRUE
+
+* Plugin loading now works correctly when the plugin module name
+  is the same name as an already defined top level constant.  This
+  means that the active_model plugin should now work correctly if
+  you require active_model before loading the Sequel plugin.
+
+* The nested_attributes plugin now preserves nested attributes for
+  *_to_one associations on validation failures.
+
+* Transactions now work correctly on Oracle when using the JDBC
+  adapter.
+  
+* Dataset#limit once again works correctly on MSSQL 2000.  It was
+  broken in Sequel 3.9.0.
+
+* many_to_one associations now use limit(1) to ensure only one
+  record is returned.  If you don't want this (because maybe you
+  are using the :eager_graph association option), you need to
+  set the :key option to nil and use a custom :dataset option.
+  
+* many_to_one and one_to_many associations now work correctly
+  with the association :eager option to eagerly load associations
+  specified by :eager when lazy loading the association.
+
+* The typecast_on_load plugin now correctly handles
+  reloading/refreshing the object, both explicitly and implicitly
+  on object creation.
+
+* The schema parser and dumper now return tinyint columns as
+  booleans when connecting to mysql using the do adapter, since
+  DataObjects now returns the columns as booleans.
+  
+* The schema dumper now deals better with unusual or database
+  specific primary key types when using the :same_db option.
+
+* On ruby 1.8, Sequel::BasicObject now undefs private methods in
+  addition to public and protected methods.  So the following
+  code now works as expected:
+  
+    DB[:a].filter{x > p} # WHERE x > p
+    
+* Sequel.connect with a block now returns the value of the block:
+
+    max_price = Sequel.connect('sqlite://items.db') do |db|
+      db[:items].max(:price)
+    end
+    
+* MSSQL emulated offset support now works correctly when Sequel's
+  core extensions are not loaded.
+  
+* Sequel::BasicObject now works correctly on rubinius, and almost
+  all Sequel specs now pass on rubinius.
+  
+* The nested_attributes plugin now uses a better exception message
+  no matching associated object is found.
+  
+* Sequel now raises a more informative error if you attempt to use
+  the native sqlite adapter with the sqlite3 gem instead of the
+  sqlite3-ruby gem.
+  
+* Multiple complex expressions with the same operator are now
+  combined for simpler SQL:
+  
+    DB[:a].filter(:a=>1, :b=>2).filter(:c=>3)
+    # Before: (((a = 1) AND (b = 2)) AND (c = 3))
+    # After:  ((a = 1) AND (b = 2) AND (c = 3))
+  
+* The Sequel::Model dataset methods (class methods proxied to the
+  model's dataset) and the Sequel::Dataset mutation methods
+  (methods that have a ! counterpart to modify the object in place)
+  have both been updated to use new dataset methods added in recent
+  versions.
+
+Backwards Compatibility
+-----------------------
+
+* The :one_to_one option of the one_to_many associations now raises
+  an exception.  Please see the section above about the new real
+  one_to_one association.
+
+* The change to apply the association options to the one_to_many and
+  many_to_many remove_all methods has the potential to break some
+  code that uses the remove_all method on associations that use
+  association options. This is especially true for many_to_many
+  associations, as filters in many_to_many associations will often
+  reference columns in the associated table, while the dataset
+  used in the remove_all method only contains the join table.  Such
+  cases should be handled by manually overriding the _remove_all
+  association instance method in the class.  It was determined that
+  it was better to issue possibly invalid queries than to issue
+  queries that make unexpected modifications.
+
+* Dataset#group_and_count now longer orders the dataset by the count.
+  Since it returns a modified dataset, if you want to order the
+  dataset, just call order on the returned dataset.
+
+* many_to_one associations now require a working :class option.
+  Previously, if you provided a custom :dataset option, a working
+  :class option was not required in some cases.
+
+* The MSSQL shared adapter dataset methods switched from using
+  the :table_options internal option key to using the :lock internal
+  option key.

data/doc/release_notes/3.2.0.txt

@@ -0,0 +1,268 @@
+New Features
+------------
+
+* Common table expressions (CTEs) are now supported.  CTEs use the
+  SQL WITH clause, and specify inline views that queries can use.
+  They also support a recursive mode, where the CTE can recursively
+  query its own output, allowing you do do things like load all
+  branches for a given node in a plain tree structure.
+  
+  The standard with takes an alias and a dataset:
+  
+    DB[:vw].with(:vw, DB[:table].filter{col < 1})
+    # WITH vw AS (SELECT * FROM table WHERE col < 1)
+    # SELECT * FROM vw
+    
+  The recursive with takes an alias, a nonrecursive dataset, and a
+  recursive dataset:
+    
+    DB[:vw].with_recursive(:vw,
+      DB[:tree].filter(:id=>1),
+      DB[:tree].join(:vw, :id=>:parent_id).
+                select(:vw__id, :vw__parent_id))
+    # WITH RECURSIVE vw AS (SELECT * FROM tree
+    #     WHERE (id = 1)
+    #     UNION ALL
+    #     SELECT vw.id, vw.parent_id
+    #     FROM tree
+    #     INNER JOIN vw ON (vw.id = tree.parent_id))
+    # SELECT * FROM vw
+
+  CTEs are supported by Microsoft SQL Server 2005+, DB2 7+,
+  Firebird 2.1+, Oracle 9+, and PostgreSQL 8.4+.
+  
+* SQL window functions are now supported, and a DSL has been added to
+  ease their creation.  Window functions act similarly to aggregate
+  functions but operate on sliding ranges of rows.
+  
+  In virtual row blocks (blocks passed to filter, select, order, etc.)
+  you can now provide a block to method calls to change the default
+  behavior to create functions that weren't possible previously.  The
+  blocks aren't called, but their presence serves as a flag.
+  
+  What function is created depends on the arguments to the method:
+  
+  * If there are no arguments, an SQL::Function is created with the
+    name of method used, and no arguments.  Previously, it was not
+    possible to create functions without arguments using the virtual
+    row block DSL.  Example:
+    
+      DB.dataset.select{version{}} # SELECT version()
+    
+  * If the first argument is :*, an SQL::Function is created with a
+    single wildcard argument (*).  This is mostly useful for count:
+    
+      DB[:t].select{count(:*){}} # SELECT count(*) FROM t
+    
+  * If the first argument is :distinct, an SQL::Function is created
+    with the keyword DISTINCT prefacing all remaining arguments. This
+    is useful for aggregate functions such as count:
+    
+      DB[:t].select{count(:distinct, col1){}}
+      # SELECT count(DISTINCT col1) FROM t
+    
+  * If the first argument is :over, the second argument, if provided,
+    should be a hash of options to pass to SQL::Window.  The options
+    hash can also contain :*=>true to use a wildcard argument as the
+    function argument, or :args=>... to specify an array of arguments
+    to use as the function arguments.
+
+      DB[:t].select{rank(:over){}} # SELECT rank() OVER ()
+      DB[:t].select{count(:over, :*=>true){}} # SELECT count(*) OVER ()
+      DB[:t].select{sum(:over, :args=>col1,
+                    :partition=>col2, :order=>col3){}}
+      # SELECT sum(col1) OVER (PARTITION BY col2 ORDER BY col3)
+      
+  PostgreSQL also supports named windows.  Named windows can be
+  specified by Dataset#window, and window functions can reference
+  them using the :window option.
+  
+* Schema information for columns now includes a :ruby_default entry
+  which contains a ruby object that represents the default given by
+  the database (which is stored in :default).  Not all :default
+  entries can be parsed into a :ruby_default, but if the
+  schema_dumper extension previously supported it, it should work.
+
+* Methods to create compound datasets (union, intersect, except), now
+  take an options hash instead of a true/false flag.  The previous
+  API is still supported, but switching to specifying the ALL setting
+  using :all=>true is recommended.
+  
+  Additionally, you can now set :from_self=>false to not wrap the
+  returned dataset in a "SELECT * FROM (...)".
+  
+* Dataset#ungraphed was added that removes the graphing information
+  from the dataset.  This allows you to use Dataset#graph for the
+  automatic aliasing, or #eager_graph for the automatic aliasing and
+  joining, and then remove the graphing information so that the
+  resulting objects will not be split into subhashes or associations.
+
+* There were some introspection methods added to Dataset to describe
+  which capabilities that dataset does or does not support:
+  
+    supports_cte?
+    supports_distinct_on?
+    supports_intersect_except?
+    supports_intersect_except_all?
+    supports_window_functions?
+
+  In addition to being available for the user to use, these are also
+  used internally, so attempting to use a CTE on a dataset that
+  doesn't support it will raise an Error.
+
+* Dataset#qualify was added, which is like qualify_to with a default
+  of first_source.
+
+  Additionally, qualify now affects PlaceholderLiteralStrings.  It
+  doesn't scan the string (as Sequel never attempts to parse SQL),
+  but if you provide the column as a symbol placeholder argument, it
+  will qualify it.
+  
+* You can now specify the table and column Sequel::Migrator will use
+  to record the current schema version.  The new Migrator.run method
+  must be used to use these new options.
+  
+* The JDBC adapter now accepts :user and :password options, instead
+  of requiring them to be specified in the connection string and 
+  handled by the JDBC driver.  This should allow connections to
+  Oracle using the Thin JDBC driver.
+  
+* You can now specify the max_connections, pool_timeout, and
+  single_threaded settings directly in the connection string:
+  
+    postgres:///database?single_threaded=t
+    postgres:///database?max_connections=10&pool_timeout=20
+
+* Dataset#on_duplicate_key_update now affects Dataset#insert when
+  using MySQL.
+
+* You can now specify the :opclass option when creating PostgreSQL
+  indexes.  Currently, this only supports a single operator class
+  for all columns.  If you need different operator classes per
+  column, please post on sequel-talk.
+  
+* Model#autoincrementing_primary_key was added and can be used if
+  the autoincrementing key isn't the same as the primary key.  The
+  only likely use for this is on MySQL MyISAM tables with composite
+  primary keys where only one of the composite parts is
+  autoincrementing.
+
+* You can now use database column values as search patterns and
+  specify the text to search as a String or Regexp:
+  
+    String.send(:include, Sequel::SQL::StringMethods)
+    Regexp.send(:include, Sequel::SQL::StringMethods)
+
+    'a'.like(:x)  # ('a' LIKE x)
+    /a/.like(:x)  # ('a' ~ x)
+    /a/i.like(:x) # ('a' ~* x)
+    /a/.like(:x, 'b') # (('a' ~ x) OR ('a' ~ 'b'))
+
+* The Dataset#dataset_alias private method was added.  It can be
+  overridden if you have tables named t0, t1, etc and want to make
+  sure the default dataset aliases that Sequel uses do not clash
+  with existing table names.
+  
+* Sequel now raises an Error if you call Sequel.connect with
+  something that is not a Hash or String.
+  
+* bin/sequel now accepts a -N option to not test the database
+  connection.
+  
+* An opening_databases.rdoc file was added to the documentation
+  directory, which should be a good introduction for new users about
+  how to set up your Database connection.
+
+Other Improvements
+------------------
+
+* MySQL native adapter SELECT is much faster than before, up to 75%
+  faster.
+
+* JDBC SELECT is about 10% faster than before.  It's still much
+  slower than the native adapters, due to conversion issues.
+
+* bin/sequel now works with a YAML file on ruby 1.9.
+
+* MySQL foreign key table constraints have been fixed.
+
+* Database#indexes now works on PostgreSQL if the schema used is a
+  Symbol.  It also works on PostgreSQL versions all the way back to
+  7.4.
+
+* Graphing of datasets with dataset sources has been fixed.
+
+* Changing a columns name, type, or NULL status on MySQL now
+  supports a much wider selection of column defaults.
+  
+* The stored procedure code is now thread-safe.  Sequel is
+  thread-safe in general, but due to a bug the previous stored 
+  procedure code was not thread-safe.
+
+* The ODBC adapter now drops statements automatically instead of
+  requiring the user to do so manually, making it more similar
+  to other adapters.
+
+* The single_table_inheritance plugin no longer overwrites the STI
+  field if the field already has a value.  This allows you to use
+  create in the generic class to insert a value that will be
+  returned as a subclass:
+  
+    Person.create(:kind => "Manager")
+    
+* When altering colums on MySQL, :unsigned, :elements, :size and other
+  options given are no longer ignored.
+
+* The PostgreSQL shared adapter's explain and analyze methods have
+  been fixed, they had been broken in 3.0.
+  
+* Parsing of the server's version is more robust on PostgreSQL.
+  It should now work correctly for 8.4 and 8.4rc1 type versions.
+
+Backwards Compatibility
+-----------------------
+
+* Dataset#table_exists? has been removed, since it never worked
+  perfectly.  Use Database#table_exists? instead.
+  
+* Model.grep now calls Dataset#grep instead of Enumerable#grep.
+  If you are using Model.grep, you need to modify your application.
+
+* The MSSQL shared adapter previously used the :with option for
+  storing the NOLOCK setting of the query.  That option has been
+  renamed to :table_options, since :with is now used for CTEs.
+  This should not have an effect unless you where using the option
+  manually.
+
+* Previously, providing a block to a method calls in virtual row
+  blocks did not change behavior, where now it causes a different
+  code path to be used.  In both cases, the block is not evaluated,
+  but that may change in a future version.
+  
+* Dataset#to_table_reference protected method was removed, as it was
+  no longer used.
+  
+* The pool_timeout setting is now converted to an Integer, so if you
+  used to pass in a Float, it no longer works the same way.
+  
+* Most files in adapters/utils have been removed, in favor of 
+  integrating the code directly into Database and Dataset.  If you
+  were previously checking for the UnsupportedIntersectExcept or
+  related modules, use the Dataset introspection methods instead
+  (e.g. supports_intersect_except?).
+  
+* If you were using the ODBC adapter and manually dropping returned
+  statements, you should note that now statements are dropped
+  automatically, and the execute method doesn't return a statement
+  object.
+  
+* The MySQL adapter on_duplicate_key_update_sql is now a private
+  method.
+  
+* If you were modifying the :from dataset option directly, note that
+  Sequel now expects this option to be preprocessed.  See the new
+  implementation of Dataset#from for an idea of the changes
+  required.
+  
+* Dataset#simple_select_all? now returns false instead of true for a
+  dataset that selects from another dataset.