sequel 3.37.0 → 3.38.0

data/CHANGELOG

@@ -1,3 +1,59 @@
+=== 3.38.0 (2012-08-01)
+
+* Sequel now recognizes the double(x, y) and double(x, y) unsigned MySQL types (Slike9, jeremyevans) (#528)
+
+* The swift subadapters now require swift-db-* instead of swift itself (deepfryed, jeremyevans) (#526)
+
+* Add :textsize option to tinytds adapter to override the default TEXTSIZE (jeremyevans, wardrop) (#525)
+
+* Support an output identifier method in the swift adapter (jeremyevans)
+
+* Add Model#to_hash as an alias to Model#values (jeremyevans)
+
+* When loading multiple pg_* extensions via Database#extension, only reset the conversion procs once (jeremyevans)
+
+* Don't allow model typecasting from string to postgres array, hstore, or composite types (jeremyevans)
+
+* Add pg_typecast_on_load plugin for converting advanced PostgreSQL types on load the {jdbc,do,swift}/postgres adapters (jeremyevans)
+
+* Make all adapters that connect to PostgreSQL store type conversion procs (jeremyevans)
+
+* Add type oid to column schema on PostgreSQL (jeremyevans)
+
+* Add pg_row plugin, for using Sequel::Model classes to represent PostgreSQL row-valued/composite types (jeremyevans)
+
+* Add pg_row_ops extension for DSL support for PostgreSQL row-valued/composite types (jeremyevans)
+
+* Add pg_row extension for dealing with PostgreSQL row-valued/composite types (jeremyevans)
+
+* Allow custom registered array types in the pg_array extension to be Database instance specific (jeremyevans)
+
+* Remove Sequel::SQL::IdentifierMethods (jeremyevans)
+
+* Don't have the schema_dumper extension produce code that relies on the core_extensions (jeremyevans)
+
+* Fix dropping of columns with constraints on Microsoft SQL Server (mluu, jeremyevans) (#515, #518)
+
+* Don't have pg_* extensions add methods to core classes unless the core_extensions extension is loaded (jeremyevans)
+
+* Use real boolean literals on derby 10.7+ (jeremyevans, matthauck) (#514)
+
+* Work around JRuby 1.6 ruby 1.9 mode bug in Time#nsec for Time prepared statement arguments on jdbc (jeremyevans)
+
+* Handle blob prepared statement arguments on jdbc/db2 and jdbc/oracle (jeremyevans)
+
+* Handle blob values in the swift adapter (jeremyevans)
+
+* Handle better nil prepared statement arguments on jdbc (jeremyevans) (#513)
+
+* Make SQL::Blob objects handle as, cast, and lit methods even if the core extensions are not loaded (jeremyevans)
+
+* Make #* with no arguments produce a ColumnAll for Identifier and QualifiedIdentifier (jeremyevans)
+
+* Sequel.expr(:symbol) now returns Identifier, QualifiedIdentifier, or AliasedExpression instead of Wrapper (jeremyevans)
+
+* Treat clob columns as string instead of blob on Derby (jeremyevans) (#509)
+
 === 3.37.0 (2012-07-02)
 
 * Allow specifying eager_graph alias base on a per-call basis using an AliasedExpression (jeremyevans)

data/README.rdoc

@@ -171,7 +171,7 @@ You can also iterate through records one at a time using +each+:
 
 Or perform more advanced stuff:
 
-  names_and_dates = posts.map{|r| [r[:name], r[:date]]}
+  names_and_dates = posts.map([:name, :date])
   old_posts, recent_posts = posts.partition{|r| r[:date] < Date.today - 7}
   
 You can also retrieve the first record in a dataset:
@@ -191,29 +191,29 @@ If the dataset is ordered, you can also ask for the last record:
   
 === Filtering Records
 
-An easy way to filter records is to provide a hash of values to match to +filter+:
+An easy way to filter records is to provide a hash of values to match to +where+:
 
-  my_posts = posts.filter(:category => 'ruby', :author => 'david')
+  my_posts = posts.where(:category => 'ruby', :author => 'david')
   # WHERE category = 'ruby' AND author = 'david'
   
 You can also specify ranges:
 
-  my_posts = posts.filter(:stamp => (Date.today - 14)..(Date.today - 7))
+  my_posts = posts.where(:stamp => (Date.today - 14)..(Date.today - 7))
   # WHERE stamp >= '2010-06-30' AND stamp <= '2010-07-07'
   
 Or arrays of values:
 
-  my_posts = posts.filter(:category => ['ruby', 'postgres', 'linux'])
+  my_posts = posts.where(:category => ['ruby', 'postgres', 'linux'])
   # WHERE category IN ('ruby', 'postgres', 'linux')
   
 Sequel also accepts expressions:
   
-  my_posts = posts.filter{stamp > Date.today << 1}
+  my_posts = posts.where{stamp > Date.today << 1}
   # WHERE stamp > '2010-06-14'
   
 Some adapters will also let you specify Regexps:
 
-  my_posts = posts.filter(:category => /ruby/i)
+  my_posts = posts.where(:category => /ruby/i)
   # WHERE category ~* 'ruby'
   
 You can also use an inverse filter via +exclude+:
@@ -223,22 +223,21 @@ You can also use an inverse filter via +exclude+:
 
 You can also specify a custom WHERE clause using a string:
 
-  posts.filter('stamp IS NOT NULL')
+  posts.where('stamp IS NOT NULL')
   # WHERE stamp IS NOT NULL
 
 You can use parameters in your string, as well:
 
   author_name = 'JKR'
-  posts.filter('(stamp < ?) AND (author != ?)', Date.today - 3, author_name)
+  posts.where('(stamp < ?) AND (author != ?)', Date.today - 3, author_name)
   # WHERE (stamp < '2010-07-11') AND (author != 'JKR')
-  posts.filter{(stamp < Date.today - 3) & ~{:author => author_name}} # same as above
 
 Datasets can also be used as subqueries:
 
-  DB[:items].filter('price > ?', DB[:items].select{avg(price) + 100})
+  DB[:items].where('price > ?', DB[:items].select{avg(price) + 100})
   # WHERE price > (SELECT avg(price) + 100 FROM items)
 
-After filtering you can retrieve the matching records by using any of the retrieval methods:
+After filtering, you can retrieve the matching records by using any of the retrieval methods:
 
   my_posts.each{|row| p row}
   
@@ -248,7 +247,7 @@ See the doc/dataset_filtering.rdoc file for more details.
 
 Counting records is easy using +count+:
 
-  posts.filter(:category.like('%ruby%')).count
+  posts.where(:category.like('%ruby%')).count
   # SELECT COUNT(*) FROM posts WHERE category LIKE '%ruby%'
 
 And you can also query maximum/minimum values via +max+ and +min+:
@@ -275,7 +274,7 @@ Ordering datasets is simple using +order+:
   posts.order(:stamp, :name)
   # ORDER BY stamp, name
 
-Chaining +order+ doesn't work the same as +filter+:
+Chaining +order+ doesn't work the same as +where+:
 
   posts.order(:stamp).order(:name)
   # ORDER BY name
@@ -285,10 +284,27 @@ The +order_append+ method chains this way, though:
   posts.order(:stamp).order_append(:name)
   # ORDER BY stamp, name
   
+The +order_prepend+ method can be used as well:
+
+  posts.order(:stamp).order_prepend(:name)
+  # ORDER BY name, stamp
+  
 You can also specify descending order:
 
-  posts.order(:stamp.desc)
+  posts.reverse_order(:stamp)
   # ORDER BY stamp DESC
+  posts.order(Sequel.desc(:stamp))
+  # ORDER BY stamp DESC
+
+=== Core Extensions
+
+Note the use of <tt>Sequel.desc(:stamp)</tt> in the above example.  Much of Sequel's DSL uses this style, calling methods on the Sequel module that return SQL expression objects.  Sequel also ships with a {core_extensions extension}[link:files/doc/core_extensions_rdoc.html]) that integrates Sequel's DSL better into the ruby language, allowing you to write:
+
+  :stamp.desc
+
+instead of:
+
+  Sequel.desc(:stamp)
 
 === Selecting Columns
 
@@ -299,7 +315,7 @@ Selecting specific columns to be returned is also simple using +select+:
   posts.select(:stamp, :name)
   # SELECT stamp, name FROM posts
 
-Chaining +select+ works like +order+, not +filter+:
+Chaining +select+ works like +order+, not +where+:
 
   posts.select(:stamp).select(:name)
   # SELECT name FROM posts
@@ -313,16 +329,16 @@ As you might expect, there is an +order_append+ equivalent for +select+ called +
 
 Deleting records from the table is done with +delete+:
 
-  posts.filter('stamp < ?', Date.today - 3).delete
+  posts.where('stamp < ?', Date.today - 3).delete
   # DELETE FROM posts WHERE stamp < '2010-07-11'
   
 Be very careful when deleting, as +delete+ affects all rows in the dataset.
-+filter+ first, +delete+ second, unless you want to empty the table:
+Call +where+ first and +delete+ second:
 
   # DO THIS:
-  posts.filter('stamp < ?', Date.today - 7).delete
+  posts.where('stamp < ?', Date.today - 7).delete
   # NOT THIS:
-  posts.delete.filter('stamp < ?', Date.today - 7)
+  posts.delete.where('stamp < ?', Date.today - 7)
 
 === Inserting Records
 
@@ -335,21 +351,21 @@ Inserting records into the table is done with +insert+:
 
 Updating records in the table is done with +update+:
 
-  posts.filter('stamp < ?', Date.today - 7).update(:state => 'archived')
+  posts.where('stamp < ?', Date.today - 7).update(:state => 'archived')
   # UPDATE posts SET state = 'archived' WHERE stamp < '2010-07-07'
 
 You can reference table columns when choosing what values to set:
 
-  posts.filter{|o| o.stamp < Date.today - 7}.update(:backup_number => :backup_number + 1)
+  posts.where{|o| o.stamp < Date.today - 7}.update(:backup_number => :backup_number + 1)
   # UPDATE posts SET backup_number = backup_number + 1 WHERE stamp < '2010-07-07'
 
-As with +delete+, +update+ affects all rows in the dataset, so +filter+ first,
-+update+ second, unless you want to update all rows:
+As with +delete+, +update+ affects all rows in the dataset, so +where+ first,
++update+ second:
 
   # DO THIS:
-  posts.filter('stamp < ?', Date.today - 7).update(:state => 'archived')
+  posts.where('stamp < ?', Date.today - 7).update(:state => 'archived')
   # NOT THIS:
-  posts.update(:state => 'archived').filter('stamp < ?', Date.today - 7)
+  posts.update(:state => 'archived').where('stamp < ?', Date.today - 7)
 
 === Transactions
 
@@ -357,7 +373,7 @@ You can wrap some code in a database transaction using the <tt>Database#transact
 
   DB.transaction do
     posts.insert(:category => 'ruby', :author => 'david')
-    posts.filter('stamp < ?', Date.today - 7).update(:state => 'archived')
+    posts.where('stamp < ?', Date.today - 7).update(:state => 'archived')
   end
 
 If the block does not raise an exception, the transaction will be committed.
@@ -378,11 +394,15 @@ and not raise an exception outside the block, you can raise the
 Sequel makes it easy to join tables:
 
   order_items = DB[:items].join(:order_items, :item_id => :id).
-    filter(:order_items__order_id => 1234)
+    where(:order_items__order_id => 1234)
   # SELECT * FROM items INNER JOIN order_items
   # ON order_items.item_id = items.id 
   # WHERE order_items.order_id = 1234
 
+The important thing to note here is that item_id is automatically qualified with
+the table being joined, and id is automatically qualified with the last table
+joined.
+
 You can then do anything you like with the dataset:
 
   order_total = order_items.sum(:price)
@@ -406,14 +426,14 @@ Using +graph+, you can split the result hashes into subhashes, one per join:
 
 Sequel expects column names to be specified using symbols. In addition, returned hashes always use symbols as their keys. This allows you to freely mix literal values and column references in many cases. For example, the two following lines produce equivalent SQL:
 
-  items.filter(:x => 1)
+  items.where(:x => 1)
   # SELECT * FROM items WHERE (x = 1)
-  items.filter(1 => :x)
+  items.where(1 => :x)
   # SELECT * FROM items WHERE (1 = x)"
 
 Ruby strings are generally treated as SQL strings:
 
-  items.filter(:x => 'x')
+  items.where(:x => 'x')
   # SELECT * FROM items WHERE (x = 'x')
 
 === Qualifying column names
@@ -423,9 +443,9 @@ Column references can be qualified by using the double underscore special notati
   items.literal(:items__price)
   # items.price
 
-Another way to qualify columns is to use the +qualify+ method:
+Another way to qualify columns is to use the <tt>Sequel.qualify</tt> method:
 
-  items.literal(:price.qualify(:items))
+  items.literal(Sequel.qualify(:items, :price))
   # items.price
 
 === Column aliases
@@ -437,9 +457,9 @@ You can also alias columns by using the triple undersecore special notation <tt>
   items.literal(:items__price___p)
   # items.price AS p
 
-Another way to alias columns is to use the +as+ method:
+Another way to alias columns is to use the <tt>Sequel.as</tt> method:
 
-  items.literal(:price.as(:p))
+  items.literal(Sequel.as(:price, :p))
   # price AS p
 
 == Sequel Models
@@ -465,7 +485,7 @@ You can explicitly set the table name or even the dataset used:
 
 If you call +set_dataset+ with a symbol, it assumes you are referring to the table with the same name.  You can also call it with a dataset, which will set the defaults for all retrievals for that model:
 
-  Post.set_dataset DB[:my_posts].filter(:category => 'ruby')
+  Post.set_dataset DB[:my_posts].where(:category => 'ruby')
   Post.set_dataset DB[:my_posts].select(:id, :name).order(:date)
 
 === Model instances
@@ -500,12 +520,12 @@ A single model instance can also be fetched by specifying a condition:
 
 A model class lets you iterate over subsets of records by proxying many methods to the underlying dataset. This means that you can use most of the +Dataset+ API to create customized queries that return model instances, e.g.:
 
-  Post.filter(:category => 'ruby').each{|post| p post}
+  Post.where(:category => 'ruby').each{|post| p post}
 
 You can also manipulate the records in the dataset:
 
-  Post.filter{num_comments < 7}.delete
-  Post.filter(:title.like(/ruby/)).update(:category => 'ruby')
+  Post.where{num_comments < 7}.delete
+  Post.where(Sequel.like(:title, /ruby/)).update(:category => 'ruby')
 
 === Accessing record values
 
@@ -523,10 +543,12 @@ If the record's attributes names are not valid columns in the model's dataset (m
   post[:id] #=> 123
   post[:title] #=> 'hello world'
 
-You can also modify record values using attribute setters or the +set+ method:
+You can also modify record values using attribute setters, the <tt>[]=</tt> method, or the +set+ method:
 
   post.title = 'hey there'
   # or 
+  post[:title] = 'hey there'
+  # or 
   post.set(:title=>'hey there')
 
 That will just change the value for the object, it will not update the row in the database.  To update the database row, call the +save+ method:
@@ -575,7 +597,7 @@ You can execute custom code when creating, updating, or deleting records by defi
 
 Note the use of +super+ if you define your own hook methods.  Almost all <tt>Sequel::Model</tt> 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 modifying the database through model instances.  If you plan on allowing any other access to the database, it's best to use database triggers and constraints for data integrity.
+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 modifying the database through model instances, and even then they are often subject to race conditions.  It's best to use database triggers and constraints to enforce data integrity.
 
 === Deleting records
 
@@ -586,8 +608,8 @@ You can delete individual records by calling +delete+ or +destroy+. The only dif
 
 Records can also be deleted en-masse by calling <tt>Model.delete</tt> and <tt>Model.destroy</tt>. As stated above, you can specify filters for the deleted records:
 
-  Post.filter(:category => 32).delete # => bypasses hooks
-  Post.filter(:category => 32).destroy # => runs hooks
+  Post.where(:category => 32).delete # => bypasses hooks
+  Post.where(:category => 32).destroy # => runs hooks
 
 Please note that if <tt>Model.destroy</tt> is called, each record is deleted 
 separately, but <tt>Model.delete</tt> deletes all matching records with a single 
@@ -632,7 +654,7 @@ All associations add a dataset method that can be used to further filter or reor
   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.where(:subscribers=>0).order(:name).all
 
 === Eager Loading
 
@@ -663,7 +685,7 @@ Associations can be eagerly loaded via +eager+ and the <tt>:eager</tt> associati
   Post.eager(:person).all
 
   # eager is a dataset method, so it works with filters/orders/limits/etc.
-  Post.filter{topic > 'M'}.order(:date).limit(5).eager(:person).all
+  Post.where{topic > 'M'}.order(:date).limit(5).eager(:person).all
   
   person = Person.first
   # Eager loading via :eager (will eagerly load the tags for this person's posts)
@@ -690,16 +712,16 @@ In addition to using +eager+, you can also use +eager_graph+, which will use a s
 You can dynamically customize the eagerly loaded dataset by using using a proc.  This proc is passed the dataset used for eager loading, and should return a modified copy of that dataset:
 
   # Eagerly load only replies containing 'foo'
-  Post.eager(:replies=>proc{|ds| ds.filter(text.like('%foo%'))}).all
+  Post.eager(:replies=>proc{|ds| ds.where(Sequel.like(text, '%foo%'))}).all
 
 This also works when using +eager_graph+, in which case the proc is called with dataset to graph into the current dataset:
 
-  Post.eager_graph(:replies=>proc{|ds| ds.filter(text.like('%foo%'))}).all
+  Post.eager_graph(:replies=>proc{|ds| ds.where(Sequel.like(text, '%foo%'))}).all
 
 You can dynamically customize eager loads for both +eager+ and +eager_graph+ while also cascading, by making the value a single entry hash with the proc as a key, and the cascaded associations as the value:
 
   # Eagerly load only replies containing 'foo', and the person and tags for those replies
-  Post.eager(:replies=>{proc{|ds| ds.filter(text.like('%foo%'))}=>[:person, :tags]}).all
+  Post.eager(:replies=>{proc{|ds| ds.where(Sequel.like(text, '%foo%'))}=>[:person, :tags]}).all
 
 === Extending the underlying dataset
 
@@ -707,7 +729,7 @@ The obvious way to add table-wide logic is to define class methods to the model
 
   class Post < Sequel::Model
     def self.posts_with_few_comments
-      filter{num_comments < 30}
+      where{num_comments < 30}
     end
 
     def self.clean_posts_with_few_comments
@@ -715,27 +737,29 @@ The obvious way to add table-wide logic is to define class methods to the model
     end
   end
 
-You can also implement table-wide logic by defining methods on the dataset using +def_dataset_method+:
+You can also implement table-wide logic by defining methods on the dataset using +dataset_module+:
 
   class Post < Sequel::Model
-    def_dataset_method(:posts_with_few_comments) do
-      filter{num_comments < 30}
-    end
-
-    def_dataset_method(:clean_posts_with_few_comments) do
-      posts_with_few_comments.delete
+    dataset_module do
+      def posts_with_few_comments
+        where{num_comments < 30}
+      end
+
+      def clean_posts_with_few_comments
+        posts_with_few_comments.delete
+      end
     end
   end
 
 This is the recommended way of implementing table-wide operations, and allows you to have access to your model API from filtered datasets as well:
 
-  Post.filter(:category => 'ruby').clean_posts_with_few_comments
+  Post.where(:category => 'ruby').clean_posts_with_few_comments
 
 Sequel models also provide a +subset+ class method that creates a dataset method with a simple filter:
 
   class Post < Sequel::Model
     subset(:posts_with_few_comments){num_comments < 30}
-    subset :invisible, ~:visible
+    subset :invisible, Sequel.~(:visible)
   end
 
 === Model Validations

data/Rakefile

@@ -29,7 +29,7 @@ end
 
 desc "Upload sequel gem to gemcutter"
 task :release=>[:package] do
-  sh %{gem push ./#{NAME}-#{VERS.call}.gem} 
+  sh %{gem push ./#{NAME}-#{VERS.call}.gem}
 end
 
 ### RDoc
@@ -132,14 +132,15 @@ begin
   spec.call("spec_core", Dir["spec/core/*_spec.rb"], "Run core specs")
   spec.call("spec_model", Dir["spec/model/*_spec.rb"], "Run model specs")
   spec.call("_spec_model_no_assoc", Dir["spec/model/*_spec.rb"].delete_if{|f| f =~ /association|eager_loading/}, '')
+  spec_with_cov.call("spec_core_ext", ["spec/core_extensions_spec.rb"], "Run core extensions specs"){|t| t.rcov_opts.concat(%w'--exclude "lib/sequel/([a-z_]+\.rb|adapters|connection_pool|database|dataset|model)"')}
   spec_with_cov.call("spec_plugin", Dir["spec/extensions/*_spec.rb"], "Run extension/plugin specs"){|t| t.rcov_opts.concat(%w'--exclude "lib/sequel/([a-z_]+\.rb|adapters|connection_pool|database|dataset|model)"')}
   spec_with_cov.call("spec_integration", Dir["spec/integration/*_test.rb"], "Run integration tests")
-  
+
   %w'postgres sqlite mysql informix oracle firebird mssql db2'.each do |adapter|
     spec_with_cov.call("spec_#{adapter}", ["spec/adapters/#{adapter}_spec.rb"] + Dir["spec/integration/*_test.rb"], "Run #{adapter} specs"){|t| t.rcov_opts.concat(%w'--exclude "lib/sequel/([a-z_]+\.rb|connection_pool|database|dataset|model|extensions|plugins)"')}
   end
-  
-  task :spec_travis=>[:spec, :spec_plugin, :spec_sqlite] do
+
+  task :spec_travis=>[:spec, :spec_plugin, :spec_core_ext, :spec_sqlite] do
     if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
       ENV['SEQUEL_PG_SPEC_DB'] = "jdbc:postgresql://localhost/sequel_test?user=postgres"
       ENV['SEQUEL_MY_SPEC_DB'] = "jdbc:mysql://localhost/sequel_test?user=root"
@@ -173,7 +174,7 @@ end
 desc "Report code statistics (KLOCs, etc) from the application"
 task :stats do
   STATS_DIRECTORIES = [%w(Code lib/), %w(Spec spec)].map{|name, dir| [ name, "./#{dir}" ] }.select { |name, dir| File.directory?(dir)}
-  require "extra/stats"
+  require "./extra/stats"
   verbose = true
   CodeStatistics.new(*STATS_DIRECTORIES).to_s
 end