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