Last Update: 2013-06-02 13:49:43 -0700

Deprecation Warnings

The main change in Sequel 3.48.0 is the deprecation of Sequel features that will be modified, moved, or removed in Sequel 4. For the reasoning behind these changes, please review the commits logs at github.com/jeremyevans/sequel-4-plans/commits/master

Deprecation Logging

If you use a deprecated method or feature, Sequel will by default print a deprecation message and 10 lines of backtrace to stderr 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')

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

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

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

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

# Select which backtrace lines to output
Sequel::Deprecation.backtrace_filter = \
  lambda{|line, line_no| line_no < 3 || line =~ /my_app/}

Major Change

  • The core extensions will no longer be loaded by default. You will have to use ‘Sequel.extension :core_extensions` to load the core extensions.

  • The Symbol#[] and Symbol#{<,>,<=,>=} methods will no longer be provided by the core extensions on ruby 1.8. You will have to use ‘Sequel.extension :ruby18_symbol_extensions` to use them.

Core Behavior Changes

  • Dataset#filter becomes an alias for where, and exclude becomes an alias for exclude_where. You will have to use ‘DB.extension :filter_having` to get the previous behavior. Dataset#and and or will also only affect the WHERE clause.

  • Dataset#and, or, and invert will not raise errors for no existing filter.

  • Dataset#select_more becomes an alias for select_append.

  • Dataset#select and from will not longer consider a hash argument as an alias specification. You will have to use ‘DB.extension :hash_aliases` to get the previous behavior.

  • Database#dataset and Dataset.new will not take an options hash.

  • Database#transaction :disconnect=>:retry option will be removed.

  • Calling Dataset#add_graph_aliases before graph or set_graph_aliases will raise an Error.

  • Datasets will have a frozen options hash by default.

  • Dataset#set_overrides and set_defaults will move to the set_overrides extension.

  • Sequel.empty_array_handle_nulls will be removed. To get the empty_array_handle_nulls = false behavior, you will have to use ‘DB.extension :empty_array_ignore_nulls`.

  • The second argument to Dataset union, intersect, and except must be an options hash if it is given.

  • The fourth argument to Dataset join_table must be an options hash if it is given.

  • Using a mismatched number of placeholders and arguments in a placeholder literal string will raise an error.

  • Dataset#graph_each will move to the graph_each extension.

  • Database#default_schema will be removed.

  • Dataset#[]= will be moved to the sequel_3_dataset_methods extension.

  • Dataset#insert_multiple will be moved to the sequel_3_dataset_methods extension.

  • Dataset#set will be moved to the sequel_3_dataset_methods extension.

  • Dataset#to_csv will be moved to the sequel_3_dataset_methods extension.

  • Dataset#db= and opts= setters will be moved to the sequel_3_dataset_methods extension.

  • Dataset#qualify_to and qualify_to_first_source will be moved to the sequel_3_dataset_methods extension.

  • Remove default methods that raise Sequel::NotImplemented: Database#connect, execute, foreign_key_list, indexes, tables, and views, and Dataset#fetch_rows.

  • Sequel::SQL::Expression#to_s will be removed.

  • All Dataset methods in Dataset::PUBLIC_APPEND_METHODS except for literal, quote_identifier, and quote_schema_table will be removed.

  • All Dataset methods in Dataset::PRIVATE_APPEND_METHODS will be removed.

  • Sequel k_require, ts_require, tsk_require, and check_requiring_thread will be removed.

  • Dataset.def_append_methods will be removed.

  • Dataset#table_ref_append will be removed.

  • Sequel.virtual_row_instance_eval accessor will be removed.

  • Database#reset_schema_utility_dataset will be removed.

Adapter Behavior Changes

  • The Database#do method will be removed from the ado, db2, dbi, informix, odbc, openbase, and oracle adapters.

  • The jdbc adapter will raise an error when parsing the schema for a table if it detects results for the same table name in multiple schemas.

  • The Database#query method will be removed from the informix adapter.

  • Dataset#lock on PostgreSQL will check the given lock mode.

  • Sequel will check the client_min_messages setting before use on PostgreSQL.

  • Prepared statement placeholders on PostgreSQL will no longer support implicit casting via :$x__type.

Extension Behavior Changes

  • The following extensions will no longer make global changes to the Database and Dataset classes: null_dataset, pagination, pretty_table, query, schema_caching, schema_dumper, select_remove, and to_dot. These will be changed to Database/Dataset specific extensions.

  • The pg_auto_parameterize and pg_statement_cache extensions will be removed.

  • Sequel::Dataset.introspect_all_columns will be removed from the columns_introspection extension.

  • PGRangeOp#starts_before and ends_after will be removed from the pg_range_ops extension.

Model Behavior Changes

  • Model#initialize will accept only one argument.

  • The after_initialize hook will be moved to a plugin.

  • Move blacklist-based security methods (set_except, update_except, .set_restricted_columns) to a plugin.

  • The :eager_loader and :eager_grapher association option procs will always be passed a hash.

  • Model string column setters will consider array and hash input to be invalid.

  • Remove save taking multiple arguments for the columns to save. Add Model#save :columns option for saving specific columns.

  • Don’t automatically choose a reciprocal association with a condition or block.

  • Don’t automatically set up reciprocal associations if multiple ones match.

  • Model::Errors#[] will no longer modify the receiver. If you want autovivification, use the active_model plugin.

  • Model.set_primary_key will not longer accept composite keys as multiple arguments.

  • The correlated_subquery eager limit strategy will be removed.

  • The following Model class dataset methods will be removed: print, each_page, paginate, set, add_graph_aliases, insert_multiple, query, set_overrides, set_defaults, to_csv.

  • The Model.{destroy,delete,update} class dataset methods will be moved to the scissors plugin.

  • Model#pk_or_nil will be removed.

  • Model#set_values will no longer be called directly by any Sequel code, and overriding it is deprecated. It will be removed in Sequel 4.1.

  • Model.cache_anonymous_models accessor will move to Sequel module.

  • Model::InstanceMethods.class_attr_overridable and .class_attr_reader will be removed.

  • The :one_to_one option check for one_to_many associations will be removed.

Plugin Behavior Changes

  • Public dataset methods will no longer have class methods automatically added.

  • The validates_not_string validation will be removed from the validation_class_methods and validation_helpers plugin.

  • In the json_serializer plugin, the to_json :root=>true option means :root=>:collection instead of :root=>:both.

  • In the json_serializer plugin, the to_json :naked option will default to true, and there will not be way to add the JSON.create_id automatically.

  • In the json_serializer plugin, from_json will no longer automatically delete the JSON.create_id key from the input hash.

  • The to_json and to_xml :all_columns and :all_associations options in the json_serializer and xml_serializer plugins will be removed.

  • The Model.json_create method will be removed from the json_serializer plugin.

  • The validates_type validation will raise validation errors for nil if :allow_nil=>true is not used.

  • auto_validate_presence_columns will be removed from the auto_validations plugin

  • The identity_map plugin will be removed.

Internal Changes

  • The sequel_core.rb and sequel_model.rb files will be removed.

  • Dataset#{quote_identifiers,identifier_output_method, identifier_input_method} will assume Database implements the methods.

Forwards Compatibility

Not all changes planned in Sequel 4 have deprecation warnings. The following changes will be made in Sequel 4 but do not have deprecation warnings in 3.48.0:

  • The threaded connection pools will default to :connection_handling=>:queue. You can manually set :connection_handling=>:stack to get the current behavior.

  • Dataset#join_table will default to :qualify=>:deep. You can manually set :qualify=>:symbol to get the current behavior. This can be set at a global level by overriding Dataset#default_join_table_qualification.

  • Model.raise_on_typecast_failure will default to false. Set this to true to get the current behavior of raising typecast errors in the setter methods.

  • Model#save will no longer call Model#_refresh or Model#set_values internally after an insert. Manually refreshes will be treated differently than after creation refreshes in Sequel 4.

  • On SQLite, integer_booleans will be true by default. Set this to false to get the current behavior of ‘t’ for true and ‘f’ for false.

  • On SQLite, use_timestamp_timezones will be false by default. Set this to true to get the current behavior with timezone information in timestamps.

  • The default value for most option hash arguments will be an empty frozen hash. If you are overriding methods and modifying option hashes, fix your code.

  • The defaults_setter plugin will work in a lazy manner instead of an eager manner. If you must have the values hash contain defaults for new objects (instead of just getting defaults from getter methods), you’ll need to fork the current plugin.

  • Model#set_all will allow setting the primary key columns.

  • The many_to_one_pk_lookup plugin will be integrated into the default associations support.

  • The association_autoreloading plugin will be integrated into the default associations support.

  • Plugins will extend the class with ClassMethods before including InstanceMethods in the class.

  • Dataset#get, select_map, and select_order_map will automatically add aliases for unaliased expressions if given a single expression.

  • Database#tables and views on PostgreSQL will check against the current schemas in the search path.

  • Sequel::SQL::SQLArray alias for ValueList will be removed.

  • Sequel::SQL::NoBooleanInputMethods will be removed.

  • Sequel::NotImplemented will be removed.

  • Sequel::Model::EMPTY_INSTANCE_VARIABLES will be removed.

  • Sequel will no longer provide a default database for the adapter or integration specs.

New Features

  • You can now choose which Errors class to use on a per model basis by overriding Model#errors_class.

  • The following Database methods have been added to check for support: supports_index_parsing?, supports_foreign_key_parsing?, support_table_listing?, supports_view_listing?.

  • The pg_hstore_ops extension now integrates with the pg_array, pg_hstore, and pg_array_ops extensions, allowing you to pass in arrays and hashes to be treated as PGArrays and HStores, and returning ArrayOps for PostgreSQL functions/operators that return arrays.

  • Sequel.object_to_json and Sequel.json_parser_error_class have been added and all internal json usage uses them, so you can now override these methods if you want to use an alternative json library with Sequel.

  • The association_proxies plugin now accepts a block allowing the user control over which methods are proxied to the dataset or the cached array of instances. You can base the decision on where to send the method using a variety of factors including the method name, the method arguments, the state of the current instance, or the related association. Here’s an example of a simple case just depending on the name of the method;

    Model.plugin :association_proxies do |opts|
     [:find, :where, :create].include?(opts[:method])

    If the block returns true, the method is sent to the dataset, otherwise it is sent to the array of associated objects.

  • The auto_validations plugin now accepts a :not_null=>:presence option, for doing a presence validation instead of a not_null validation. This is useful for databases with NOT NULL constraints where you also want to disallow empty strings.

  • The auto_validations plugin now validates against explicit nil values in NOT NULL columns that have defaults.

  • The constraint_validations plugin now reflects validations, using Model.constraint_validation_reflections.

    # => [[:presence, {}],
    #     [:max_length, {:argument=>255, :message=>'just too long'}]]
  • The constraint_validations plugin can now be set to pass specific validations options to the validation_helpers plugin. This can be useful if using the auto_validations plugin with this plugin to avoid duplicate error messages for nil values:

    Model.plugin :constraint_validations,
  • The named_timezones extension can now be loaded as a database extension, which allows for automatic conversions of string timezones:

    DB.extension :named_timezones
    DB.timezone = 'America/Los_Angeles'
  • Offsets are now emulated by Microsoft Access using a combination of reverse orders and total counts. This is slow, especially on large datasets, but probably better than having no support at all. It is also possible to use the same code to support Microsoft SQL Server 2000, but as Sequel does not support that (minimum supported version is 2005), you have to do it manually:

    Sequel.require 'adapters/utils/emulate_offset_with_reverse_and_count'
    DB.extend_datasets Sequel::EmulateOffsetWithReverseAndCount

Other Improvements

  • Dataset#clone is now faster.

  • Database methods that create datasets (fetch, from, select, get) are now faster.

  • Model.with_pk and .with_pk! are now faster.

  • Dataset#or now just clones if given an empty argument, similar to Dataset#where.

  • Sequel now correctly frees statements after using them in the ibmdb adapter. Previously, they weren’t freed until GC, which could result in errors if all available handles are in use.

  • Dataset creation is now faster on Microsoft SQL Server.

  • The mediumint and mediumtext types are now recognized on MySQL.

  • The ado adapter now handles disconnecting an already disconnected connection.

  • The auto_validations plugin now works on databases that don’t support index parsing. However, it will not set up automatic uniqueness validations on such databases.

  • The validation_helpers is more strict in some cases when checking for nil values, using a specific nil check instead of general falsely check.

  • The table inheritance plugins now correctly handle usage of set_dataset in a subclass.

  • The bin/sequel command line tool now has specs.

Backwards Compatibility

  • Sequel now uses aliases for many internal Dataset#get calls, such as those used by table_exists? and max.

  • Sequel now no longer uses class variables internally. Instead, instance variables of the Sequel::Database class are used.

  • Sequel now sets up the identifier mangling methods on Database initialization instead of on first use.

  • The private Database#adapter_initialize method has been added for per adapter configuration. All internal adapters have been switched to use this method instead of overridding initialize, and all external adapters should as well. This makes sure that Database instances are not added to Sequel::DATABASES until they have been completely initialized.

  • Virtual row blocks no longer convert their return values to an array. Among other things, this means that having a virtual row block return a hash works as expected.

  • The private Dataset#hash_key_symbol method now only takes a single argument.

  • Database#constraint_validations in the constraint_validations plugin now returns raw hash rows, instead of arrays of validation method call arguments.

  • Dataset#count now uses a lowercase count function in the SQL.

  • Passing a non-String or Hash as the first argument to an adapter method (e.g. Sequel.postgres(1)) now raises an error. Before, this used to work on some adapters that implicitly converted the database name to a string.

  • The stats and dcov rake tasks were removed.