sequel 3.5.0 → 3.6.0

data/CHANGELOG

@@ -1,3 +1,111 @@
+=== 3.6.0 (2009-11-02)
+
+* Make the MSSQL shared adapter correctly parse the column schema information for tables in the non-default database schema (rohit.namjoshi)
+
+* Use save_changes instead of save when updating existing associated objects in the nested_attributes plugin (jeremyevans)
+
+* Allow Model#save_changes to accept an option hash that is passed to save, so you can save changes without validating (jeremyevans)
+
+* Make nested_attributes plugin add newly created objects to cached association array immediately (jeremyevans)
+
+* Make add_ association method not add the associated object to the cached array if it's already there (jeremyevans)
+
+* Add Model#modified! for explicitly marking an object as modified, so save_changes/update will run callbacks even if no columns have been modified (jeremyevans)
+ 
+* Add support for a :fields option in the nested attributes plugin, and only allow updating of the fields specified (jeremyevans)
+
+* Don't allow modifying keys related to the association when updating existing objects in the nested_attributes plugin (jeremyevans)
+
+* Add associated_object_keys method to AssociationReflection objects, specifying the key(s) in the associated model table related to the association (jeremyevans)
+
+* Support the memcached protocol in the caching plugin via the new :ignore_exceptions option (EppO, jeremyevans)
+
+* Don't modify array with a string and placeholders passed to Dataset#filter or related methods (jeremyevans)
+
+* Speed up Amalgalite adapter (copiousfreetime)
+
+* Fix bound variables on PostgreSQL when using nil and potentially other values (jeremyevans)
+
+* Allow easier overriding of default options used in the validation_helpers plugin (jeremyevans)
+
+* Have Dataset#literal_other call sql_literal on the object if it responds to it (heda, michaeldiamond)
+
+* Fix Dataset#explain in the amalgalite adapter (jeremyevans)
+
+* Have Model.table_name respect table aliases (jeremyevans)
+
+* Allow marshalling of saved model records after calling #marshallable! (jeremyevans)
+
+* one_to_many association methods now make sure that the removed object is currently associated to the receiver (jeremyevans)
+
+* Model association add_ and remove_ methods now have more descriptive error messages (jeremyevans)
+
+* Model association add_ and remove_ methods now make sure passed object is of the correct class (jeremyevans)
+
+* Model association remove_ methods now accept a primary key value and disassociate the associated model object (natewiger, jeremyevans)
+
+* Model association add_ methods now accept a hash and create a new associated model object (natewiger, jeremyevans)
+
+* Dataset#window for PostgreSQL datasets now respects previous windows (jeremyevans)
+
+* Dataset#simple_select_all? now ignores options that don't affect the SQL being issued (jeremyevans)
+
+* Account for table aliases in eager_graph (mluu)
+
+* Add support for MSSQL clustered index creation (mluu)
+
+* Implement insert_select in the MSSQL adapter via OUTPUT. Can be disabled via disable_insert_output. (jfirebaugh, mluu)
+
+* Correct error handling when beginning a transaction fails (jfirebaugh, mluu)
+
+* Correct JDBC binding for Time objects in prepared statements (jfirebaugh, jeremyevans)
+
+* Emulate JOIN USING clause poorly using JOIN ON if the database doesn't support JOIN USING (e.g. MSSQL, H2) (jfirebaugh, jeremyevans)
+
+* Support column aliases in Dataset#group_and_count (jfirebaugh)
+
+* Support preparing insert statements of the form insert(1,2,3) and insert(columns, values) (jfirebaugh)
+
+* Fix add_index for tables in non-default schema (jfirebaugh)
+
+* Allow named placeholders in placeholder literal strings (jeremyevans)
+
+* Allow the force_encoding plugin to work when refreshing (jeremyevans)
+
+* Add Dataset#bind for setting bound variable values before calling #call (jeremyevans)
+
+* Add additional join methods to Dataset: (cross|natural|(natural_)?(full|left|right))_join (jeremyevans)
+
+* Fix use a dataset aggregate methods (e.g. sum) on limited/grouped/etc. datasets (jeremyevans)
+
+* Clear changed_columns when saving new model objects with a database adapter that supports insert_select, such as postgres (jeremyevans)
+
+* Fix Dataset#replace with default values on MySQL, and respect insert-related options (jeremyevans)
+
+* Fix Dataset#lock on PostgreSQL (jeremyevans)
+
+* Fix Dataset#explain on SQLite (jeremyevans)
+
+* Add Dataset#use_cursor to the native postgres adapter, for processing large datasets (jeremyevans)
+
+* Don't ignore Class.inherited in Sequel::Model.inherited (antage) (#277)
+
+* Optimize JDBC::MySQL::DatabaseMethods#last_insert_id to prevent additional queries (tmm1)
+
+* Fix use of MSSQL with ruby 1.9 (cult hero)
+
+* Don't try to load associated objects when the current object has NULL for one of the key fields (jeremyevans)
+
+* No longer require GROUP BY to use HAVING, except on SQLite (jeremyevans)
+
+* Add emulated support for the lack of multiple column IN/NOT IN support in MSSQL and SQLite (jeremyevans)
+
+* Add emulated support for #ilike on MSSQL and H2 (jeremyevans)
+
+* Add a :distinct option for all associations, which uses the SQL DISTINCT clause (jeremyevans)
+
+* Don't require :: prefix for constant lookups in instance_evaled virtual row blocks on ruby 1.9 (jeremyevans)
+
 === 3.5.0 (2009-10-01)
 
 * Correctly literalize timezones in timestamps when using Oracle (jeremyevans)

