ANN: Sequel 3.48.0 Released

Sequel is a lightweight database access toolkit for Ruby.

  • Sequel provides thread safety, connection pooling and a concise
    DSL for constructing SQL queries and table schemas.
  • Sequel includes a comprehensive ORM layer for mapping records to
    Ruby objects and handling associated records.
  • Sequel supports advanced database features such as prepared
    statements, bound variables, stored procedures, savepoints,
    two-phase commit, transaction isolation, master/slave
    configurations, and database sharding.
  • Sequel currently has adapters for ADO, Amalgalite, CUBRID,
    DataObjects, DB2, DBI, Firebird, IBM_DB, Informix, JDBC, MySQL,
    Mysql2, ODBC, OpenBase, Oracle, PostgreSQL, SQLite3, Swift, and
    TinyTDS.

Sequel 3.48.0 has been released and should be available on the gem
mirrors. This is the last minor release in the Sequel 3 series.

= 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
https://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])
    end

    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.

    Model.constraint_validation_reflections[:column]

    => [[: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,
    :validates_options=>{:presence=>{:allow_nil=>true}}

  • 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.

Thanks,
Jeremy