3.10.0.txt

doc/release_notes/3.10.0.txt
Last Update: 2011-07-16 11:31:03 -0700

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.