data/README.rdoc

@@ -75,13 +75,13 @@ Sequel is designed to take the hassle away from connecting to databases and mani
 
 Sequel uses the concept of datasets to retrieve data. A Dataset object encapsulates an SQL query and supports chainability, letting you fetch data using a convenient Ruby DSL that is both concise and flexible.
 
-For example, the following one-liner returns the average GDP for the five biggest countries in the middle east region:
+For example, the following one-liner returns the average GDP for countries in the middle east region:
 
-  DB[:countries].filter(:region => 'Middle East').reverse_order(:area).limit(5).avg(:GDP)
+  DB[:countries].filter(:region => 'Middle East').avg(:GDP)
   
 Which is equivalent to:
 
-  SELECT avg(GDP) FROM countries WHERE region = 'Middle East' ORDER BY area DESC LIMIT 5
+  SELECT avg(GDP) FROM countries WHERE region = 'Middle East'
 
 Since datasets retrieve records only when needed, they can be stored and later reused. Records are fetched as hashes (or custom model objects), and are accessed using an Enumerable interface:
 
@@ -120,8 +120,10 @@ You can specify a block to connect, which will disconnect from the database afte
 
 === Arbitrary SQL queries
 
-  DB << "create table t (a text, b text)"
-  DB << "insert into t values ('a', 'b')"
+You can execute arbitrary SQL code using Database#run:
+
+  DB.run("create table t (a text, b text)")
+  DB.run("insert into t values ('a', 'b')")
 
 You can also create datasets based on raw SQL:
 
@@ -137,6 +139,7 @@ You can also fetch records with raw SQL through the dataset:
 
 You can use placeholders in your SQL string as well:
 
+  name = 'Jim'
   DB['select * from items where name = ?', name].each do |row|
     p row
   end
@@ -407,7 +410,7 @@ Sequel models allow you to use any column as a primary key, and even composite k
   post = Post['ruby', 'hello world']
   post.pk #=> ['ruby', 'hello world']
 
-You can also define a model class that does not have a primary key, but then you lose the ability to update records.
+You can also define a model class that does not have a primary key, but then you lose the ability to easily update records.
 
 A model instance can also be fetched by specifying a condition:
 
