sequel 3.35.0 → 3.36.0

data/CHANGELOG

@@ -1,3 +1,81 @@
+=== 3.36.0 (2012-06-01)
+
+* Use Bignum generic type when dumping unsigned integer types that could potentially overflow 32-bit signed integer values (stu314)
+
+* Support :transform option in the nested_attributes plugin, for automatically preprocessing input hashes (chanks)
+
+* Support :unmatched_pk option in the nested_attributes plugin, can be set to :create for associated objects with natural keys (chanks)
+
+* Support composite primary keys in the nested_attributes plugin (chanks)
+
+* Allow Model#from_json in the json_serializer plugin to use set_fields if a :fields option is given (jeremyevans)
+
+* Support :using option to set_column_type on PostgreSQL, to force a specific conversion from the old value to the new value (jeremyevans)
+
+* Drop indexes in the reverse order that they were added in the schema dumper (jeremyevans)
+
+* Add :index_names option to schema dumper method, can be set to false or :namespace (stu314, jeremyevans)
+
+* Add Database#global_index_namespace? for checking if index namespace is global or per table (jeremyevans)
+
+* Fix typecasting of time columns on jdbc/postgres, before could be off by a millisecond (jeremyevans)
+
+* Add document explaining Sequel's object model (jeremyevans)
+
+* Attempt to detect more disconnect errors in the mysql2 adapter (jeremyevans)
+
+* Add is_current? and check_current to the migrators, for checking/raising if there are unapplied migrations (pvh, jeremyevans) (#487)
+
+* Add a jdbc subadapter for the Progress database (Michael Gliwinski, jeremyevans)
+
+* Add pg_inet extension, for working with PostgreSQL inet and cidr types (jeremyevans)
+
+* Fix bug in model column setters when passing an object that raises an exception for ==('') (jeremyevans)
+
+* Add eager_each plugin, which makes each on an eagerly loaded dataset do eager loading (jeremyevans)
+
+* Fix bugs when parsing foreign keys for tables with explicit schema on PostgreSQL (jeremyevans)
+
+* Remove Database#case_sensitive_like on SQLite (jeremyevans)
+
+* Remove Database#single_value in the native sqlite adapter (jeremyevans)
+
+* Make Dataset#get work with nil and false arguments (jeremyevans)
+
+* Make json_serializer plugin respect :root=>:collection and :root=>:instance options (jeremyevans)
+
+* Support savepoints in prepared transactions on MySQL 5.5.23+ (jeremyevans)
+
+* Add pg_json extension, for working with PostgreSQL 9.2's new json type (jeremyevans)
+
+* In the optimistic locking plugin, make refresh and save after a failed save work correctly (jeremyevans)
+
+* Support partial indexes on Microsoft SQL Server 2008 (jeremyevans)
+
+* Make Database#call pass blocks (jeremyevans)
+
+* Support :each when preparing statements, useful for iterating over large datasets (jeremyevans)
+
+* Support :if_exists and :cascade options when dropping indexes on PostgreSQL (jeremyevans)
+
+* Support :concurrently option when adding and dropping indexes on PostgreSQL (jeremyevans)
+
+* Make Database#transaction on PostgreSQL recognize :synchronous, :read_only, and :deferrable options (jeremyevans)
+
+* Support :sql_mode option when connecting to MySQL (jeremyevans)
+
+* Apply :timeout MySQL connection setting on do, jdbc, and swift adapters (jeremyevans)
+
+* Don't set Sequel::Model.db automatically when creating an anonymous class with an associated database object (jeremyevans)
+
+* Add :connection_handling=>:queue option to the threaded connection pools, may reduce chance of stale connections (jeremyevans) (#481)
+
+* Handle JRuby 1.7 exception handling changes when connecting in the jdbc adapter (jeremyevans) (#477)
+
+* Make *_to_one association setters be noops if you pass a value that is the same as the cached value (jeremyevans)
+
+* Make Model#refresh return self when using dirty plugin (jeremyevans)
+
 === 3.35.0 (2012-05-01)
 
 * Correctly handle parsing schema for tables in other databases on MySQL (jeremyevans)

data/Rakefile

@@ -128,15 +128,15 @@ begin
   end
 
   task :default => [:spec]
-  spec_with_cov.call("spec", Dir["spec/{core,model}/*_spec.rb"], "Run core and model specs"){|t| t.rcov_opts.concat(%w'--exclude "lib/sequel/adapters/([a-ln-z]|m[a-np-z])"')}
+  spec_with_cov.call("spec", Dir["spec/{core,model}/*_spec.rb"], "Run core and model specs"){|t| t.rcov_opts.concat(%w'--exclude "lib/sequel/(adapters/([a-ln-z]|m[a-np-z])|extensions/core_extensions)"')}
   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_plugin", Dir["spec/extensions/*_spec.rb"], "Run extension/plugin specs")
+  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")
+    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
 
   desc "Run model specs without the associations code"

data/bin/sequel

@@ -162,10 +162,12 @@ begin
     start_time = Time.now
     TO_DB = connect_proc[db2]
     same_db = DB.database_type==TO_DB.database_type
+    index_opts = {:same_db=>same_db}
+    index_opts[:index_names] = :namespace if !DB.global_index_namespace? && TO_DB.global_index_namespace?
 
     puts "Databases connections successful"
     schema_migration = eval(DB.dump_schema_migration(:indexes=>false, :same_db=>same_db))
-    index_migration = eval(DB.dump_indexes_migration(:same_db=>same_db))
+    index_migration = eval(DB.dump_indexes_migration(index_opts))
     fk_migration = eval(DB.dump_foreign_key_migration(:same_db=>same_db))
     puts "Migrations dumped successfully"
 

data/doc/advanced_associations.rdoc

@@ -96,25 +96,168 @@ necessary for polymorphic associations).  Inside the <tt>:eager_loader</tt>
 proc, you should get the related objects and populate the
 associations cache for all objects in the array of records.  The hash
 of dependent associations is available for you to cascade the eager
-loading down multiple levels, but it is up to you to use it.  The
-key_hash is a performance enhancement that is used by the default
+loading down multiple levels, but it is up to you to use it.
+
+The key_hash is a performance enhancement that is used by the default
 association loaders and is also available to you.  It is a hash with keys being
 foreign/primary key symbols in the current table, and the values
 being hashes where the key is foreign/primary key values and values
 being arrays of current model objects having the foreign/primary key
 value associated with the key.  This is hard to visualize, so I'll
-give an example:
-    
-  album1 = Album.load(:id=>1, :artist_id=>2)
-  album2 = Album.load(:id=>3, :artist_id=>2)
+give an example.  Let's say you have the following associations
+
   Album.many_to_one :artist
   Album.one_to_many :tracks
-  Album.eager(:band, :tracks).all
-  # The key_hash provided to the :eager_loader proc would be:
-  {:id=>{1=>[album1], 3=>[album2]}, :artist_id=>{2=>[album1, album2]}}
+    
+and the following two albums in the database:
+
+  album1 = Album.create(:artist_id=>3) # id: 1
+  album2 = Album.create(:artist_id=>3) # id: 2
+
+If you try to eager load this dataset:
+
+  Album.eager(:artist, :tracks).all
+
+Then the key_hash provided to the :eager_loader proc would be:
+
+  {:id=>{1=>[album1], 2=>[album2]}, :artist_id=>{3=>[album1, album2]}}
+
+Let's break down the reason for the makeup of this key_hash.  The hash has keys for
+each of foreign/primary keys used in the association.  In this case, the artist
+association needs the artist_id foreign key (since it is a many_to_one), and the
+tracks association needs the id primary key (since it is a one_to_many).
+
+If you only eagerly loaded the artist association:
+
+  Album.eager(:artist).all
+
+Then the key_hash would only contain artist_id information:
 
-Using these options, you can build associations that Sequel doesn't natively support,
-and still be able to use the same eager loading features that you are used to.
+  {:artist_id=>{3=>[album1, album2]}}
+ 
+Likewise, if you only eagerly loaded the tracks association:
+
+  Album.eager(:tracks).all
+
+Then the key_hash would only contain id information:
+
+  {:id=>{1=>[album1], 2=>[album2]}}
+
+Now, the eager loader for the artist association is only going to care about the
+value of the artist_id key in the hash, so it's going to do the equivalent of:
+
+  artist_id_map = key_hash[:artist_id] # {3=>[album1, album2]}
+
+The artist_id_map contains a mapping of artist_id values to arrays of
+album objects.  Since it only has a single entry with a key of 3, when eagerly
+loading the artists, you only need to look for artists that have an id of 3.
+
+  artists = Artist.where(:id=>artist_id_map.keys).all
+
+When the artists are retrieved, you can iterate over them, find entries
+with matching keys, and manually associate them to the albums:
+
+  artists.each do |artist|
+    # Find related albums using the artist_id_map
+    if albums = artist_id_map[artist.id]
+      # Iterate over the albums
+      albums.each do |album|
+        # Manually set the artist association for each album
+        album.associations[:artist] = artist
+      end
+    end
+  end
+
+Similarly, the eager loader for the tracks association is only going to care about the
+value of the id key in the hash:
+
+  id_map = key_hash[:id] # {1=>[album1], 2=>[album2]}
+
+Now the id_map contains a mapping of id values to arrays of album objects (in this
+case each array only has a single object, because id is the primary key).  So when
+looking for tracks to eagerly load, you only need to look for ones that have an
+album_id of 1 or 2:
+
+  tracks = Track.where(:album_id=>id_map.keys).all
+
+When the tracks are retrieved, you can iterate over them, find entries with matching
+keys, and manually associate them to the albums:
+
+  tracks.each do |track|
+    if albums = id_map[track.album_id]
+      albums.each do |album|
+        album.associations[:tracks] << track
+      end
+    end
+  end
+
+=== Two basic example eager loaders
+
+Putting the code in the above examples together, you almost have enough for a basic
+working eager loader.  The main important thing that is missing is you need to set
+initial values for the eagerly loaded associations.  For the artist association, you
+need to initial the values to nil:
+
+  # rows here is the :rows entry in the hash passed to the eager loader
+  rows.each{|album| album.associations[:artist] = nil}
+  
+For the tracks association, you set the initial value to an empty array:
+
+  rows.each{|album| album.associations[:track] = []}
+
+These are done so that if an album currently being loaded doesn't have an associated
+artist or any associated tracks, the lack of them will be cached, so calling the
+artist or tracks method on the album will not do another database lookup.
+
+So putting everything together, the artist eager loader looks like:
+
+  :eager_loader=>(proc do |eo_opts|
+    eo_opts[:rows].each{|album| album.associations[:artist] = nil}
+    artist_id_map = eo_opts[:key_hash][:artist_id]
+    Artist.where(:id=>artist_id_map.keys).all do |artist|
+      if albums = artist_id_map[artist.id]
+        albums.each do |album|
+          album.associations[:artist] = artist
+        end
+      end
+    end
+  end)
+
+and the tracks eager loader looks like:
+
+  :eager_loader=>(proc do |eo_opts|
+    eo_opts[:rows].each{|album| album.associations[:tracks] = []}
+    id_map = eo_opts[:key_hash][:id]
+    Track.where(:id=>id_map.keys).all do |tracks|
+      if albums = id_map[track.album_id]
+        albums.each do |album|
+          album.associations[:tracks] << track
+        end
+      end
+    end
+  end)
+
+Now, these are both overly simplistic eager loaders that don't respect cascaded
+associations or any of the association options.  But hopefully they both
+provide simple examples that you can more easily build and learn from, as 
+the custom eager loaders described later in this page are more complex.
+
+Basically, the eager loading steps can be broken down into:
+
+1. Set default association values (nil/[]) for each of the current objects
+2. Build a custom key map mapping foreign/primary key values to arrays of
+   current objects (using the key_hash)
+3. Return just related associated objects by filtering the associated class
+   to include only matching values
+4. Iterating over the returned associated objects, indexing into the custom key
+   map using the foreign/primary key value in the associated object to get
+   current values associated to that specific object.
+5. For each of those current values, updating the cached association value to
+   include that specific object.
+
+Using the :eager_loader proc, you should be able to eagerly load all associations
+that can be eagerly loaded, even if Sequel doesn't natively support such eager
+loading.
 
 == ActiveRecord associations
 

data/doc/migration.rdoc

@@ -534,6 +534,24 @@ with an empty database, and attempt to recreate the schema using:
 
   sequel -m db/migrations postgres://host/database
 
+== Checking for Current Migrations
+
+In your application code, you may want to check that you are up to date in
+regards to migrations (i.e. you don't have any unapplied migrations).  Sequel
+offers two separate methods to do that.  The first is Sequel::Migrator.check_current.
+This method raises an exception if there are outstanding migrations that need to
+be run.  The second is Sequel::Migrator.is_current?, which returns true if there
+are no outstanding migrations, and false if there are outstanding migrations.
+
+If you want to ensure that your application code is up to date, you may want to
+add the following code after connecting to your database:
+
+  Sequel.extension :migration
+  Sequel::Migrator.check_current(DB, '/path/to/migrations')
+
+This will cause your application to raise an error when you start it if you have
+any outstanding migrations.
+
 == Old-style migration classes
 
 Before the <tt>Sequel.migration</tt> DSL was introduced, Sequel used classes

data/doc/object_model.rdoc

@@ -0,0 +1,541 @@
+= The Sequel Object Model
+
+Sequel's dataset layer is mostly structured as an DSL, so it often obscures
+what actual objects are being used.  For example, you don't usually create
+Sequel objects by calling #new on the object's class (other than Sequel::Model
+subclasses).  However, just as almost everything in ruby is an object, all 
+the methods you call in Sequel deal with objects behind the scenes.
+
+There are five main types of Sequel-specific objects that you deal with in
+Sequel:
+
+* Sequel::Database
+* Sequel::Dataset
+* Sequel::Model
+* Standard Ruby Types
+* Sequel::SQL::Expression (and subclasses)
+
+== Sequel::Database
+
+Sequel::Database is the main Sequel object that you deal with.  It's usually
+created by the Sequel.connect method:
+
+  DB = Sequel.connect('postgres://host/database')
+
+A Sequel::Database object represents the database you are connecting to.
+Sequel::Database handles things like Sequel::Dataset creation,
+
+  dataset = DB[:table]
+
+schema modification,
+
+  DB.create_table(:table) do
+    primary_key :id
+    String :name
+  end
+
+and transactions:
+
+  DB.transaction do
+    DB[:table].insert(:column=>value)
+  end
+
+Sequel::Database#literal can be used to take any object that Sequel handles
+and literalize the object to an SQL string fragment:
+
+  DB.literal(DB[:table]) # (SELECT * FROM "table")
+
+== Sequel::Dataset
+
+Sequel::Dataset objects represent SQL queries, or more generally, they represent
+abstract collections of rows in the database.  They are usually created from
+a Sequel::Database object:
+
+  dataset = DB[:table]         # SELECT * FROM "table"
+  dataset = DB.from(table)     # SELECT * FROM "table"
+  dataset = DB.select(:column) # SELECT "column"
+
+Most Sequel::Dataset methods return modified copies of the receiver, and the
+general way to build queries in Sequel is via a method chain:
+
+  dataset = DB[:test].
+              select(:column1, :column2).
+              where(:column3 => 4).
+              order(:column5)
+
+Such a method chain is a more direct way of doing:
+
+  dataset = DB[:test]
+  dataset = dataset.select(:column1, :column2)
+  dataset = dataset.where(:column3 => 4)
+  dataset = dataset.order(:column5)
+
+When you are ready to execute your query, you call one of the Sequel::Dataset
+action methods.  For returning rows, you can do:
+
+  dataset.first
+  dataset.all
+  dataset.each{|row| row}
+
+For inserting, updating, or deleting rows, you can do:
+
+  dataset.insert(:column=>value)
+  dataset.update(:column=>value)
+  dataset.delete
+
+All datasets are related to their database object, which you can access via
+the Sequel::Dataset#db method:
+
+  dataset.db # => DB
+
+== Sequel::Model
+
+Sequel::Model objects are wrappers around a particular Sequel::Dataset object that
+add custom behavior, both custom behavior for the entire set of rows in the dataset
+(the model's class methods), custom behavior for a subset of rows in the dataset
+(the model's dataset methods), and custom behavior for single rows in the dataset
+(the model's instance methods).
+
+Unlike most other Sequel objects, Sequel::Model classes and instances are
+generally created by the user using standard ruby syntax:
+
+  class Album < Sequel::Model
+  end
+  album = Album.new
+
+All model classes are related to their Sequel::Dataset object, which you
+can access via the Sequel::Model.dataset method:
+
+  Album.dataset # SELECT * FROM "albums"
+
+Additionally, all model classes are related to their dataset's Sequel::Database
+object, which you can access via the Sequel::Model.db method:
+
+  Album.db # => DB
+
+== Standard Ruby Types
+
+Where possible, Sequel uses ruby's standard types to represent SQL concepts.
+In the examples here, the text to the right side of the # sign is the output
+if you pass the left side to Sequel::Database#literal.
+
+=== Symbol
+
+For example, ruby symbols represent SQL identifiers (tables, columns, schemas):
+
+  :table  # "table"
+  :column # "column"
+
+However, they can also represent qualified identifiers by including a double
+underscore inside a symbol:
+
+  :table__column # "table"."column"
+
+They can also represent an aliased identifier by including a triple underscore
+inside a symbol:
+
+  :column___alias # "column" AS "alias"
+
+You can combine both qualification and aliasing by using a double underscore
+and a triple underscore:
+
+  :table__column___alias # "table"."column" AS "alias"
+
+=== Integer, Float, BigDecimal, String, Date, Time, DateTime
+
+Ruby's Integer, Float, BigDecimal, String, Date, Time, and DateTime classes
+represent similar types in SQL:
+
+  1                     # 1
+  1.0                   # 1.0
+  BigDecimal.new('1.0') # 1.0
+  "string"              # 'string'
+  Date.new(2012, 5, 6)  # '2012-05-06'
+  Time.now              # '2012-05-06 10:20:30'
+  DateTime.now          # '2012-05-06 10:20:30'
+
+=== Hash
+
+Sequel generally uses hash objects to represent equality:
+
+  {:column => 1} # ("column" = 1)
+
+However, if you use in array as the hash value, it will usually be used to represent inclusion:
+
+  {:column => [1, 2, 3]} # ("column" IN (1, 2, 3))
+
+You can also use a Sequel::Dataset instance as the hash value, which will be used to
+represent inclusion in the subselect:
+
+  {:column => DB[:table].select(:column)} # ("column" IN (SELECT "column" FROM "table"))
+
+If you pass true, false, or nil as the hash value, it will be used to represent identity:
+
+  {:column => nil} # ("column" IS NULL)
+
+If you pass a Range object, it will be used as the bounds for a greater than and less than
+operation:
+
+  {:column => 1..2} # (("column" >= 1) AND ("column" <= 2))
+  {:column => 1...3} # (("column" >= 1) AND ("column" < 3))
+
+If you pass a Regexp object as the value, it will be used as a regular expression
+operation (only supported on PostgreSQL and MySQL currently):
+
+  {:column => /a.*b/} # ("column" ~ 'a.*b')
+
+=== Array
+
+Sequel generally treats arrays as an SQL value list:
+
+  [1, 2, 3] # (1, 2, 3)
+
+However, if all members of the array are arrays with two members, then the array is treated like
+a hash:
+
+   [[:column, 1]] # ("column" = 1)
+
+The advantage of using an array over a hash for such a case is that a hash cannot include
+multiple objects with the same key, while the array can.
+
+== Sequel::SQL::Expression (and subclasses)
+
+If Sequel needs to represent an SQL concept that does not map directly to an existing
+ruby class, it will generally use a Sequel::SQL::Expression subclass to represent that
+concept.
+
+=== Sequel::LiteralString
+
+Sequel::LiteralString is not actually a Sequel::SQL::Expression subclass.  It is
+a subclass of String, but it is treated specially by Sequel, in that it is treated
+as literal SQL code, instead of as an SQL string that needs to be escaped:
+
+  Sequel::LiteralString.new("co'de") # co'de
+
+The following shortcuts exist for creating Sequel::LiteralString objects:
+
+  Sequel.lit("co'de")
+  "co'de".lit
+
+=== Sequel::SQL::Blob
+
+Sequel::SQL::Blob is also a String subclass, but it is treated as an SQL blob
+instead of an SQL string, as SQL blobs often have different literalization rules
+than SQL strings do:
+
+  Sequel::SQL::Blob.new("blob")
+
+The following shortcuts exist for creating Sequel::SQL::Blob objects:
+
+  Sequel.blob("blob")
+  "blob".to_sequel_blob
+
+=== Sequel::SQLTime
+
+Sequel::SQLTime is a Time subclass.  However, it is treated specially by Sequel
+in that only the time component is literalized, not the date part.  This type
+is used to represent SQL time types, which do not contain date information.
+
+  Sequel::SQLTime.create(10, 20, 30) # "10:20:30"
+
+=== Sequel::SQL::ValueList
+
+Sequel::SQL::ValueList objects always represent SQL value lists.  Most ruby arrays
+represent value lists in SQL, except that arrays of two-element arrays are treated
+similar to hashes.  Such arrays can be wrapped in this class to ensure they are
+treated as value lists.  This is important when doing a composite key IN lookup,
+which some databases support.  Sequel::SQL::ValueList is an ::Array subclass with
+no additional behavior, so it can be instantiated like a normal array:
+
+  Sequel::SQL::ValueList.new([[1, 2], [3, 4]]) # ((1, 2), (3, 4))
+
+In old versions of Sequel, these objects often needed to be created manually,
+but in newer versions of Sequel, they are created automatically in most cases
+where they are required.
+
+The following shortcuts exist for creating Sequel::SQL::ValueList objects:
+
+  Sequel.value_list([[1, 2], [3, 4]])
+  [[1, 2], [3, 4]].sql_value_list
+
+=== Sequel::SQL::Identifier
+
+Sequel::SQL::Identifier objects represent single identifiers.  The main reason for
+their existance is that they are not checked for double or triple underscores, so no
+automatic qualification or aliasing happens for them:
+
+  Sequel::SQL::Identifier.new(:col__umn) # "col__umn"
+
+The following shortcuts exist for creating Sequel::SQL::Identifier objects:
+
+  Sequel.identifier(:col__umn)
+  :col__umn.identifier
+
+=== Sequel::SQL::QualifiedIdentifier
+
+Sequel::SQL::QualifiedIdentifier objects represent qualified identifiers:
+
+  Sequel::SQL::QualifiedIdentifier.new(:table, :column) # "table"."column"
+
+The following shortcuts exist for creating Sequel::SQL::QualifiedIdentifier objects:
+
+  Sequel.qualify(:table, :column)
+  :column.qualify(:table)
+
+=== Sequel::SQL::AliasedExpression
+
+Sequel::SQL::AliasedExpression objects represent aliased expressions in SQL.  The alias
+is treated as an identifier, but the expression can be an arbitrary Sequel expression:
+
+  Sequel::SQL::AliasedExpression.new(:column, :alias) # "column" AS "alias"
+
+The following shortcuts exist for creating Sequel::SQL::AliasedExpression objects:
+
+  Sequel.as(:column, :alias)
+  :column.as(:alias)
+  
+=== Sequel::SQL::ComplexExpression
+
+Sequel::SQL::ComplexExpression objects mostly represent SQL operations with arguments.
+There are separate subclasses for representing boolean operations such as AND and OR
+(Sequel::SQL::BooleanExpression), mathematical operations such as + and -
+(Sequel::SQL::NumericExpression), and string operations such as || and LIKE
+(Sequel::SQL::StringExpression).
+
+  Sequel::SQL::BooleanExpression.new(:OR, :col1, :col2) # ("col1" OR "col2")
+  Sequel::SQL::NumericExpression.new(:+, :column, 2) # ("column" + 2)
+  Sequel::SQL::StringExpression.new(:"||", :column, "b") # ("column" || 'b')
+
+There are many shortcuts for creating Sequel::SQL::ComplexExpression objects:
+
+  Sequel.or(:col1, :col2)
+  :col1 | :col2
+
+  Sequel.+(:column, 2)
+  :column + 2
+
+  Sequel.join([:column, 'b'])
+  :column + 'b'
+
+=== Sequel::SQL::CaseExpression
+
+Sequel::SQL::CaseExpression objects represent SQL CASE expressions, which represent
+branches in the database, similar to ruby case expressions.  Like ruby's case
+expressions, these case expressions can have a implicit value you are comparing
+against:
+
+  Sequel::SQL::CaseExpression.new({2=>1}, 0, :a) # CASE "a" WHEN 2 THEN 1 ELSE 0 END
+
+Or they can treat each condition separately:
+ 
+  Sequel::SQL::CaseExpression.new({{:a=>2}=>1}, 0) # CASE WHEN ("a" = 2) THEN 1 ELSE 0 END
+
+In addition to providing a hash, you can also provide an array of two-element arrays:
+
+  Sequel::SQL::CaseExpression.new([[2, 1]], 0, :a) # CASE "a" WHEN 2 THEN 1 ELSE 0 END
+
+The following shortcuts exist for creating Sequel::SQL::CaseExpression objects:
+
+  Sequel.case({2=>1}, 0, :a)
+  Sequel.case({{:a=>2}=>1}, 0)
+
+  {2=>1}.case(0, :a)
+  {{:a=>2}=>1}.case(0)
+
+=== Sequel::SQL::Cast
+
+Sequel::SQL::Cast objects represent CAST expressions in SQL, which does explicit
+typecasting in the database.  With Sequel, you provide the expression to typecast
+as well as the type to cast to.  The type can either be a generic type, given as
+a ruby class:
+
+  Sequel::SQL::Cast.new(:a, String) # (CAST "a" AS text)
+
+or a specific type, given as a symbol or string:
+
+  Sequel::SQL::Cast.new(:a, :int4) # (CAST "a" AS int4)
+
+The following shortcuts exist for creating Sequel::SQL::Cast objects:
+
+  Sequel.cast(:a, String)
+  Sequel.cast(:a, :int4)
+
+  :a.cast(String)
+  :a.cast(:int4)
+
+=== Sequel::SQL::ColumnAll
+
+Sequel::SQL::ColumnAll objects represent the selection of all columns from a
+table.  They are pretty much only used as arguments to one of the Dataset select
+methods, and are not used much anymore since Dataset#select_all was expanded to
+take arguments.  Still, it's possible they are still useful in some code:
+
+  Sequel::SQL::ColumnAll.new(:table) # "table".*
+
+The following shortcut exists for creating Sequel::SQL::Cast objects:
+
+  :table.*
+
+=== Sequel::SQL::Constant
+
+Sequel::SQL::Constant objects represent constants or psuedo-constants in SQL,
+such as TRUE, NULL, and CURRENT_TIMESTAMP.  These are not designed to be created
+or used by the end user, but some existing values are predefined under the
+Sequel namespace:
+
+  Sequel::CURRENT_TIMESTAMP # CURRENT_TIMESTAMP
+
+These objects are usually used as values in queries:
+
+  DB[:table].insert(:time=>Sequel::CURRENT_TIMESTAMP)
+
+=== Sequel::SQL::Function
+
+Sequel::SQL::Function objects represents database function calls, which take a function
+name and any arguments:
+
+  Sequel::SQL::Function.new(:func, :a, 2) # func("a", 2)
+
+The following shortcuts exist for creating Sequel::SQL::Function objects:
+
+  Sequel.function(:func, :a, 2)
+  :func.sql_function(:a, 2)
+
+=== Sequel::SQL::JoinClause
+
+Sequel::SQL::JoinClause objects represent SQL JOIN clauses.  They are usually
+not created manually, as the Dataset join methods create them automatically.
+
+=== Sequel::SQL::PlaceholderLiteralString
+
+Sequel::SQL::PlaceholderLiteralString objects represent a literal SQL string
+with placeholders for variables.  There are three types of these objects.
+The first type uses question marks with multiple placeholder value objects:
+
+  Sequel::SQL::PlaceholderLiteralString.new('? = ?', [:a, 1]) # "a" = 1
+
+The second uses named placeholders with colons and a hash of placeholder
+value objects:
+
+  Sequel::SQL::PlaceholderLiteralString.new(':b = :v', [{:b=>:a, :v=>1}]) # "a" = 1
+
+The third uses an array instead of a string, with multiple placeholder
+objects, each one going in between the members of the array:
+
+  Sequel::SQL::PlaceholderLiteralString.new(['', ' = '], [:a, 1]) # "a" = 1
+
+For any of these three forms, you can also include a third argument for whether
+to include parentheses around the string:
+
+  Sequel::SQL::PlaceholderLiteralString.new('? = ?', [:a, 1], true) # ("a" = 1)
+
+The following shortcuts exist for creating Sequel::SQL::PlaceholderLiteralString
+objects:
+
+  Sequel.lit('? = ?', :a, 1)
+  Sequel.lit(':b = :v', :b=>:a, :v=>1)
+  Sequel.lit(['', ' = '], :a, 1)
+
+  '? = ?'.lit(:a, 1)
+  ':b = :v'.lit(:b=>:a, :v=>1)
+
+=== Sequel::SQL::OrderedExpression
+
+Sequel::SQL::OrderedExpression objects represent ascending or descending sorts,
+used by the Dataset order methods.  They take an expression, and whether to sort
+it ascending or descending:
+
+  Sequel::SQL::OrderedExpression.new(:a) # "a" DESC
+  Sequel::SQL::OrderedExpression.new(:a, false) # "a" ASC
+
+Additionally, they take an options hash, which can be used to specify how nulls
+can be sorted:
+
+  Sequel::SQL::OrderedExpression.new(:a, true, :nulls=>:first) # "a" DESC NULLS FIRST
+  Sequel::SQL::OrderedExpression.new(:a, false, :nulls=>:last) # "a" ASC NULLS LAST
+
+The following shortcuts exist for creating Sequel::SQL::OrderedExpression objects:
+
+  Sequel.asc(:a)
+  Sequel.desc(:a)
+  Sequel.asc(:a, :nulls=>:first)
+  Sequel.desc(:a, :nulls=>:last)
+
+  :a.asc
+  :a.desc
+  :a.asc(:nulls=>:first)
+  :a.desc(:nulls=>:last)
+
+=== Sequel::SQL::Subscript
+
+Sequel::SQL::Subscript objects represent SQL database array access.  They take an
+expression and an array of indexes:
+
+  Sequel::SQL::Subscript.new(:a, [1]) # "a"[1]
+  Sequel::SQL::Subscript.new(:a, [1, 2]) # "a"[1, 2]
+
+The following shortcuts exist for creating Sequel::SQL::Subscript objects:
+
+  Sequel.subscript(:a, 1)
+  Sequel.subscript(:a, 1, 2)
+
+  :a.sql_subscript(1)
+  :a.sql_subscript(1, 2)
+  
+=== Sequel::SQL::VirtualRow
+
+Sequel::SQL::VirtualRow is a BasicObject subclass that is the backbone behind the
+block expression support:
+
+  DB[:table].filter{a < 1}
+
+In the above code, the block is instance-evaled instead a VirtualRow instance.
+
+These objects are usually not instantiated manually.  See the
+{Virtual Row Guide}[link:files/doc/virtual_rows_rdoc.html] for details.
+
+=== Sequel::SQL::Window
+
+Sequel::SQL::Window objects represent the windows used by Sequel::SQL::WindowFunction.
+They use a hash-based API, supporting the :frame, :order, :partition, and :window
+options:
+
+  Sequel::SQL::Window.new(:order=>:a) # (ORDER BY "a")
+  Sequel::SQL::Window.new(:parition=>:a) # (PARTITION BY "a")
+
+  Sequel::SQL::Window.new(:parition=>:a, :frame=>:all)
+  # (PARTITION BY "a" ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING)
+
+=== Sequel::SQL::WindowFunction
+
+Sequel::SQL::WindowFunction objects represent SQL window function calls.  These
+just combine a Sequel::SQL::Function with a Sequel::SQL::Window:
+
+  function = Sequel::SQL::Function.new(:f, 1)
+  window = Sequel::SQL::Window.new(:order=>:a)
+  Sequel::SQL::WindowFunction.new(function, window) # f(1) OVER (ORDER BY "a")
+
+Virtual rows offer a shortcut for creating Sequel::SQL::Window objects.
+
+=== Sequel::SQL::Wrapper
+
+Sequel::SQL::Wrapper objects wrap arbitrary objects so that they can be used
+in Sequel expressions:
+
+  o = Object.new
+  def o.sql_literal(ds) "foo" end
+  Sequel::SQL::Wrapper.new(o) # foo
+
+The advantage of wrapping the object is that you can the call Sequel methods
+on the wrapper that would not be defined on the object itself:
+
+  Sequel::SQL::Wrapper.new(o) + 1 # (foo + 1)
+
+You can use the Sequel.expr method to wrap any object:
+
+  Sequel.expr(o)
+
+However, note that that does not necessarily return a Sequel::SQL::Wrapper
+object, it may return a different class of object, such as a
+Sequel::SQL::ComplexExpression subclass object.
+