viking-sequel 3.10.0

data/doc/release_notes/3.5.0.txt

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