sequel 4.26.0 → 5.37.0

data/doc/release_notes/2.12.0.txt

@@ -1,534 +0,0 @@
-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.