2.12.0.txt

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

Overview

Sequel 2.12 is really just a stepping stone to Sequel 3.0, which will be released next month. All major changes currently planned for 3.0 have been made in 2.12, but 2.12 contains many features that have been deprecated and will be removed or moved into extensions or plugins in 3.0.

Deprecation Logging

If you use a deprecated method or feature, Sequel will by default print a deprecation message and 10 lines of backtrace to standard error to easily allow you to figure out which code needs to be updated. You can change where the deprecation messages go and how many lines of backtrace are given using the following:

# Log deprecation information to a file
Sequel::Deprecation.output = File.open('deprecated.txt', 'wb')

# Use 5 lines of backtrace when logging deprecation messages
Sequel::Deprecation.backtraces = 5

# Use all backtrace lines when logging deprecation messages
Sequel::Deprecation.backtraces = true

# Don't include backtraces in the deprecation logging
Sequel.Deprecation.backtraces = false

# Turn off all deprecation logging
Sequel::Deprecation.output = nil

Deprecated Features Moving to Extensions

  • Migrations are being moved into sequel/extensions/migration. There isn’t any reason that they should be loaded in normal use since they are used so rarely. The sequel command line tool uses this extension to run the migrations.

  • Adding the blank? method to all objects has been moved into sequel/extensions/blank.

  • Dataset#print and Sequel::PrettyTable have been moved into sequel/extensions/pretty_table.

  • Dataset#query and related methods have been moved into sequel/extensions/query.

  • Dataset#paginate and related methods have been moved into sequel/extensions/pagination.

  • String inflection methods (e.g. “people”.singularize) have been moved into sequel/extensions/inflector.

  • String date/time conversion methods (e.g. ‘2000-01-01’.to_date) have been moved into sequel/extensions/string_date_time.

Deprecated Model Features Moving to Plugins

  • Model validation class methods have been moved to a plugin. Sequel users are encouraged to write their own validate instance method instead. A new validation_helpers plugin has been added to make this easier, it’s explained in the New Features section. If you want to continue using the validation class methods:

    Sequel::Model.plugin :validation_class_methods

  • Model hook class methods have been moved to a plugin. Sequel users are encouraged to write their own hook instance methods, and call super to get hooks specified in superclasses or plugins. If you want to continue using the hook class methods:

    Sequel::Model.plugin :hook_class_methods

  • Model schema methods (e.g. Model.set_schema, Model.create_table, Model.drop_table) have been moved to a plugin. The use of these methods has been discouraged for a long time. If you want to use them:

    Sequel::Model.plugin :schema

  • Model.set_sti_key has been moved to a plugin. So you should change:

    MyModel.set_sti_key :key_column

    to:

    MyModel.plugin :single_table_inheritance, :key_column

  • Model.set_cache has been moved to a plugin. So you should change:

    MyModel.set_cache cache_store, opts

    to:

    MyModel.plugin :caching, cache_store, opts

  • Model.serialize has been moved to a plugin. So you should change:

    MyModel.serialize :column, :format=>:yaml

    to:

    MyModel.plugin :serialization, :yaml, :column

    Because the previous serialization support depended on dataset transforms, the new serialization support is implemented differently, and behavior may not be identical in all cases. However, this should be a drop in replacement for most users.

