sequel 3.3.0 → 3.4.0

data/CHANGELOG

@@ -1,3 +1,65 @@
+=== 3.4.0 (2009-09-02)
+
+* Allow datasets without tables to work correctly on Oracle (mikegolod)
+
+* Add #invert, #asc, and #desc to OrderedExpression (dlee)
+
+* Allow validates_unique to take a block used to scope the uniqueness constraint (drfreeze, jeremyevans)
+
+* Automatically save a new many_to_many associated object when associating the object via add_* (jeremyevans)
+
+* Add a nested_attributes plugin for modifying associated objects directly through a model object (jeremyevans)
+
+* Add an instance_hooks plugin for adding hooks to specific model instances (jeremyevans)
+
+* Add a boolean_readers plugin for creating attribute? methods for boolean columns (jeremyevans)
+
+* Add Dataset#ungrouped which removes existing grouping (jeremyevans)
+
+* Make Dataset#group with nil or no arguments to remove existing grouping (dlee)
+
+* Fix using multiple emulated ALTER TABLE statements (e.g. drop_column) in a single alter_table block on SQLite (jeremyevans)
+
+* Don't allow inserting on a grouped dataset or a dataset that selects from multiple tables (jeremyevans)
+
+* Allow class Item < Sequel::Model(DB2) to work (jeremyevans)
+
+* Add Dataset#truncate for truncating tables (jeremyevans)
+
+* Add Database#run method for executing arbitrary SQL on a database (jeremyevans)
+
+* Handle index parsing correctly for tables in a non-default schema on JDBC (jfirebaugh)
+
+* Handle unique index parsing correctly when connecting to MSSQL via JDBC (jfirebaugh)
+
+* Add support for converting Time/DateTime to local or UTC time upon storage, retrieval, or typecasting (jeremyevans)
+
+* Accept a hash when typecasting values to date, time, and datetime types (jeremyevans)
+
+* Make JDBC adapter prepared statements support booleans, blobs, and potentially any type of object (jfirebaugh)
+
+* Refactor the inflection support and modify the default inflections (jeremyevans, dlee)
+
+* Make the serialization and lazy_attribute plugins add accessor methods to modules included in the class (jeremyevans)
+
+* Make Database#schema on JDBC include a :column_size entry specifying the maximum length/precision for the column (jfirebaugh)
+
+* Make Database#schema on JDBC accept a :schema option (dlee)
+
+* Fix Dataset#import when called with a dataset (jeremyevans)
+
+* Give a much more descriptive error message if the mysql.rb driver is detected (jeremyevans)
+
+* Make postgres adapter work with a modified postgres-pr that raises PGError (jeremyevans)
+
+* Make ODBC adapter respect Sequel.datetime_class (jeremyevans)
+
+* Add support for generic concepts of CURRENT_{DATE,TIME,TIMESTAMP} (jeremyevans)
+
+* Add a timestamps plugin for automatically creating hooks for create and update timestamps (jeremyevans)
+
+* Add support for serializing to json (derdewey)
+
 === 3.3.0 (2009-08-03)
 
 * Add an assocation_proxies plugin that uses proxies for associations (jeremyevans)

data/README.rdoc

@@ -327,7 +327,7 @@ Which is equivalent to the SQL:
 When retrieving records from joined datasets, you get the results in a single hash, which is subject to clobbering if you have columns with the same name in multiple tables:
 
   DB[:items].join(:order_items, :item_id => :id).first
-  => {:id=>order_items.id), :item_id=>order_items.item_id}
+  => {:id=>order_items.id, :item_id=>order_items.item_id}
 
 Using graph, you can split the result hashes into subhashes, one per join:
 
@@ -518,7 +518,7 @@ many_to_one creates a getter and setter for each model object:
   post.author = Author[:name => 'Sharon']
   post.author
 
-one_to_many and many_to_many create a getter method, a method for adding an object to the association, a method for removing an object from the association, and a method for removing all associated objected from the association:
+one_to_many and many_to_many create a getter method, a method for adding an object to the association, a method for removing an object from the association, and a method for removing all associated objects from the association:
 
   class Post < Sequel::Model
     one_to_many :comments
@@ -539,10 +539,10 @@ one_to_many and many_to_many create a getter method, a method for adding an obje
 All associations add a dataset method that can be used to further filter or reorder the returned objects, or modify all of them:
 
   # Delete all of this post's comments from the database
-  Post.comments_dataset.destroy
+  post.comments_dataset.destroy
 
   # Return all tags related to this post with no subscribers, ordered by the tag's name
