sequel 5.6.0 → 5.7.0

data/doc/release_notes/3.5.0.txt

@@ -1,510 +0,0 @@
-New Plugins
------------
-
-* A class_table_inheritance plugin has been added, supporting model
-  inheritance in the database using a table-per-model-class approach.
-  Each table stores only attributes unique to that model or subclass
-  hierarchy.
-  
-  For example, with this hierarchy:
-
-                Employee
-               /        \
-            Staff     Manager
-                         |
-                      Executive
-
-  the following database schema may be used (table - columns):
-
-  * employees - id, name, kind
-  * staff - id, manager_id
-  * managers - id, num_staff
-  * executives - id, num_managers
-
-  The class_table_inheritance plugin assumes that the main table
-  (e.g. employees) has a primary key field (usually
-  autoincrementing), and all other tables have a foreign key of the
-  same name that points to the same key in their superclass's table.
-  For example:
-
-  * employees.id  - primary key, autoincrementing
-  * staff.id - foreign key referencing employees(id)
-  * managers.id - foreign key referencing employees(id)
-  * executives.id - foreign key referencing managers(id)
-
-  When using the class_table_inheritance plugin, subclasses use joined
-  datasets:
-
-    Employee.dataset.sql  # SELECT * FROM employees
-    Manager.dataset.sql   # SELECT * FROM employees
-                          # INNER JOIN managers USING (id)
-    Executive.dataset.sql # SELECT * FROM employees
-                          # INNER JOIN managers USING (id)
-                          # INNER JOIN executives USING (id)
-
-  This allows Executive.all to return instances with all attributes
-  loaded.  The plugin overrides deleting, inserting, and updating
-  in the model to work with multiple tables, by handling each table
-  individually.
-
-  This plugin allows and encourages the use of a :key option to mark
-  a column holding the class name.  This allows methods on the
-  superclass to return instances of specific subclasses.
-
-    a = Employee.all # [<#Staff>, <#Manager>, <#Executive>]
-    
-  This plugin requires the lazy_attributes plugin and uses it to
-  handle subclass specific attributes that would not be loaded
-  when calling superclass methods (since those wouldn't join
-  to the subclass tables).  For example:
-    
-    a.first.values # {:id=>1, name=>'S', :kind=>'Staff'}
-    a.first.manager_id # Loads the manager_id attribute from the
-                       # database
-                       
-  The class_table_inheritance plugin requires JOIN USING and
-  therefore is not supported on H2 or Microsoft SQL Server, which do
-  not support that SQL-92 feature.
-  
-* An associations_dependencies plugin was added for deleting,
-  destroying, or nullifying associated objects when destroying a
-  model object.  This just gives an easy way to add the necessary
-  before and after destroy hooks.  The following association types
-  support the following dependency actions:
-
-  * :many_to_many - :nullify (removes all related entries in join
-    table)
-  * :many_to_one - :delete, :destroy
-  * :one_to_many - :delete, :destroy, :nullify (sets foreign key to
-    NULL for all associated objects)
-    
-  This plugin works directly with the association datasets and does
-  not use any cached association values.  The :delete action will
-  delete all associated objects from the database in a single SQL
-  call. The :destroy action will load each associated object from the
-  database and call the destroy method on it.
-  
-  The plugin call takes a hash of association symbol keys and 
-  dependency action symbol values.  Alternatively, you can specify
-  additional dependencies later using add_association_dependencies:
-  
-    Business.plugin :association_dependencies, :address=>:delete
-    # or:
-    Artist.plugin :association_dependencies
-    Artist.add_association_dependencies :albums=>:destroy,
-      :reviews=>:delete, :tags=>:nullify
-
-* A force_encoding plugin was added that forces the encoding of
-  strings used in model instances.  When model instances are loaded
-  from the database, all values in the hash that are strings are
-  forced to the given encoding.  Whenever you update a model column
-  attribute, the resulting value is forced to a given encoding if the
-  value is a string.  There are two ways to specify the encoding.
-  You can either do so in the plugin call itself, or via the
-  forced_encoding class accessor:
-  
-    class Album < Sequel::Model
-      plugin :force_encoding, 'UTF-8'
-      # or
-      plugin :force_encoding
-      self.forced_encoding = 'UTF-8'
-    end
-    
-  This plugin only works on ruby 1.9, since strings don't have
-  encodings in 1.8.
-  
-* A typecast_on_load plugin was added, for fixing bad database
-  typecasting when loading model objects. Most of Sequel's database
-  adapters don't have complete control over typecasting, and may
-  return columns that aren't typecast correctly (with correct being
-  defined as how the model object would typecast the same column
-  values).
-
-  This plugin modifies Model.load to call the setter methods (which
-  typecast by default) for all columns given.  You can either specify
-  the columns to typecast on load in the plugin call itself, or
-  afterwards using add_typecast_on_load_columns:
-
-    Album.plugin :typecast_on_load, :release_date, :record_date
-    # or:
-    Album.plugin :typecast_on_load
-    Album.add_typecast_on_load_columns :release_date, :record_date
-
-  If the database returns release_date and record_date columns as
-  strings instead of dates, this will ensure that if you access those
-  columns through the model object, you'll get Date objects instead of
-  strings.
-
-* A touch plugin was added, which adds Model#touch for updating an
-  instance's timestamp, as well as touching associations when an
-  instance is updated or destroyed.
-  
-  The Model#touch instance method saves the object with a modified
-  timestamp.  By default, it uses the :updated_at column, but you can
-  set which column to use. It also supports touching of associations,
-  so that when the current model object is updated or destroyed, the
-  associated rows in the database can have their modified timestamp
-  updated to the current timestamp.  Example:
-  
-    class Album < Sequel::Model
-      plugin :touch, :column=>:modified_on, :associations=>:artist
-    end
-
-* A subclasses plugin was added, for recording all of a models
-  subclasses and descendent classes.  Direct subclasses are available
-  via the subclasses method, and all descendent classes are available
-  via the descendents method:
-
-    c = Class.new(Sequel::Model)
-    c.plugin :subclasses
-    sc1 = Class.new(c)
-    sc2 = Class.new(c)
-    ssc1 = Class.new(sc1)
-    c.subclasses    # [sc1, sc2]
-    sc1.subclasses  # [ssc1]
-    sc2.subclasses  # []
-    ssc1.subclasses # []
-    c.descendents   # [sc1, ssc1, sc2]
-
-  The main use case for this is if you want to modify all models
-  after the model subclasses have been created.  Since mutable
-  options are copied when subclassing, modifying parent classes
-  does not affect current subclasses, only future ones.  The
-  subclasses plugin allows you get all subclasses so that you can
-  easily modify them.  The plugin only records subclasses
-  created after the plugin call, though.
-
-* An active_model plugin was added, giving Sequel::Model an
-  ActiveModel complaint API, in so much as it passes the
-  ActiveModel::Lint tests.
-
-New Extensions
---------------
-
-* A named_timezones extension was added, allowing you to use named
-  timezones such as "America/Los_Angeles" (the default Sequel
-  timezone support only supports UTC or local time). This extension
-  requires TZInfo.  It also sets the Sequel.datetime_class to 
-  DateTime, so database timestamps will be returned as DateTime
-  instances instead of Time instances.  This is because ruby's
-  Time class doesn't support timezones other than UTC and local time.
-  
-  This plugin allows you to pass either strings or TZInfo::Timezone
-  instance to Sequel.database_timezone=, application_timezone=, and
-  typecast_timezone=.  If a string is passed, it is converted to a
-  TZInfo::Timezone using TZInfo::Timezone.get.
-
-  Let's say you have the database server in New York and the
-  application server in Los Angeles.  For historical reasons, data
-  is stored in local New York time, but the application server only
-  services clients in Los Angeles, so you want to use New York
-  time in the database and Los Angeles time in the application.  This
-  is easily done via:
-
-    Sequel.database_timezone = 'America/New_York'
-    Sequel.application_timezone = 'America/Los_Angeles'
-
-  Then, before timestamps are stored in the database, they are
-  converted to New York time.  When timestamps are retrieved from the
-  database, they are converted to Los Angeles time.
-
-* A thread_local_timezones extension was added.  This allows you to
-  set a per-thread timezone that will override the default global
-  timezone while the thread is executing.  The main use case is for
-  web applications that execute each request in its own thread, and
-  want to set the timezones based on the request.  The most common
-  example is having the database always store time in UTC, but have
-  the application deal with the timezone of the current user.  That
-  can be done with:
-  
-    Sequel.database_timezone = :utc
-    # In each thread:
-    Sequel.thread_application_timezone = current_user.timezone
-
-  This extension is designed to work with the named_timezones
-  extension.
-  
-* An sql_expr extension was added that adds .sql_expr methods to
-  all objects, giving them easy access to Sequel's DSL:
-  
-    1.sql_expr < :a     # 1 < a
-    false.sql_expr & :a # FALSE AND a
-    true.sql_expr | :a  # TRUE OR a
-    ~nil.sql_expr       # NOT NULL
-    "a".sql_expr + "b"  # 'a' || 'b'
-
-  Proc#sql_expr uses a virtual row:
-
-    proc{[[a, b], [a, c]]}.sql_expr | :x
-    # (((a = b) AND (a = c)) OR x)
-
-* A looser_typecasting extension was added, for using to_f and to_i
-  instead of the more strict Kernel.Float and Kernel.Integer when
-  typecasting floats and integers. To use it, you should extend the
-  database with the Sequel::LooserTypecasting module after loading
-  the extension:
-
-    Sequel.extension :looser_typecasting
-    DB.extend(Sequel::LooserTypecasting)
-
-  This makes the behavior more like ActiveRecord:
-  
-    a = Artist.new(:num_albums=>'a')
-    a.num_albums # => 0
-
-Other New Features
-------------------
-
-* Associations now support composite keys.  All of the :*key options
-  options now accept arrays of symbols instead of plain symbols.
-  Example:
-  
-    Artist.primary_key # [:name, :city]
-    Album.many_to_one :artist, :key=>[:artist_name, :artist_city]
-    Artist.one_to_many :albums, :key=>[:artist_name, :artist_city]
-    
-  All association types are supported, including the built-in
-  many_to_many association and the many_through_many plugin.  Both
-  methods of eager loading work with composite keys for all
-  association types. Setter and add/remove/remove_all methods
-  also now work with composite keys.
-  
-* Associations now respect a :validate option, which can be set to
-  false to not validate when implicitly saving associated objects.
-  
-  There isn't a lot of implicit saving in Sequel's association
-  methods, but this gives the user the control over validation when
-  the association methods implicitly save an object.
-
-* In addition to the regular association methods, the
-  nested_attributes plugin was also updated to respect the
-  :validate_association option. It was also modified to not validate
-  associated objects twice, once when the parent object was validated
-  and again when the associated object was saved.  Additionally, if
-  you pass :validate=>false to the save method when saving the parent
-  object, it will not longer attempt to validate associated objects
-  when saving them.
-
-* Dataset#insert and #insert_sql were refactored and now support the
-  following API:
-  
-  * No arguments - Treat as a single empty hash argument
-  * Single argument:
-    * Hash - Use keys as columns and values as values
-    * Array - Use as values, without specifying columns
-    * Dataset - Use a subselect, without specifying columns
-    * LiteralString - Use as the values
-  * 2 arguments:
-    * Array, Array - Use first array as keys, second as values
-    * Array, Dataset - Use a subselect, with the array as columns
-    * Array, LiteralString - Use LiteralString as the values, with
-      the array as the columns
-  * Anything else: Treat all given values an an array of values
-
-* Graphing now works with previously joined datasets.  The main use
-  case of this is when eagerly loading (via eager_graph) model
-  associations for models backed by joined datasets, such as those
-  created by the class_table_inheritance plugin.
-  
-* Sequel.virtual_row was added allowing you to easily use the
-  VirtualRow support outside of select, order, and filter calls:
-  
-    net_benefit = Sequel.virtual_row{revenue > cost}
-    good_employee = Sequel.virtual_row{num_commendations > 0}
-    fire = ~net_benefit & ~good_employee
-    demote = ~net_benefit & good_employee
-    promote = net_benefit & good_employee
-    DB[:employees].filter(fire).update(:employed=>false)
-    DB[:employees].filter(demote).update(:rank=>:rank-1)
-    DB[:employees].filter(promote).update(:rank=>:rank+1)
-
-* When Sequel wraps exception in its own classes (to provide database
-  independence), it now keeps the wrapped exception available in
-  a wrapped_exception accessor.  This allows you to more easily
-  determine the wrapped exception class, without resorting to parsing
-  the exception message.
-  
-    begin
-      DB.run('...')
-    rescue Sequel::DatabaseError => e
-      case e.wrapped_exception
-      when Mysql::Error
-        ...
-      when PGError
-        ...
-      end
-    end
-    
-* The MySQL adapter now supports a Dataset#split_multiple_result_sets
-  method that yields arrays of rows (one per result set), instead of
-  rows.  This allows you to submit multiple statements at the same
-  time (or call a stored procedure that returns multiple result
-  sets), and know which rows are related to which result sets.
-  
-  This violates a lot of Sequel's internal assumptions and should be
-  used with care.  Existing row_procs are modified to work correctly,
-  but graphing will not work on these datasets.
-
-* The ADO adapter now accepts a :conn_string option and uses that
-  as the full ADO connection string.  This can be used to connect to
-  any datasource ADO supports, such as Microsoft Excel.
-  
-* The Microsoft SQL Server shared adapter now supports a
-  Database#server_version method.
-  
-* The Microsoft SQL Server shared adapter now supports updating and
-  deleting from joined datasets.
-  
-* The Microsoft SQL Server shared adapter now supports a
-  Dataset#output method that uses the OUTPUT clause.
-
-* Model#_save now calls either Model#_insert or Model#_update for
-  inserting/updating the row in the database.  This allows for easier
-  overriding when you want to allow creating and updating model
-  objects backed by a joined dataset.
-  
-* Dataset#graph now takes a :from_self_alias option specifying the
-  alias to use for the subselect created if the receiver is a joined
-  but not yet graphed dataset.  It defaults to the first source table
-  in the receiver.
-
-Other Improvements
-------------------
-
-* Typecasting model attributes is now done before checking existing
-  values, instead of after.  Before, the code for the model attribute
-  setters would compare the given value to the existing entry.  If it
-  didn't match, the value was typecasted and then assigned.  That led
-  to the following situation:
-
-    a = Album[1]
-    a.num_tracks # => 10
-    params # => {'num_tracks'=>'10'}
-    a.set(params)
-    a.changed_columns # => [:num_tracks]
-
-  The new behavior typecasts the value first, and only sets it and
-  records the column as changed if it doesn't match the typecasted
-  value.
-  
-* Model#modified? is now always true if the record is new.  modified?
-  indicates the instance's status relative to the database, and since
-  a new object is not yet in the database, and saving the object
-  would add it, the object is considered modified. A consequence of
-  this is that Model#save_changes now always saves if the object is
-  new.
-  
-  If you want to check if there were changes to columns since the
-  object was first initialized, you should use
-  !changed_columns.empty?, which was the historical way to handle
-  the situation.
-
-* The DataObjects (do) adpater now supports DataObjects 0.10.
-
-* Dataset#select_more and Dataset#order_more no longer affect the
-  receiver.  They are supposed to just return a modified copy of the
-  receiver instead of modifying the receiver itself.  For a few
-  versions they have been broken in that they modified the receiver
-  in addition to returning a modified copy.
-  
-* Performance was increased for execution of prepared statements
-  with multiple bound variables on MySQL.
-  
-* On MySQL, database errors raised when preparing statements or
-  setting bound variable values are now caught and raised as
-  Sequel::DatabaseErrors.
-  
-* On MySQL, more types of disconnection errors are detected.
-  
-* When altering columns in MySQL, options such as :unsigned,
-  :elements, and :size that are given in the call are now respected.
-
-* MySQL enum defaults are now handled correctly in the schema dumper.
-
-* The schema dumper no longer attempts to use unparseable defaults
-  as literals on MySQL, since MySQL does not provide defaults as
-  valid literals.
-
-* The emulated offset support in the shared Microsoft SQL Server
-  adapter now works better with model classes (or any datasets with
-  row_procs).
-  
-* Microsoft SQL Server now supports using the WITH clause in delete,
-  update, and insert calls.
-  
-* Parsed indexes when connecting to Microsoft SQL Server via JDBC no
-  longer include primary key indexes.
-  
-* Dataset#insert_select now returns nil if disable_insert_returning
-  is used in the shared PostgreSQL adapter.  This makes it work as
-  expected with model object creation.
-  
-* Calling Model.set_primary_key with an array of symbols to set
-  a composite primary key is now supported.  You can also provide
-  multiple symbol arguments to do the same thing.  Before, specifying
-  an array of symbols broke the Model.[] optimization.
-
-* Literalization of timezones in timestamps now works correctly on
-  Oracle.
-  
-* __FILE__ and __LINE__ are now used everywhere that eval is called
-  with a string, which makes for better backtraces.
-  
-* The native MySQL adapter now correctly handles returning before
-  yielding all result sets.  Previously, this caused a commands out
-  of sync error.
-  
-* Table names in common table expressions are now quoted.
-
-* The Oracle adapter's Dataset#except now accepts a hash, giving it
-  the same API as the default Dataset#except.
-  
-* When connecting to Microsoft SQL Server via ADO, allow
-  Dataset#insert to take multiple arguments.
-  
-* Fractional timestamps are no longer used on ODBC.
-
-* Schema parsing now works on MSSQL when the database is set to not
-  quote identifiers.
-  
-* Timezone offsets are no longer used on Microsoft SQL Server, since
-  they only work for the datetimeoffset type.
-  
-* Only 3 fractional digits in timestamps are used in Microsoft SQL
-  Server, since an error is raised if the use the datetime type
-  with more than that.
-
-* The integration test suite now has guards for expected failures
-  when run on known databases.  Expected failures are marked as
-  pending.
-
-Backwards Compatibility
------------------------
-
-* Graphing to an previously joined (but not graphed) dataset now
-  causes the receiver to be wrapped in a subselect, so if you
-  graph a dataset to a previously joined dataset, and then filter
-  the dataset referring to tables that were in the joined dataset
-  (other than the first table), the SQL produced will probably no
-  longer be valid.  You should either filter the dataset before
-  graphing or use the name of the first source of the joined
-  dataset (which is what the subselected is aliased to) if filtering
-  afterward.
-  
-  In certain cases, this change can cause tables to be aliased
-  differently, so if you were graphing previously joined datasets
-  and then filtering using the automatically generated aliases, you
-  might need to modify your code.
-
-* The DataObjects (do) adpater no longer supports DataObjects 0.9.x.
-
-* The Dataset#virtual_row_block_call private instance method has
-  been removed.
-
-* Sequel's timezone support was significantly refactored, so if you
-  had any custom modifications to the timezone support, they might
-  need to be refactored as well.
-
-* The SQL generation code was significantly refactored, so if you
-  had any custom modifications in that area, you might need to
-  refactor as well.