@@ -439,9 +442,14 @@ You can read the record values as object attributes (assuming the attribute name
 You can also change record values:
 
   post.title = 'hey there'
+  # or 
+  post.set(:title=>'hey there')
+
+That will just change the value for the object, it will not persist the changes to the database.  To persist the record, call the #save method:
+
   post.save
 
-Another way to change values by using the #update method:
+If you want to modify record values and save the object after doing so, use the #update method:
 
   post.update(:title => 'hey there')
 
@@ -451,7 +459,7 @@ New records can be created by calling Model.create:
 
   post = Post.create(:title => 'hello world')
 
-Another way is to construct a new instance and save it:
+Another way is to construct a new instance and save it later:
 
   post = Post.new
   post.title = 'hello world'
@@ -459,27 +467,30 @@ Another way is to construct a new instance and save it:
 
 You can also supply a block to Model.new and Model.create:
 
-  post = Post.create{|p| p.title = 'hello world'}
-
   post = Post.new do |p|
     p.title = 'hello world'
-    p.save
   end
 
+  post = Post.create{|p| p.title = 'hello world'}
+
 === Hooks
 
 You can execute custom code when creating, updating, or deleting records by defining hook methods. The before_create and after_create hook methods wrap record creation. The before_update and after_update hook methods wrap record updating. The before_save and after_save hook methods wrap record creation and updating. The before_destroy and after_destroy hook methods wrap destruction. The before_validation and after_validation hook methods wrap validation. Example:
 
   class Post < Sequel::Model
     def after_create
+      super
       author.increase_post_count
     end
 
     def after_destroy
+      super
       author.decrease_post_count
     end
   end
 
+Note the use of super if you define your own hook methods.  Almost all Sequel::Model class and instance methods (not just hook methods) can be overridden safely, but you have to make sure to call super when doing so, otherwise you risk breaking things.
+
 For the example above, you should probably use a database trigger if you can.  Hooks can be used for data integrity, but they will only enforce that integrity when you are using the model.  If you plan on allowing any other access to the database, it's best to use database triggers for data integrity.
 
 === Deleting records
@@ -636,7 +647,7 @@ Sequel models also provide a short hand notation for filters:
 
 === Model Validations
 
-You can define a validate method for your model, which save
+You can define a validate method for your model, which #save
 will check before attempting to save the model in the database.
 If an attribute of the model isn't valid, you should add a error
 message for that attribute to the model object's errors. If an
@@ -645,8 +656,8 @@ raise an error or return false depending on how it is configured.
 
   class Post < Sequel::Model
     def validate
-      errors[:name] << "can't be empty" if name.empty?
-      errors[:written_on] << "should be in the past" if written_on >= Time.now
+      errors.add(:name, "can't be empty") if name.empty?
+      errors.add(:written_on, "should be in the past") if written_on >= Time.now
     end
   end
 

data/Rakefile

@@ -168,12 +168,26 @@ begin
     t.spec_opts  = spec_opts.call
   end
   
+  desc "Run integration tests with coverage"
+  Spec::Rake::SpecTask.new("integration_cov") do |t|
+    t.spec_files = Dir["spec/integration/*_test.rb"]
+    t.spec_opts  = spec_opts.call
+    t.rcov, t.rcov_opts = rcov_opts.call
+  end
+  
   %w'postgres sqlite mysql informix oracle firebird mssql'.each do |adapter|
-    desc "Run #{adapter} specs without coverage"
+    desc "Run #{adapter} specs"
     Spec::Rake::SpecTask.new("spec_#{adapter}") do |t|
       t.spec_files = ["spec/adapters/#{adapter}_spec.rb"] + Dir["spec/integration/*_test.rb"]
       t.spec_opts  = spec_opts.call
     end
+
+    desc "Run #{adapter} specs with coverage"
+    Spec::Rake::SpecTask.new("spec_#{adapter}_cov") do |t|
+      t.spec_files = ["spec/adapters/#{adapter}_spec.rb"] + Dir["spec/integration/*_test.rb"]
+      t.spec_opts  = spec_opts.call
+      t.rcov, t.rcov_opts = rcov_opts.call
+    end
   end
 rescue LoadError
 end
@@ -197,3 +211,8 @@ desc "Print Sequel version"
 task :version do
   puts VERS.call
 end
+
+desc "Check syntax of all .rb files"
+task :check_syntax do
+  Dir['**/*.rb'].each{|file| print `#{ENV['RUBY'] || :ruby} -c #{file} | fgrep -v "Syntax OK"`}
+end

data/doc/advanced_associations.rdoc

@@ -196,8 +196,8 @@ Sequel::Model:
   @author = Author.first
   @author.books
 
-If you use an association other than belongs_to in the associated model, things
-are a bit more involved (has_many :through a has_many association):
+If you use an association other than belongs_to in the associated model, you'll have
+to specify some of the :*key options and write a short method.
 
 ActiveRecord:
 
@@ -222,23 +222,7 @@ Sequel::Model:
 
   class Firm < Sequel::Model
     one_to_many :clients
-    one_to_many :invoices, :read_only=>true, \
-      :dataset=>proc{Invoice.eager_graph(:client).filter(:client__firm_id=>pk)}, \
-      :after_load=>(proc do |firm, invs|
-        invs.each do |inv|
-          inv.client.associations[:firm] = inv.associations[:firm] = firm
-        end
-      end), \
-      :eager_loader=>(proc do |key_hash, firms, associations|
-        id_map = key_hash[Firm.primary_key]
-        firms.each{|firm| firm.associations[:invoices] = []} 
-        Invoice.eager_graph(:client).filter(:client__firm_id=>id_map.keys).all do |inv|
-          id_map[inv.client.firm_id].each do |firm|
-            inv.client.associations[:firm] = inv.associations[:firm] = firm
-            firm.associations[:invoices] << inv 
-          end
-        end
-      end)
+    many_to_many :invoices, :join_table=>:clients, :right_key=>:id, :right_primary_key=>:client_id
   end 
 
   class Client < Sequel::Model
@@ -248,55 +232,28 @@ Sequel::Model:
 
   class Invoice < Sequel::Model
     many_to_one :client
-    many_to_one :firm, :key=>nil, :read_only=>true, \
-      :dataset=>proc{Firm.eager_graph(:clients).filter(:clients__id=>client_id)}, \
-      :after_load=>(proc do |inv, firm|
-        # Delete the cached associations from firm, because it only has the
-        # client with this invoice, instead of all clients of the firm
-        inv.associations[:client] = firm.associations.delete(:clients).first
-      end), \
-      :eager_loader=>(proc do |key_hash, invoices, associations|
-        id_map = {}
-        invoices.each do |inv|
-          inv.associations[:firm] = nil
-          inv.associations[:client] = nil
-          (id_map[inv.client_id] ||= []) << inv
-        end
-        Firm.eager_graph(:clients).filter(:clients__id=>id_map.keys).all do |firm|
-          # Delete the cached associations from firm, because it only has the
-          # clients related the invoices being eagerly loaded, instead of all
-          # clients of the firm.
-          firm.associations.delete(:clients).each do |client|
-            id_map[client.pk].each do |inv|
-              inv.associations[:firm] = firm
-              inv.associations[:client] = client
-            end
-          end
-        end
-      end)
+
+    def firm
+      client.firm if client
+    end
   end
-  Firm.find(:first).invoices
 
-It is significantly more code in Sequel Model, but quite a bit of it is setting
-the intermediate associated record (the client) and the reciprocal association
-in the associations cache for each object, which ActiveRecord won't do for you.
-The reason you would want to do this is that then firm.invoices.first.firm or
-firm.invoices.first.client doesn't do another query to get the firm/client.
+  Firm.first.invoices
 
 === Polymorphic Associations
 
-Polymorphic associations are really a design flaw.  The only advantage
-polymorphic associations offer is that they require fewer join tables.
+Sequel discourages the use of polymorphic associations, which is the reason they
+are not supported by default.  All polymorphic associations can be made non-polymorphic
+by using additional tables and/or columns instead of having a column
+containing the associated class name as a string.
 
-Proof by Reductio ad absurdum: If fewer join tables are preferable, then surely
-fewer tables and columns are preferrable, so you might as well store all of
-your data in a single column in a single table if you think polymorphic
-associations are a good idea.
+Polymorphic associations break referential integrity and are significantly more
+complex than non-polymorphic associations, so their use is not recommended unless
+you are stuck with an existing design that uses them.
 
-Compelling Argument: Polymorphic associations are more complex than normal
-associations, and they break referential integrity, so the only reason you
-should use them is if you are already stuck with an existing design that
-uses them.  You should never use them in new code.
+If you must use them, look for the sequel_polymorphic plugin, as it makes using
+polymorphic associations in Sequel about as easy as it is in ActiveRecord.  However,
+here's how they can be done using Sequel's custom associations:
 
 ActiveRecord:
 
@@ -464,12 +421,22 @@ design, but sometimes you have to play with the cards you are dealt).
 === Joining on multiple keys
 
 Let's say you have two tables that are associated with each other with multiple