Deprecated Features To Be Removed in Sequel 3.0

  • Dataset#transform is deprecated without any replacement planned. It was announced on the Sequel mailing list that transforms would be removed unless someone said they needed them, and nobody said that they did.

  • Dataset#multi_insert and Dataset#import are no longer aliases of each other. Dataset#multi_insert now takes an array of hashes, and Dataset#import now takes an array of columns and an array of arrays of values. Using multi_insert with import’s API or vice-versa is deprecated.

  • Calling Dataset#[] with no arguments or an integer argument is deprecated.

  • Calling Dataset#map with both an argument and a block is deprecated.

  • Database#multi_threaded? and Database#logger are both deprecated.

  • Calling Database#transaction with a symbol to specify which server to use is deprecated. You should now call it with an option hash with a :server key.

  • Array#extract_options! and Object#is_one_of? are both deprecated.

  • The metaprogramming methods taken from metaid are deprecated and have been moved into Sequel::Metaprogramming. If you want them available to specific objects/classes, just include or extend with Sequel::Metaprogramming. If you want all objects to have access to the metaprogramming methods, install metaid. Note that the class_def method from metaid doesn’t exist in Sequel::Metaprogramming, since it really isn’t different from define_method (except it is public instead of private).

  • Module#class_attr_overridable, class_attr_reader, and metaalias are deprecated.

  • Using Model#set or update when the columns for the model are not set and you provide a hash with symbol keys is deprecated. Basically, you must have setter methods now for any columns used in set or update.

  • Model#set_with_params and update_with_params are deprecated, use set and update instead.

  • Model#save! is deprecated, use save(:validate=>false).

  • Model.is and Model.is_a are deprecated, use Model.plugin.

  • Model.str_columns, Model#str_columns, set_values, and update_values are deprecated. You should use set and update instead of set_values and update_values, though they operate differently.

  • Model.delete_all, Model.destroy_all, Model.size, and Model.uniq are deprecated, use .delete, .destroy, .count, and .distinct.

  • Model.belongs_to, Model.has_many, and Model.has_and_belongs_to_many are deprecated, use .many_to_one, .one_to_many, and .many_to_many.

  • Model#dataset is deprecated, use Model.dataset.

  • SQL::CastMethods#cast_as is deprecated, use cast.

  • Calling Database#schema without a table argument is deprecated.

  • Dataset#uniq is deprecated, use Dataset#distinct.

  • Dataset#symbol_to_column_ref is deprecated, use literal.

  • Dataset#quote_column_ref is deprecated, use quote_identifier.

  • Dataset#size is deprecated, use count.

  • Passing options to Dataset#each, all, single_record, single_value, sql, select_sql, update, update_sql, delete, delete_sql, and exists is deprecated. Modify the options first using clone or a related method, then call one of the above methods.

  • Dataset#create_view and create_or_replace_view are deprecated, use the database methods instead.

  • Dataset.dataset_classes, model_classes, polymorphic_key, and set_model are deprecated.

  • Database#>> is deprecated.

  • String#to_blob and SQL::Blob#to_blob are deprecated, use to_sequel_blob.

  • The use of Symbol#| to create array subscripts is deprecated, use Symbol#sql_subscript.

  • Symbol#to_column_ref is deprecated, use Dataset#literal.

  • String#expr is deprecated, use String#lit.

  • Array#to_sql, String#to_sql, and String#split_sql are deprecated.

  • Passing an array to Database#<< is deprecated.

  • Range#interval is deprecated.

  • Enumerable#send_each is deprecated.

  • When using ruby 1.8, Hash#key is deprecated.

  • Sequel.open is deprecated, use Sequel.connect.

  • Sequel.use_parse_tree and Sequel.use_parse_tree= are deprecated.

  • All upcase_identifier methods and the :upcase_identifiers database option are deprecated, use identifier_input_method = :upcase instead.

  • Using a virtual row block without an argument is deprecated, see Sequel.virtual_row_instance_eval= under New Features.

  • When using the JDBC adapter, Java::JavaSQL::Timestamp#usec is deprecated. Sequel has returned Java::JavaSQL::Timestamp as DateTime or Time for a few versions, so this shouldn’t affect most people.

  • Sequel will no longer require bigdecimal/util, enumerator, or yaml in 3.0. If you need them in your code, make sure you require them yourself. Using features added by requiring these standard libaries will not bring up a deprecation warning, for obvious reasons.

  • Sequel::Error::InvalidTransform, Sequel::Error::NoExistingFilter, and Sequel::Error::InvalidStatement exceptions will be removed in Sequel 3.0. You will not get a deprecation message if you reference them in 2.12.

  • Sequel::Model::Validation::Errors is deprecated, use Sequel::Model::Errors instead. Referencing the old name will not bring up a deprecation message.