-  Post.tags_dataset.filter(:subscribers=>0).order(:name).all
+  post.tags_dataset.filter(:subscribers=>0).order(:name).all
 
 === Eager Loading
 

data/doc/release_notes/3.3.0.txt

@@ -2,7 +2,7 @@ New Features
 ------------
 
 * An association_proxies plugin has been added.  This is not a
-  full-blown proxy implemention, but it allows you to write code
+  full-blown proxy implementation, but it allows you to write code
   such as:
   
     artist.albums.filter{num_tracks > 10}

data/doc/release_notes/3.4.0.txt

@@ -0,0 +1,325 @@
+New Plugins
+-----------
+
+* A nested_attributes plugin was added allowing you to modify
+  associated objects directly through a model object, similar to
+  ActiveRecord's Nested Attributes.
+  
+    Artist.plugin :nested_attributes
+    Artist.one_to_many :albums
+    Artist.nested_attributes :albums
+    a = Artist.new(:name=>'YJM',
+     :albums_attributes=>[{:name=>'RF'}, {:name=>'MO'}])
+    # No database activity yet
+
+    a.save # Saves artist and both albums
+    a.albums.map{|x| x.name} # ['RF', 'MO']
+  
+  It takes most of the same options as ActiveRecord, as well as a
+  a few additional options:
+  
+  * :destroy - Allow destruction of nested records.
+  * :limit - For *_to_many associations, a limit on the number of
+    records that will be processed, to prevent denial of service
+    attacks.
+  * :remove - Allow disassociation of nested records (can remove the
+    associated object from the parent object, but not destroy the
+    associated object).
+  * :strict - Set to false to not raise an error message if a primary
+    key is provided in a record, but it doesn't match an existing
+    associated object.
+    
+  If a block is provided, it is passed each nested attribute hash.
+  If the hash should be ignored, the block should return anything
+  except false or nil.
+
+* A timestamps plugin was added for automatically adding
+  before_create and before_update hooks for setting values on
+  timestamp columns.  There are a couple of existing external
+  plugins that handle timestamps, but the implementations are
+  suboptimal.  The new built-in plugin supports the following
+  options (with the default in parentheses):
+  
+  * :create - The field to hold the create timestamp (:created_at)
+  * :force - Whether to overwrite an existing create timestamp
+    (false)
+  * :update - The field to hold the update timestamp (:updated_at)
+  * :update_on_create - Whether to set the update timestamp to the
+    create timestamp when creating (false)
+      
+* An instance_hooks plugin was added for adding hooks to specific
+  w
+  model instances:
+  
+    obj = Model.new
+    obj.after_save_hook{do_something}
+    obj.save # calls do_something after the obj has been saved
+
+  All of the standard hooks are supported, except for
+  after_initialize.  Instance level before hooks are executed in
+  reverse order of addition before calling super.  Instance level
+  after hooks are executed in order of addition after calling super.
+  If any of the instance level before hook blocks return false, no
+  more instance level before hooks are called and false is returned.
+
+  Instance level hooks are cleared when the object is saved
+  successfully.
+  
+* A boolean_readers plugin was added for creating attribute? methods
+  for boolean columns.  This can provide a nicer API:
+  
+    obj = Model[1]
+    obj.active  # Sequel default column reader
+    obj.active? # Using the boolean_readers plugin
+    
+  You can provide a block when loading the plugin to change the
+  criteria used to determine if the column is boolean:
+  
+    Sequel::Model.plugin(:boolean_readers) do |c|
+      db_schema[c][:db_type] =~ /\Atinyint/
+    end
+    
+  This may be useful if you are using MySQL and have some tinyint
+  columns that represent booleans and others that represent integers.
+  You can turn the convert_tinyint_to_bool setting off and use the
+  attribute methods for the integer value and the attribute? methods
+  for the boolean value.
+
+Other New Features
+------------------
+
+* Sequel now has support for converting Time/DateTime to local or UTC
+  time upon storage, retrieval, or typecasting.
+  
+  There are three different timezone settings:
+
+  * Sequel.database_timezone - The timezone that timestamps use in
+    the database.  If the database returns a time without an offset,
+    it is assumed to be in this timezone.
+
+  * Sequel.typecast_timezone - Similar to database_timezone, but used
+    for typecasting data from a source other than the database.  This
+    is currently only used by the model typecasting code.
+
+  * Sequel.application_timezone - The timezone that the application
+    wants to deal with.  All Time/DateTime objects are converted into
+    this timezone upon retrieval from the database.
+
+  Unlike most things in Sequel, these are only global settings, you
+  cannot change them per database.  There are only three valid
+  timezone settings:
+
+  * nil (the default) - Don't do any timezone conversion.  This is
+    the historical behavior.
+
+  * :local - Convert to local time/Consider time to be in local time.
+
+  * :utc - Convert to UTC/Consider time to be in UTC.
+
+  So if you want to store times in the database as UTC, but deal with
+  them in local time in the application:
+
+    Sequel.application_timezone = :local
+    Sequel.database_timezone = :utc
+
+  If you want to set all three timezones to the same value:
+
+    Sequel.default_timezone = :utc
+
+  There are three conversion methods that are called:
+
+  * Sequel.database_to_application_timestamp - Called on time objects
+    coming out of the database.  If the object coming out of the
+    database (usually a string) does not have an offset, assume it is
+    already in the database_timezone.  Return a Time/DateTime object
+    (depending on Sequel.datetime_class), in the application_timzone.
+
+  * Sequel.application_to_database_timestamp - Used when literalizing
+    Time/DateTime objects into an SQL string.  Converts the object to
+    the database_timezone before literalizing them.
+
+  * Sequel.typecast_to_application_timestamp - Called when
+    typecasting objects for model datetime columns.  If the object
+    being typecasted does not already have an offset, assume it is
+    already in the typecast_timezone.  Return a Time/DateTime object
+    (depending on Sequel.datetime_class), in the
+    application_timezone.
+
+  Sequel does not yet support named timezones or per thread
+  modification of the timezone (for showing all timestamps in the
+  current user's timezone).  Extensions to support both features are
+  planned for a future version.
+
+* Dataset#truncate was added for truncating tables.  Truncate allows
+  for fast removal of all rows in a table.
+  
+* Sequel now supports typecasting a hash to date, time, and datetime
+  types.  This allows easy usage of Sequel with forms that split
+  the entry of these database types into separate from fields.
+  With this code, you can just have field names like:
+
+    date[year]
+    date[month]
+    date[day]
+
+  Rack will parse that into:
+
+    {'date'=>{'year'=>?, 'month'=>?, 'day'=>?}}
+
+  So then you can do:
+
+    obj.date = params['date']
+    # or
+    obj.set(params)
+  
+* validates_unique now takes a block that can be used to scope the
+  uniqueness constraint. This allows you to easily set up uniqueness
+  validations that are only necessary in a given scope.  For example,
+  a validation on username, but only for active users (as inactive
+  users are soft deleted but remain in the table).  You just pass a
+  block to validates_unique:
+
+    validates_unique(:name){|ds| ds.filter(:active)}
+    
+* The serialization plugin now supports json.
+    
+* Sequel now supports generic concepts of
+  CURRENT_{DATE,TIME,TIMESTAMP}.  Most databases support these SQL
+  concepts, but not all, and some implementations act differently.
+
+  The Sequel::SQL::Constants module holds the three constants,
+  which are instances of SQL::Constant, an SQL::GenericExpression
+  subclass.  This module is included in Sequel, so you can reference
+  the constants more easily (e.g. Sequel::CURRENT_TIMESTAMP).
+  It's separated out into a separate module so that you can just
+  include that module in the top level scope, allowing you to
+  reference the constants directly (e.g. CURRENT_TIMESTAMP).
+  
+    DB[:events].filter{date < ::Sequel::CURRENT_DATE}
+    # or:
+    include Sequel::SQL::Constants
+    DB[:events].filter{date < ::CURRENT_DATE}
+
+* Database#run was added for executing arbitrary SQL on a database.
+  It's an alias for Database#<<, but it allows for a nicer API inside
+  migrations, since you can now do:
+  
+    run 'SQL'
+    
+  instead of:
+  
+    self << 'SQL'
+    
+  You can also provide a :server option to run the SQL on the
+  given server/shard:
+  
+    run 'SQL', :server=>:shard1
+
+* Sequel::Model() can now take a database argument in addition to
+  a symbol or dataset argument.  If a database is given, it'll create
+  an anonymous subclass attached to the given database.  Other changes
+  were made to allow the following code to work:
+  
+    class Item < Sequel::Model(DB2)
+    end
+    
+  That will work correctly assuming a table named items in DB2.
+
+* Dataset#ungrouped was added for removing a grouping from an
+  existing dataset.  Also, Dataset#group when called with no arguments
+  or with a nil argument also removes any existing grouping instead
+  of resulting in invalid SQL.
+
+* Model#modified? was added, letting you know if the model has been
+  modified.  If the model hasn't been modified, calling
+  Model#save_changes will do nothing.
+
+* SQL::OrderedExpression now supports #asc, #desc, and #invert.
+
+Other Improvements
+------------------
+
+* The serialization and lazy_attribute plugins now add accessor
+  methods to a module included in the class, instead of to the
+  model class itself.  This allows the methods to be overridden
+  in the class and work well with super, as well for the plugins
+  to work together on the same column.  Make sure the
+  lazy_attributes accessor is setup before the serialization
+  accessor if you want to have a lazy serialized column.
+  
+* Calling the add_* method for many_to_many association now saves the
+  record if the record is new.  This makes it operate more similarly
+  to one_to_many associations.  Previously, it raised an Error.
+
+* Dataset#import now works correctly when called with a dataset.
+  Previously, it generated incorrect SQL.
+
+* The JDBC adapter now converts byte arrays to/from SQL::Blob.
+
+* The JDBC adapter now attempts to bind unknown types using
+  setObject instead of raising, so it can work with native Java
+  objects.  It also binds boolean parameters correctly.
+
+* Using multiple emulated ALTER TABLE statements (such as
+  drop_column) in a single alter_table block now works correctly
+  on SQLite.
+  
+* Database#indexes now works on JDBC for tables in a non-default
+  schema.  It also now properly detects unique indexes on MSSQL.
+
+* Database#schema on JDBC now accepts a :schema option.  Also,
+  returned schema hashes now include a :column_size entry specifying
+  the maximum length/precision for the column, since the
+  :db_type entry doesn't have contain the information on JDBC.
+
+* Datasets without tables now work correctly on Oracle, so things
+  like DB.get(...) now work.
+  
+* A descriptive error message is given if you attempt to use
+  Sequel with the mysql.rb driver (which Sequel doesn't support).
+  
+* The postgres adapter now works correctly with a modified
+  postgres-pr that raises PGErrors instead of RuntimeErrors
+  (e.g. http://github.com/jeremyevans/postgres-pr).
+  
+* You now get a Sequel::InvalidOperation instead of a NoMethodError
+  if you attempt to update a dataset without a table.
+  
+* The inflection support has been modified to reduce code
+  duplication.
+
+Backwards Compatibility
+-----------------------
+
+* Sequel now includes fractional seconds in timestamps for all
+  adapters except MySQL.  It's possible that this may break
+  timestamp columns for databases that are not regularly tested.
+  
+* Sequel now includes timezone values in timestamps on Microsoft
+  SQL Server, Oracle, PostgreSQL and SQLite.  The modification for
+  SQLite is probably the biggest cause for concern, since SQLite
+  stores times as text.  If you have an SQLite database that uses
+  timestamps and is accessed by something other than Sequel, you
+  should make sure that it works with the timestamp format that
+  Sequel now uses.
+  
+* The default timestamp format used by Sequel now uses a space
+  instead of 'T' between the date and time parts, which could
+  possibly affect some databases that are not regularly tested.
+
+* Attempting to insert into a grouped dataset or a dataset that
+  selects from multiple tables will now raise an Error.  Previously,
+  it would ignore any GROUP or JOIN settings and generate bad SQL if
+  there were multiple FROM tables.
+  
+* Database#<< now always returns nil.  Before, the return value was
+  adapter dependent.
+
+* ODBC::Time and ODBC::DateTime values are now converted to the
+  Sequel.datetime_class.  Before, ODBC::Time used Time and
+  ODBC::DateTime used DateTime regardless of the
+  Sequel.datetime_class setting.
+  
+* The default inflections were modified, fixing some obvious errors
+  and possibly changing some existing inflections.  Further changes
+  to the default inflections are unlikely.

data/doc/sharding.rdoc

@@ -32,7 +32,7 @@ Let's say you have 4 slave database servers with names slave_server0,
 slave_server1, slave_server2, and slave_server3.
 
   DB=Sequel.connect('postgres://master_server/database', \
-    :servers=>{:read_only=>proc{|db| :host=>db.get_slave_host}})
+    :servers=>{:read_only=>proc{|db| {:host=>db.get_slave_host}}})
   def DB.get_slave_host
     @current_host ||= -1
     "slave_server#{(@current_host+=1)%4}"
@@ -50,8 +50,8 @@ it shows that the master database is named :default.  So for 4 masters and
 4 slaves:
 
   DB=Sequel.connect('postgres://master_server/database', \
-    :servers=>{:read_only=>proc{|db| :host=>db.get_slave_host}, \
-      :default=>proc{|db| :host=>db.get_master_host}})
+    :servers=>{:read_only=>proc{|db| {:host=>db.get_slave_host}}, \
+      :default=>proc{|db| {:host=>db.get_master_host}}})
   def DB.get_slave_host
     @current_slave_host ||= -1
     "slave_server#{(@current_slave_host+=1)%4}"