3.12.0.txt

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

Migration Changes ↑

  • A TimestampMigrator has been added to Sequel, and is automatically used if any migration has a version greater than

    1. This migrator operates similarly to the default

    ActiveRecord migrator, in that it allows missing migrations. It differs from the ActiveRecord migrator in that it supports migrations with the same timestamp/version as well as a wide variety of timestamp formats (though the ActiveRecord default of YYYYMMDDHHMMSS is recommended and should be used in portable code).

    Sequel still defaults to the old migrator, but you can use the new one without making changes to your old migrations. Just make sure your new migration starts with a version greater than 20000100, and Sequel will automatically convert the previous schema table to the new format.

  • A new migration DSL was added:

    Sequel.migration do
  up do
  end

  down do
  end
end

    The old style of using a Sequel::Migration subclass is still supported, but it is recommended that new code use the new DSL.

  • The default migrator also had significant issues fixed. First, it now saves the migration version after each migration, instead of after all migrations, which means Sequel won’t attempt to apply already applied migrations if there was previously an error when applying multiple migrations at once on a database that didn’t support transactional schema modification.

    Second, duplicate migration versions in the default migrator now raise an exception, as do missing migration versions. Neither should happen when using the default migrator, which requires consecutive integer versions, similar to the old ActiveRecord migrator.

  • Execution times for migrations are now logged to the database’s loggers.

New Plugins ↑

  • A sharding plugin has been added that allows model objects to work well with sharded databases. When using it, model objects know which shard they were retrieved from, so when you save the object, it is saved back to that shard. The sharding plugin also works with associations, so associated records are retrieved from the same shard the main object was retreived from. The sharding plugin also works with both methods of eager loading, and provides methods that you can use to create objects on specific shards.

  • An update_primary_key plugin has been added that allows Sequel to work correctly if you modify the primary key of a model object. This should not be necessary if you are using surrogate keys, but if your database uses natural primary keys which can change, this should be helpful.

  • An association_pks plugin has been added that adds association_pks and association_pks= methods to model objects for both one_to_many and many_to_many associations. The association_pks method returns an array of primary key values for the associated objects, and the association_pks= method modifies the database to ensure that the object is only associated to the objects specified by the array of primary keys provided to it.

  • A string_stripper plugin has been added that strips all strings that are assigned to attribute values. This is useful for web applications where you want to easily remove leading and trailing whitespace in form entries before storing them in the database.

  • A skip_create_refresh plugin has been added that skips the refresh of after you save a new model object. On most databases, Sequel refreshes the model object after inserting it in order to get values for all of the columns. For performance reasons, you can use this plugin to skip the refresh if it isn’t necessary for you.

Other New Features ↑

  • Sequel::Model#set_fields and update_fields were added. These methods have a similar API to set_only and update_only, but they operate differently. While set_only and update_only operate over the hash, these methods operate over the array of fields, so they don’t raise errors if the hash contains fields not in the array:

    params = {:a=>1, :b=>2, :c=>3}
album = Album[1]

# raises Error because :a is not in the fields
album.set_only(params, [:b, :c])

# Just sets the value of album.b and album.c
album.set_fields(params, [:b, :c])

    Other than handling entries in the hash that aren’t in the array, set_fields and update_fields also handle entries not in the hash differently:

    # Doesn't modify the object, since the hash is empty
album.set_only({}, [:b, :c])

# Sets album.b and album.c to nil, since they aren't in the hash
album.set_fields({}, [:b, :c])

  • The :eager_loader association option has a new API, though the previous API still works. Instead of accepting three arguments, it can now accept a single hash argument, which will use the :key_hash, :rows, and :association keys for the previous three arguments. The hash will also contain a :self key whose value is the dataset doing the eager load, which was not possible to determine using the old API.

  • Sequel::SQL::Expression#hash has been added so that the objects are now safe to use as hash keys.

  • A Dataset#order_prepend method has been added allowing you to prepend to an existing order. This is useful if want to modify a dataset’s order such that it first orders by the columns you provide, but for any rows where the columns you provide are equal, uses the existing order to further order the dataset:

    ds.order(:albums__name).order_prepend(:artists__name)
# ORDER BY artists.name, albums.name

  • When creating foreign key columns, you can now use a :deferrable option to set up a foreign key constraint that is not checked until the end of the transaction:

    DB.create_table(:albums) do
  primary_key :id
  String :name
  foreign_key :artist_id, :artists, :deferrable=>true