-keys.  For example:
+keys.  This can now be handled using Sequel's built in composite key support for
+associations:
 
   # Both of these models have an album_id, number, and disc_number fields.
   # All FavoriteTracks have an associated track, but not all tracks have an
   # associated favorite track
   
+  class Track < Sequel::Model
+    many_to_one :favorite_track, :key=>[:disc_number, :number, :album_id], :primary_key=>[:disc_number, :number, :album_id]
+  end
+  class FavoriteTrack < Sequel::Model
+    one_to_many :tracks, :key=>[:disc_number, :number, :album_id], :primary_key=>[:disc_number, :number, :album_id], :one_to_one=>true
+  end
+
+Here's the old way to do it via custom associations:
+
   class Track < Sequel::Model
     many_to_one :favorite_track, \
       :dataset=>(proc do
@@ -572,6 +539,37 @@ without knowing the depth of the tree?
     end)
   end
 
+Note that unlike ActiveRecord, Sequel supports common table expressions, which allows you to use recursive queries.
+The results are not the same as in the above case, as all descendents are stored in a single association,
+but all descendants can be both lazy loaded or eager loaded in a single query (assuming your database
+supports recursive common table expressions):
+
+  class Node < Sequel::Model
+    one_to_many :descendants, :class=>Node, :dataset=>(proc do
+        Node.from(:t).
+        with_recursive(:t, Node.filter(:parent_id=>pk),
+          Node.join(:t, :id=>:parent_id).
+          select(:nodes.*))
+      end),
+      :eager_loader=>(proc do |key_hash, nodes, associations|
+        id_map = key_hash[:id]
+        nodes.each{|n| n.associations[:descendants] = []}
+        Node.from(:t).
+        with_recursive(:t, Node.filter(:parent_id=>id_map.keys).
+           select(:parent_id___root, :id, :parent_id),
+          Node.join(:t, :id=>:parent_id).
+          select(:t__root, :nodes.*)).
+        all.each do |node|
+          if root = id_map[node.values.delete(:root)].first
+            root.associations[:descendants] << node
+          end
+        end
+      end)
+  end
+
+You could modify the code to also store direct children relationships at the same time,
+for functionality similar to the non-common table expression case.
+
 === Joining multiple keys to a single key, through a third table
 
 Let's say you have a database, of songs, lyrics, and artists.  Each song
@@ -614,7 +612,6 @@ tickets, and each ticket has a number of hours associated with it.  You can use
 association support to create a Project association that gives the sum of hours for all
 associated tickets.
 
-
   class Project < Sequel::Model
     one_to_many :tickets
     many_to_one :ticket_hours, :read_only=>true, :key=>:id,
@@ -644,6 +641,6 @@ associated tickets.
   end
 
 Note that it is often better to use a sum cache instead of this approach.  You can implement
-a sum cache using before or after save and delete hooks, or using a database trigger
+a sum cache using after_create and after_delete hooks, or using a database trigger
 (the preferred method if you only have to support one database and that database supports
 triggers).