New Features

  • Sequel.virtual_row_instance_eval= was added, which lets you give Sequel 2.12 the behavior that will be the standard in 3.0. It changes blocks passed to Dataset#filter, select, or order that don’t accept arguments (or accept any number of arguments) to instance eval the block in the context of a new VirtualRow instance instead of passing a new VirtualRow instance to the block. It allows you to change code that looks like this:

    dataset.filter{|o| (o.number > 10) & (o.name > 'M')}

    to:

    dataset.filter{(number > 10) & (name > 'M')}

    When instance_eval is used, only local variables are available to the block. Any calls to instance methods will be interpreted as calling VirtualRow#method_missing, which generates identifiers or functions. When virtual_row_instance_eval is enabled, the following type of code will break:

    # amount is a instance method
dataset.filter{:number + amount > 0}

    Just like this example, the only type of code that should break is when a virtual row block was used when it wasn’t necessary (since it doesn’t use the VirtualRow argument).

    When Sequel.virtual_row_instance_eval = false, using a virtual row block that doesn’t accept an argument will cause a deprecation message.

    Here’s a regular expression that should catch most places where you are using a virtual row block without an argument.

    egrep -nr '[^A-Za-z0-9_](filter|select|select_more|order|order_more|get|where|having|from|first|and|or|exclude|find|subset|constraint|check)( *(\([^)]*\) *)?){*[^|]' *

    An RDoc page explaining virtual row blocks was added as well.

  • A validation_helpers model plugin was added that allows you to do validations similar to the old class level validations inside the Model#validate instance method. The API has changed, but it’s capable of most of the same validations. It doesn’t handle acceptance_of or confirmation_of validations, as those shouldn’t be handled in the model.

    # Old class level validations
validates_format_of :col, :with=>/.../
validates_length_of :col, :maximum=>5
validates_length_of :col, :minimum=>3
validates_length_of :col, :is=>4
validates_length_of :col, :within=>3..5
validates_not_string :col
validates_numericality_of :col
validates_numericality_of :col, :only_integer=>true
validates_presence_of :col
validates_inclusion_of :col, :in=>[3, 4, 5]
validates_uniqueness_of :col, :col2
validates_uniqueness_of([:col, :col2])

# New instance level validations
def validate
  validates_format /.../, :col
  validates_max_length 5, :col
  validates_min_length 3, :col
  validates_exact_length 4, :col
  validates_length_range 3..5, :col
  validates_not_string :col
  validates_numeric :col
  validates_integer :col
  validates_presence :col
  validates_includes([3,4,5], :col)
  validates_unique :col, :col2
  validates_unique([:col, :col2])
end

    Another change made is to specify the same type of validation on multiple attributes, you must use an array:

    # Old
validates_length_of :name, :password, :within=>3..5

# New
def validate
  validates_length_range 3..5, [:name, :password]
end

    The :message, :allow_blank, :allow_missing, and :allow_nil options are still respected. The :tag option is not needed as instance level validations work with code reloading without workarounds. The :if option is also not needed for instance level validations:

    # Old
validates_presence_of :name, :if=>:new?
validates_presence_of :pass, :if=>{flag > 3}

# New
def validate
  validates_presence(:name) if new?
  validates_presence(:pass) if flag > 3
end

    The validates_each also doesn’t have an equivalent instance method, since it is much easier to just write your own validation:

    # Old
validates_each(:date) do |o,a,v|
  o.errors.add(a, '...') unless v > Date.today
end

# New
def validate
  errors.add(:date, '...') unless date > Date.today
end

  • MySQL adapter datasets now have on_duplicate_key_update and insert_ignore methods which modify the SQL used to support ON DUPLICATE KEY UPDATE and INSERT INGORE syntax in multi_insert and import.

  • If you use the MySQL native adapter, you can set:

    Sequel::MySQL.convert_invalid_date_time = nil

    to return dates like “0000-00-00” and times like “25:00:00” as nil values instead of raising an error. You can also set it to :string to return the values as strings.

  • You can now use Sequel without modifying any core classes, by defining a SEQUEL_NO_CORE_EXTENSIONS constant or environment variable. In 2.12, this may still add some deprecated methods to the core classes, but in 3.0 no methods will be added to the core classes if you use this.

  • You can now use Sequel::Model without the associations implementation by defining a SEQUEL_NO_ASSOCIATIONS constant or environment variable.