end

  • many_to_many associations now support a :join_table_block option that is used by the add/remove/remove_all methods. It can modify the dataset to ensure that certain columns are included when inserting or to add a filter so that only certain records are deleted. It’s useful if you have a many_to_many association that is filtered to only a subset of the matching rows in the join table.

  • The single_table_inheritance plugin now supports :model_map and :key_map options to set up a custom mapping of column values to model classes. For simple situations such as when you are mapping integer values to certain classes, a :model_map hash is sufficient:

    Employee.plugin :single_table_inheritance, :type_id,
 :model_map=>{1=>:Staff, 2=>:Manager}

    Here the :model_map keys are type_id column values, and the :model_map values are symbols or strings specifying class names.

    For more complex conditions, you can use a pair of procs:

    Employee.plugin :single_table_inheritance, :type_name,
 :model_map=>proc{|v| v.reverse},
 :key_map=>proc{|klass| klass.name.reverse}

    Here the type_name column is a string column holding the reverse of the class’s name.

  • The single_table_inheritance plugin now correctly sets up subclass filters for middle tables in a class hierarchy with more than 2 levels. For example, with this code:

    class Employee < Sequel::Model; end
Employee.plugin :single_table_inheritance, :kind
class Manager < Employee; end
class Executive < Manager; end

    Sequel previously would not return Executives if you used Manager.all. It now correctly recognizes subclasses so that it will return both Managers and Executives.

  • Sequel::Model.qualified_primary_key_hash has been added, giving you a hash that can be used for filtering. It is similar to primary_key_hash, but it qualifies the keys with the model’s table. It’s useful if you have joined the table to another table that has columns with the same name, but you want to only look for a single model object in that dataset.

  • For consistency, you can now use Dataset#order_append as an alias for order_more.

Other Improvements ↑

  • Sequel now correctly removes schema entries when altering tables. Previously, some adapters that had to query the existing schema when altering tables resulted in the previous schema being cached.

  • Sequel::Model::Errors#on now always returns nil if there are no errors on the attribute. Previously, it would return an empty array in certain cases. Additionally, Sequel::Model::Errors#empty? now returns true if there are no errors, where it certain cases it would return false even if there were no errors.

  • The schema_dumper extension now works with tables specified as Sequel::SQL::Identifiers.

  • Sequel now recognizes the timestamp(N) with(out) time zone column type.

  • The lazy_attributes plugin no longer requires the core extensions to work correctly.

  • DatabaseDisconnectError support has been added to the ODBC adapter, allowing Sequel to detect disconnects and remove the connection from the connection pool.

  • A leak of JDBC statement objects when using transactions was fixed in the jdbc adapter.

  • The jdbc adapter now gives a nicer error message if you use a connection string that it doesn’t recognize and there is an error when connecting.

  • Temporary table creation was fixed on Microsoft SQL Server, but it is not recommended as it changes the name of the table. If you use Microsoft SQL Server, you should prefix your temporary table names with # and use the regular create table method.

  • A large number of guides were added to Sequel to make it easier for new and existing users to learn more about Sequel. The following guides were added:

    • Querying in Sequel

    • Migration and Schema Modification

    • Model Hooks

    • Model Validations

    • Sequel for SQL Users

    • Sequel for ActiveRecord Users

  • RDoc section support was added to Sequel::Database, making the method documentation easier to read.

Backwards Compatibility ↑

  • Sequel::Database now defines the indexes and tables methods, even if the adapter does not implement them, similar to how connect and execute are defined. Previously, you could use respond_to? to check if the adapter supported them, now they raise Sequel::NotImplemented if the database adapter does not implement them.

  • Sequel used to raise NotImplementedError in certain default definitions of methods inside Sequel::Database and Sequel::Dataset, when the methods were supposed to be overridden in subclasses. Sequel now uses a Sequel::NotImplemented exception class for these exceptions, which is a subclass of Sequel::Error.

  • Sequel no longer applies all association options to the dataset used to remove all many_to_many associated objects. You should use the new :join_table_block option to get similar behavior if you were filtering the many_to_many association based on columns in the join table and you wanted remove_all to only remove the related columns.

  • Sequel now calls certain before and after hook actions in plugins in a different order than before. This should not have an effect unless you were relying on them being called in the previous order. Now, when overriding before hooks in plugins, Sequel always does actions before calling super, and when overriding after hooks in plugins, Sequel always does actions after calling super.

  • The hook_class_methods plugin no longer skips later after hooks if a previous after hook returns false. That behavior now only occurs for before hooks.

  • Sequel now only removes primary key values when updating objects if you are saving the entire object and you have not modified the values of the primary keys. Previously, Sequel would remove primary key values when updating even if you specified the primary key column specifically or the primary key column was modified and you used save_changes/update.

  • Sequel now uses explicit methods instead of aliases for certain methods. This should only affect you if for example you overrode Dataset#group to do one thing and wanted Dataset#group_by to do the default action. Now, Dataset#group_by, and methods like it, are explicit methods that just call the methods they previously aliased. This also means that if you were overriding Dataset#group and explicitly aliasing group_by to it, you no longer need the alias.

  • The single_table_inheritance plugin now uses IN instead of = for subclass filters. This could lead to poor performance if the database has a very bad query planner.

  • The private transaction_statement_object method was removed from the JDBC adapter, and Sequel will no longer check for the presence of the method in the transaction code.

  • The Sequel::Migrator object is now a class instead of a module, and has been pretty much rewritten. If you were using any methods of it besides apply and run, they no longer work.