Other Improvements

  • Model column accessors have been made faster and the overhead of creating them has been reduced significantly.

  • ~{:bool_col=>true} now generates an bool_col IS NOT TRUE filter instead of bool_col != TRUE. This makes it return records with NULL values. If you only want to have false records, you should use {:bool_col=>false}. This works better with SQL’s 3 valued boolean logic.

    It is slightly inconsistent with ~{:col=>1}, since that won’t return values where col is NULL, but it gives the user the ability to create an IS [NOT] (TRUE|FALSE) filter, which Sequel previously did not support.

    If you really want the old behavior, you can change it to ~{true=>:bool_col}.

  • Model.use_transactions was added for setting whether model objects should use transactions when destroying or saving records. Like most Sequel options, it’s settable on a global, per model, and per object basis:

    Sequel::Model.use_transactions = false
MyModel.use_transactions = true
my_model.use_transactions = false

    You can also turn it on or off for specific save calls:

    my_model.save(:transaction=>true)

  • The Oracle adapter now supports schema parsing.

  • When using Model.db=, all current dataset options are copied to a new dataset created with the new db.

  • Model::Errors#count was refactored to improve performance.

  • Most exception classes that were located under Sequel::Error are now located directly under Sequel. The old names are not deprecated (unless mentioned above), but their use is now discouraged. The exceptions have the same name except that Sequel::Error::PoolTimeoutError changed to Sequel::PoolTimeout.

  • Dataset#where now always affects the WHERE clause. Before, it was just an alias of filter, so it modified the HAVING clause if the dataset already had a HAVING clause.

  • The optimization of Model.[] introduced in 2.11.0 broke on databases that didn’t support LIMIT. The optimization now works on those databases.

  • All of the the RDoc documentation was reviewed and many updates were made, resulting in significantly improved documentation quality.

  • Model.def_dataset_method now works when the model doesn’t have an associated dataset, as it will add the method to a dataset given to set_dataset in the future.

  • Database#get and select now take a block that is passed to the dataset they create.

  • You can disable the use of INSERT RETURNING in the shared PostgreSQL adapter using disable_insert_returning. This is mostly useful if you are inserting a large number of records.

  • A bug relating to aliasing columns in the JDBC adapter has been fixed.

  • Sequel can now create and drop schema-qualified views.

  • Performance of Dataset#destroy for model datasets was improved.

  • The specs now run on Rspec 1.2.

  • Internal dependence on the methods that Sequel adds to core classes has been eliminated, any internal use of methods that Sequel adds to the core classes is now considered a bug.

  • A possible bug where Database#rename_table would not remove a cached schema entry has been fixed.

  • The Oracle and MySQL adapters now raise an error as soon as you call distinct on a dataset, instead of waiting until the SQL is generated.

Backwards Compatibilty

  • Saving a newly inserted record in an after_create or after_save hook is no longer broken. It broke in 2.10 as a side effect of allowing the hook to check whether or not the record was a new record. The code has been changed so that a @was_new instance variable will be defined to true if the record was just created.

    Similarly, instead of not modifying changed_columns until after the after hooks run, a @columns_updated instance variable will be available in the after hooks that is a hash of exactly what attribute keys and values were used in the update.

    These changes break compatibility with 2.11.0 and 2.10.0, but restore compatibility with 2.9.0 and previous versions.

  • PostgreSQL no longer uses savepoints for nested transactions by default. If you want to use a savepoint, you have to pass the :savepoint option to the transaction method. Using savepoints by default broke expectations when a method raised Rollback to rollback the transaction, and it only rolled back to the last savepoint.

  • The anonymous model classes created by Sequel::Model() are now stored in Model::ANONYMOUS_MODEL_CLASSES instead of the @models class instance variable of the main module.

  • The mappings of adapter schemes to classes are now stored in Sequel::ADAPTER_MAP instead of the Database @@adapters class variable.

  • Model instances no longer contain a reference to their class’s @db_schema.

  • Database schema sql methods (e.g. alter_table_sql) are now private.

  • Database#[] no longer accepts a block. It’s not possible to call it with a block in general usage, anyway.

  • The Sequel::Schema::SQL module no longer exists, the methods it included were placed directly in the Sequel::Database class.

  • The Sequel::SQL::SpecificExpression class has been removed, subclasses now inherit from Sequel::SQL::Expression.

  • Sequel now requires its own files with an absolute path.

  • The file hierarchy of the sequel library changed significantly.