sequel 3.37.0 → 3.38.0

data/doc/association_basics.rdoc

@@ -345,7 +345,7 @@ The association dataset is just like any other Sequel dataset, in that
 it can be further filtered, ordered, etc.:
 
   @artist.albums_dataset.
-   filter(:name.like('A%')).
+   where(Sequel.like(:name, 'A%')).
    order(:copies_sold).
    limit(10)
   # SELECT * FROM albums
@@ -364,8 +364,8 @@ Similar to the +_dataset+ method, you can provide a block to the association
 method to customize the dataset that will be used to retrieve the records.  So
 you can apply a filter in either of these two ways:
 
-  @artist.albums_dataset.filter(:name.like('A%'))
-  @artist.albums{|ds| ds.filter(:name.like('A%'))}
+  @artist.albums_dataset.where(Sequel.like(:name, 'A%'))
+  @artist.albums{|ds| ds.where(Sequel.like(:name, 'A%'))}
 
 While they both apply the same filter, using the +_dataset+ method does not
 apply any of the association callbacks or handle association reciprocals (see
@@ -373,11 +373,6 @@ below for details about callbacks and reciprocals).  Using a block instead handl
 all those things, and also caches its results in the associations cache (ignoring
 any previously cached value).
 
-Note that if you are using ruby 1.8.6, you can't pass a block to the association
-method, you have to pass a proc as an argument:
-
-  @artist.albums(proc{|ds| ds.filter(:name.like('A%'))})
-
 == Filtering By Associations
 
 In addition to using the association method to get associated objects, you
@@ -389,35 +384,35 @@ all albums for a given artist, you would usually do:
 
 You can also do the following:
 
-  Album.filter(:artist=>@artist).all
+  Album.where(:artist=>@artist).all
   # or leave off the .all for a dataset
 
 For filtering by a single association, this isn't very useful.  However, unlike
 using the association method, using a filter allows you to filter by multiple
 associations:
 
-  Album.filter(:artist=>@artist, :publisher=>@publisher)
+  Album.where(:artist=>@artist, :publisher=>@publisher)
 
 This will return all albums by that artist and published by that publisher.
 This isn't possible using just the association method approach, though you
 can combine the approaches:
 
-  @artist.albums_dataset.filter(:publisher=>@publisher)
+  @artist.albums_dataset.where(:publisher=>@publisher)
 
 This doesn't just work for +many_to_one+ associations, it also works for
 +one_to_one+, +one_to_many+, and +many_to_many+ associations:
 
   Album.one_to_one :album_info
   # The album related to that AlbumInfo instance
-  Album.filter(:album_info=>AlbumInfo[2])
+  Album.where(:album_info=>AlbumInfo[2])
 
   Album.one_to_many :tracks
   # The album related to that Track instance
-  Album.filter(:tracks=>Track[3])
+  Album.where(:tracks=>Track[3])
 
   Album.many_to_many :tags
   # All albums related to that Tag instance
-  Album.filter(:tags=>Tag[4])
+  Album.where(:tags=>Tag[4])
 
 Note that for +one_to_many+ and +many_to_many+ associations, you still
 use the plural form even though only a single model object is given.
@@ -430,7 +425,7 @@ This will return all albums not by that artist.
 
 You can also provide an array with multiple model objects:
 
-  Album.filter(:artist=>[@artist1, @artist2]).all
+  Album.where(:artist=>[@artist1, @artist2]).all
 
 Similar to using an array of integers or strings, this will return
 all albums whose artist is one of those two artists.  You can also
@@ -442,28 +437,28 @@ If you are using a +one_to_many+ or +many_to_many+ association, you
 may want to return records where the records matches all of multiple
 records, instead of matching any of them.  For example:
 
-  Album.filter(:tags=>[@tag1, @tag2])
+  Album.where(:tags=>[@tag1, @tag2])
   
 This matches albums that are associated with either @tag1 or @tag2 or
 both.  If you only want ones that you are associated with both, you can
 use separate filter calls:
 
-  Album.filter(:tags=>@tag1).filter(:tags=>@tag2)
+  Album.where(:tags=>@tag1).where(:tags=>@tag2)
 
 Or the the array form of condition specifiers:
 
-  Album.filter([[:tags, @tag1], [:tags, @tag2]])
+  Album.where([[:tags, @tag1], [:tags, @tag2]])
 
 These will return albums associated with both @tag1 and @tag2.
 
 You can also provide a dataset value when filtering by associations:
 
-  Album.filter(:artist=>Artist.filter(:name.like('A%'))).all
+  Album.where(:artist=>Artist.where(Sequel.like(:name, 'A%'))).all
 
 This will return all albums whose artist starts with 'A'. Like
 the other forms, this can be inverted:
 
-  Album.exclude(:artist=>Artist.filter(:name.like('A%'))).all
+  Album.exclude(:artist=>Artist.where(Sequel.like(:name, 'A%'))).all
  
 This will return all albums whose artist does not start with 'A'.
 
@@ -562,6 +557,8 @@ wanted to add an albums_artists join table to create the following schema:
 
 You could use the following Sequel code:
 
+  DB.create_join_table(:album_id=>:albums, :artist_id=>:artists)
+  # or
   DB.create_table(:albums_artists) do
     foreign_key :album_id, :albums
     foreign_key :artist_id, :artists
@@ -717,7 +714,7 @@ The <i>association</i>_dataset method returns a dataset that represents
 all associated objects.  This dataset is like any other Sequel dataset,
 in that it can be filtered, ordered, etc.:
 
-  ds = @artist.albums_dataset.filter(:name.like('A%')).order(:copies_sold)
+  ds = @artist.albums_dataset.where(Sequel.like(:name, 'A%')).order(:copies_sold)
 
 Unlike most other Sequel datasets, association datasets have a couple of
 added methods:
@@ -828,7 +825,7 @@ that returns all albums of an artist that went gold (sold at least
 500,000 copies):
 
   Artist.one_to_many :gold_albums, :class=>:Album do |ds|
-    ds.filter{copies_sold > 500000}
+    ds.where{copies_sold > 500000}
   end
 
 ==== :class
@@ -847,7 +844,7 @@ default class guessed will be wrong:
 
   # guesses GoldAlbum
   Artist.one_to_many :gold_albums do |ds|
-    ds.filter{copies_sold > 500000}
+    ds.where{copies_sold > 500000}
   end
 
 You can specify the :class option using the class itself, a Symbol,
@@ -872,13 +869,13 @@ symbol.  Defaults to :"#{self.name.underscore}_id".
 
   Artist.one_to_many :albums # :key=>:artist_id
 
-In both cases an array of symbols for a composite key association:
+In both cases an array of symbols can be used for a composite key association:
 
   Apartment.many_to_one :building # :key=>[:city, :address]
 
 ==== :conditions
 
-The conditions to use to filter the association, can be any argument passed to filter.
+The conditions to use to filter the association, can be any argument passed to +where+.
 If you use a hash or an array of two element arrays, this will also be used as a
 filter when using eager_graph to load the association.
 
@@ -911,7 +908,7 @@ columns that have the same name in both the join table and the associated
 table.  Example:
 
   Artist.one_to_many :albums, :select=>[:id, :name]
-  Album.many_to_many :tags, :select=>[:tags.*, :albums_tags__number]
+  Album.many_to_many :tags, :select=>[Sequel.expr(:tags).*, :albums_tags__number]
 
 ==== :limit
 
@@ -928,8 +925,6 @@ Use an array with two arguments for the value to specify a limit and an offset.
 This probably doesn't make a lot of sense for *_to_one associations, though you
 could use it to specify an offset.
 
-This option is ignored when eager loading.
-
 ==== :join_table [+many_to_many+]
 
 Name of table that includes the foreign keys to both the current model and the
@@ -944,7 +939,7 @@ Here's an example of the defaults:
 ==== :left_key [+many_to_many+]
 
 Foreign key in join table that points to current model's primary key, as a
-symbol.  Defaults to :"#{self.name.underscore}_id".
+symbol.  Defaults to :"#{model_name.underscore}_id".
 
   Album.many_to_many :tags # :left_key=>:album_id
 
@@ -953,9 +948,9 @@ Can use an array of symbols for a composite key association.
 ==== :right_key [+many_to_many+]
 
 Foreign key in join table that points to associated model's primary key, as a
-symbol.  Defaults to :"#{name.to_s.singularize}_id".
+symbol.  Defaults to :"#{association_name.singularize}_id".
 
-  Album.many_to_many :tags # :left_key=>:tag_id
+  Album.many_to_many :tags # :right_key=>:tag_id
   
 Can use an array of symbols for a composite key association.
 
@@ -1006,7 +1001,7 @@ Here's an example of an association of songs to artists through lyrics, where
 the artist can perform any one of four tasks for the lyric:
 
   Album.one_to_many :songs, :dataset=>(proc do
-    Song.select(:songs.*).
+    Song.select_all(:songs).
      join(Lyric, :id=>:lyricid,
       id=>[:composer_id, :arranger_id, :vocalist_id, :lyricist_id])
   end)
@@ -1025,8 +1020,8 @@ set up association extensions.  For more information , please see the
 ==== :primary_key
 
 The column that the :key option references, as a symbol. For +many_to_one+
-associations, this column in the associated table. For +one_to_one+ and
-+one_to_many+ associations, this column in the current table.  In both cases,
+associations, this column is in the associated table. For +one_to_one+ and
++one_to_many+ associations, this column is in the current table.  In both cases,
 it defaults to the primary key of the table. Can use an
 array of symbols for a composite key association.
 
@@ -1063,7 +1058,7 @@ applies to the join table.  It can be used to make sure additional columns are
 used when inserting, or that filters are used when deleting.
 
   Artist.many_to_many :lead_guitar_albums, :join_table_block=>proc do |ds|
-    ds.filter(:instrument_id=>5).set_overrides(:instrument_id=>5)
+    ds.where(:instrument_id=>5).set_overrides(:instrument_id=>5)
   end
 
 === Callback Options
@@ -1158,8 +1153,7 @@ Called after the _<i>association</i>= method is called to modify the objects:
 
 ==== :after_load
 
-Called after retrieving the associated records from the database. Not called
-when eager loading via eager_graph, but called when eager loading via eager.
+Called after retrieving the associated records from the database.
 
   class Artist
     # Cache all album names to a single string when retrieving the
@@ -1176,8 +1170,7 @@ when eager loading via eager_graph, but called when eager loading via eager.
   end
 
 Generally used if you know you will always want a certain action done
-when retrieving the association.  However, you need to be careful if you
-also plan on using eager_graph to eagerly load the association.
+when retrieving the association.
 
 For +one_to_many+ and +many_to_many+ associations, both the argument to
 symbol callbacks and the second argument to proc callbacks will be an
@@ -1242,7 +1235,7 @@ association based on dependent associations:
 
   Artist.one_to_many :albums_with_short_tracks, :class=>:Album,
    :eager_graph=>:tracks do |ds|
-    ds.filter{tracks__seconds < 120}
+    ds.where{tracks__seconds < 120}
   end
   Artist.one_to_many :albums_by_track_name, :class=>:Album,
    :eager_graph=>:tracks do |ds|
@@ -1274,13 +1267,13 @@ via eager_graph.  This is useful to specify conditions that can't be specified
 in a hash or array of two element arrays.
 
   Artist.one_to_many :gold_albums, :class=>:Album,
-    :graph_block=>proc{|j,lj,js| :copies_sold.qualify(j) > 500000}
+    :graph_block=>proc{|j,lj,js| Sequel.qualify(j, :copies_sold) > 500000}
 
 ==== :graph_join_type
 
 The type of SQL join to use when eagerly loading the association via
 eager_graph.  Defaults to :left_outer.  This is useful if you want to
-ensure that all return only artists that have albums:
+ensure that only artists that have albums are returned:
 
   Artist.one_to_many :albums, :graph_join_type=>:inner
   # Will exclude artists without an album
@@ -1306,8 +1299,8 @@ where the artist's name differs in case:
 
   Artist.one_to_many :albums, :key=>:artist_name, 
     :graph_only_conditions=>nil, 
-    :graph_block=>proc{|j,lj,js| {:lower.sql_function(artist_name.qualify(j))=>
-      :lower.sql_function(name.qualify(lj))}}
+    :graph_block=>proc{|j,lj,js| {Sequel.function(:lower, Sequel.qualify(j, :artist_name))=>
+      Sequel.function(:lower, Sequel.qualify(lj, :name))}}
 
 Note how :graph_only_conditions is set to nil to ignore any existing conditions,
 and :graph_block is used to set up the case insensitive comparison.
@@ -1345,8 +1338,8 @@ Sets up a custom grapher to use when eager loading the objects via eager_graph.
 This is the eager_graph analogue to the :eager_loader option. This isn't generally
 needed, as one of the other eager_graph related association options is usually sufficient.
 
-If specified, should be a proc that accepts one or three three arguments.
-If the proc takes one argument, it will be given a hash with the following keys:
+If specified, should be a proc that accepts a single hash argument, which will contain
+at least the following keys:
 
 :self :: The dataset that is doing the eager loading
 :table_alias :: An alias to use for the table to graph for this association.
@@ -1355,10 +1348,7 @@ If the proc takes one argument, it will be given a hash with the following keys:
              current dataset, before such graphing is done. This is nil if no callback
              proc is used.
 
-If the proc takes three arguments, it gets passed the :self, :association_alias,
-and :table_alias values. The 3 argument procs are allowed for backwards
-compatibility, and it is recommended to use the 1 argument proc format
-for new code.
+Example:
 
   Artist.one_to_many :self_title_albums, :class=>:Album,
    :eager_grapher=>(proc do |eo|
@@ -1407,7 +1397,7 @@ has received a bachelor's degree (degree starting with B):
 
   Person.many_to_many :bachelor_degree_colleges, :class=>:College,
     :join_table=>:degrees_received,
-    :graph_join_table_block=>proc{|j,lj,js| :degree.qualify(j).like('B%')}
+    :graph_join_table_block=>proc{|j,lj,js| Sequel.qualify(j, :degree).like('B%')}
 
 This should be done when graphing the join table, instead of when graphing the
 final table, as :degree is a column of the join table.

data/doc/cheat_sheet.rdoc

@@ -53,8 +53,8 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 == Update/Delete rows
 
-  dataset.filter(~:active).delete
-  dataset.filter('price < ?', 100).update(:active => true)
+  dataset.exclude(:active).delete
+  dataset.where('price < ?', 100).update(:active => true)
 
 == Datasets are Enumerable
 
@@ -64,21 +64,21 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
   dataset.inject(0){|sum, r| sum + r[:value]}
   dataset.sum(:value) # same as above
 
-== Filtering (see also doc/dataset_filtering.rdoc)
+== Filtering (see also {Dataset Filtering}[link:files/doc/dataset_filtering_rdoc.html])
 
 === Equality
 
-  dataset.filter(:name => 'abc')
-  dataset.filter('name = ?', 'abc')
+  dataset.where(:name => 'abc')
+  dataset.where('name = ?', 'abc')
 
 === Inequality
 
-  dataset.filter{value > 100}
+  dataset.where{value > 100}
   dataset.exclude{value <= 100}
 
 === Inclusion
 
-  dataset.filter(:value => 50..100)
+  dataset.where(:value => 50..100)
   dataset.where{(value >= 50) & (value <= 100)}
 
   dataset.where('value IN ?', [50,75,100])
@@ -89,34 +89,34 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 === Subselects as scalar values
 
   dataset.where('price > (SELECT avg(price) + 100 FROM table)')
-  dataset.filter{price > dataset.select(avg(price) + 100)}
+  dataset.where{price > dataset.select(avg(price) + 100)}
 
 === LIKE/Regexp
 
-  DB[:items].filter(:name.like('AL%'))
-  DB[:items].filter(:name => /^AL/)
+  DB[:items].where(Sequel.like(:name, 'AL%'))
+  DB[:items].where(:name => /^AL/)
 
 === AND/OR/NOT
 
-  DB[:items].filter{(x > 5) & (y > 10)}.sql 
+  DB[:items].where{(x > 5) & (y > 10)}.sql 
   # SELECT * FROM items WHERE ((x > 5) AND (y > 10))
 
-  DB[:items].filter({:x => 1, :y => 2}.sql_or & ~{:z => 3}).sql 
+  DB[:items].where({:x => 1, :y => 2}.sql_or & Sequel.~(:z => 3)).sql 
   # SELECT * FROM items WHERE (((x = 1) OR (y = 2)) AND (z != 3))
 
 === Mathematical operators
 
-  DB[:items].filter((:x + :y) > :z).sql 
+  DB[:items].where{x + y > z}.sql 
   # SELECT * FROM items WHERE ((x + y) > z)
 
-  DB[:items].filter{price - 100 < avg(price)}.sql 
+  DB[:items].where{price - 100 < avg(price)}.sql 
   # SELECT * FROM items WHERE ((price - 100) < avg(price))
 
 == Ordering
 
   dataset.order(:kind)
   dataset.reverse_order(:kind)
-  dataset.order(:kind.desc, :name)
+  dataset.order(Sequel.desc(:kind), :name)
 
 == Limit/Offset
 
@@ -140,15 +140,15 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
   dataset.sum(:stock)
 
   dataset.group_and_count(:category)
-  dataset.group(:category).select(:category, :AVG.sql_function(:price))
+  dataset.group(:category).select(:category, Sequel.function(:AVG, :price))
 
 == SQL Functions / Literals
 
-  dataset.update(:updated_at => :NOW.sql_function)
-  dataset.update(:updated_at => 'NOW()'.lit)
+  dataset.update(:updated_at => Sequel.function(:NOW))
+  dataset.update(:updated_at => Sequel.lit('NOW()'))
 
-  dataset.update(:updated_at => "DateValue('1/1/2001')".lit)
-  dataset.update(:updated_at => :DateValue.sql_function('1/1/2001'))
+  dataset.update(:updated_at => Sequel.lit("DateValue('1/1/2001')")
+  dataset.update(:updated_at => Sequel.function(:DateValue, '1/1/2001'))
 
 == Schema Manipulation
 
@@ -171,7 +171,7 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 == Aliasing
 
-  DB[:items].select(:name.as(:item_name))
+  DB[:items].select(Sequel.as(:name, :item_name))
   DB[:items].select(:name___item_name)
   DB[:items___items_table].select(:items_table__name___item_name)
   # SELECT items_table.name AS item_name FROM items AS items_table

data/doc/core_extensions.rdoc

@@ -0,0 +1,374 @@
+= Sequel's Core Extensions
+
+== Background
+
+Historically, Sequel added methods to many of the core classes, and usage of those methods was the primary and recommended way to use Sequel.  For example:
+
+  DB[:table].select(:column.cast(Integer)). # Symbol#cast 
+    where(:column.like('A%')).              # Symbol#like
+    order({1=>2}.case(0, :a))               # Hash#case
+
+While Sequel never override any methods defined by ruby, it is possible that other libraries could define the same methods that Sequel defines, which could cause problems.  Also, some rubyists do not like using libraries that add methods to the core classes.
+
+Alternatives for the core extension methods where added to Sequel, so the query above could be written as:
+
+  DB[:table].select(Sequel.cast(:column, Integer)).
+    where(Sequel.like(:column, 'A%')).
+    order(Sequel.case({1=>2}, 0, :a))
+
+Almost all of the core extension methods have a replacement on the Sequel module.  So it is now up to the user which style to use.  Using the methods on the Sequel module results in slightly more verbose code, but allows the code to work without modifications to the core classes.
+
+== Issues
+
+There is no recommendation on whether the core_extensions should be used or not.  It is very rare that any of the methods added by core_extensions actually causes a problem, but some of them can make it more difficult to find other problems.  For example, if you type:
+
+  do_somehting if value | other_value
+
+while meaning to type:
+
+  do_something if value || other_value
+
+and value is a Symbol, instead of a NoMethodError being raised because Symbol#| is not implemented by default, <tt>value | other_value</tt> will return a Sequel expression object, which if will evaluate as true, and do_something will be called.
+
+== Usage
+
+All of Sequel's extensions to the core classes are stored in Sequel's core_extensions extension, which you can load via:
+
+  Sequel.extension :core_extensions
+
+For backwards compatibility, the core_extensions are loaded by default in Sequel 3.  Starting in Sequel 4, the core extensions will no longer be loaded by default, so you will have to load the core_extensions extension manually using the above code.  If you plan to use the core extensions, it's recommended that you manually load the extension, even in Sequel 3.  If you do not plan to use the core extensions, you can change from:
+
+  require 'sequel'
+
+to:
+
+  require 'sequel/no_core_ext'
+
+which will load Sequel without the core extensions.
+
+== No Internal Dependency
+
+Sequel has no internal dependency on the core extensions.  This includes Sequel's core, Sequel::Model, and all plugins and extensions that ship with Sequel.  However, it is possible that external plugins and extensions will depend on the core extensions.  Such plugins and extensions should be updated so that they no longer depend on the core extensions.
+
+== Core Extension Methods
+
+This section will briefly describe all of the methods added to the core classes, and what the alternative method is that doesn't require the core extensions.
+
+=== Symbol & String
+
+==== as
+
+Symbol#as and String#as return Sequel aliased expressions using the provided alias:
+
+  :a.as(:b)  # SQL: a AS b
+  'a'.as(:b) # SQL: 'a' AS b
+
+Alternative: Sequel.as:
+
+  Sequel.as(:a, :b)
+
+==== cast
+
+Symbol#cast and String#cast return Sequel cast expressions for typecasting in the database:
+
+  :a.cast(Integer)  # SQL: CAST(a AS integer)
+  'a'.cast(Integer) # SQL: CAST('a' AS integer)
+
+Alternative: Sequel.cast:
+
+  Sequel.cast(:a, Integer)
+
+==== cast_numeric
+
+Symbol#cast_numeric and String#cast_numeric return Sequel cast expressions for typecasting in the database, defaulting to integers, where the returned expression is treated as an numeric value:
+
+  :a.cast_numeric         # SQL: CAST(a AS integer)
+  'a'.cast_numeric(Float) # SQL: CAST('a' AS double precision)
+
+Alternative: Sequel.cast_numeric:
+
+  Sequel.cast_numeric(:a)
+
+==== cast_string
+
+Symbol#cast_string and String#cast_string return Sequel cast expressions for typecasting in the database, defaulting to strings, where the returned expression is treated as a string value:
+
+  :a.cast_string         # SQL: CAST(a AS varchar(255))
+  'a'.cast_string(:text) # SQL: CAST('a' AS text)
+
+Alternative: Sequel.cast_string:
+
+  Sequel.cast_string(:a)
+
+=== Symbol
+
+==== identifier
+
+Symbol#identifier wraps the symbol in a single identifier that will not be split.  By default, Sequel will split symbols with double or triple underscores to do qualifying and aliasing.
+
+  :table__column.identifier # SQL: table__column
+
+Alternative: Sequel.identifier:
+
+  Sequel.identifier(:table__column)
+
+==== asc
+
+Symbol#asc is used to define an ascending order on a column.  It exists mostly for consistency with #desc, since ascending is the default order:
+
+  :a.asc # SQL: a ASC
+
+Alternative: Sequel.asc:
+
+  Sequel.asc(:a)
+
+==== desc
+
+Symbol#desc is used to defined a descending order on a column.  The returned value is usually passed to one of the dataset order methods.
+
+  :a.desc # SQL: a DESC
+
+Alternative: Sequel.desc:
+
+  Sequel.desc(:a)
+
+==== +, -, *, /
+
+The standard mathematical operators are defined on Symbol, and return a Sequel numeric expression object representing the operation:
+
+    :a + :b # SQL: a + b
+    :a - :b # SQL: a - b
+    :a * :b # SQL: a * b
+    :a / :b # SQL: a / b 
+
+Alternatives:
+
+    Sequel.+(:a, :b)
+    Sequel.-(:a, :b)
+    Sequel.*(:a, :b)
+    Sequel./(:a, :b)
+
+==== *
+
+The * operator is overloaded on Symbol such that if it is called with no arguments, it represents a selection of all columns in the table:
+
+  :a.* # SQL: a.*
+
+Alternative: Sequel.expr.*:
+
+  Sequel.expr(:a).*
+
+==== qualify
+
+Symbol#qualify qualifies the identifier (e.g. a column) with a another identifier (e.g. a table):
+
+  :column.qualify(:table) # SQL: table.column
+
+Alternative: Sequel.qualify:
+
+  Sequel.qualify(:table, :column)
+
+Note the reversed order of the arguments.  For the Symbol#qualify method, the argument is the qualifier, while for Sequel.qualify, the qualifier is the first argument.
+
+==== like
+
+Symbol#like returns a case sensitive LIKE expression between the identifier and the given argument:
+
+  :a.like('b%') # SQL: a LIKE 'b%'
+
+Alternative: Sequel.like:
+
+  Sequel.like(:a, 'b%')
+
+==== like
+
+Symbol#ilike returns a case insensitive LIKE expression between the identifier and the given argument:
+
+  :a.ilike('b%') # SQL: a ILIKE 'b%'
+
+Alternative: Sequel.ilike:
+
+  Sequel.ilike(:a, 'b%')
+
+==== sql_subscript
+
+Symbol#sql_subscript returns a Sequel expression representing an SQL array access:
+
+  :a.sql_subscript(1) # SQL: a[1]
+
+Alternative: Sequel.subscript:
+
+  Sequel.subscript(:a, 1)
+
+==== extract
+
+Symbol#extract does a datetime part extraction from the receiver:
+
+  :a.extract(:year) # SQL: extract(year FROM a)
+
+Alternative: Sequel.extract:
+
+  Sequel.extract(:year, :a)
+
+Note the reversed order of the arguments.  In Symbol#extract, the datetime part is the argument, while in Sequel.extract, the datetime part is the first argument.
+
+==== sql_boolean, sql_number, sql_string
+
+These Symbol methods are used to force the treating of the object as a specific SQL type, instead of as a general SQL type.  For example:
+
+  :a.sql_boolean + 1  # NoMethodError
+  :a.sql_number << 1  # SQL: a << 1
+  :a.sql_string + 'a' # SQL: a || 'a'
+
+Alternative: Sequel.expr:
+
+  Sequel.expr(:a).sql_boolean
+  Sequel.expr(:a).sql_number
+  Sequel.expr(:a).sql_string
+
+==== sql_function
+
+Symbol#sql_function returns an SQL function call expression object:
+
+  :now.sql_function # SQL: now()
+  :sum.sql_function(:a) # SQL: sum(a)
+  :concat.sql_function(:a, :b) # SQL: concat(a, b)
+
+Alternative: Sequel.function:
+
+  Sequel.function(:now, :a)
+
+=== String
+
+==== lit
+
+String#lit creates a literal string, using placeholders if any arguments are given.  Literal strings are not escaped, they are treated as SQL code, not as an SQL string:
+
+  'a'.lit          # SQL: a
+  '"a" = ?'.lit(1) # SQL: "a" = 1
+
+Alternative: Sequel.lit:
+
+  Sequel.lit('a')
+
+==== to_sequel_blob
+
+String#to_sequel_blob returns the string wrapper in Sequel blob object.  Often blobs need to be handled differently than regular strings by the database adapters.
+
+  "a\0".to_sequel_blob # SQL: X'6100'
+
+Alternative: Sequel.blob:
+
+  Sequel.blob("a\0")
+
+=== Hash, Array, & Symbol
+
+==== ~
+
+Array#~, Hash#~, and Symbol#~ treat the receiver as a conditions specifier, not matching all of the conditions:
+
+  ~{:a=>1, :b=>[2, 3]}     # SQL: a != 1 OR b NOT IN (2, 3)
+  ~[[:a, 1], [:b, [1, 2]]] # SQL: a != 1 OR b NOT IN (1, 2)
+
+Alternative: Sequel.~:
+
+   Sequel.~(:a=>1, :b=>[2, 3])
+
+=== Hash & Array
+
+==== case
+
+Array#case and Hash#case return an SQL CASE expression, where the keys are conditions and the values are results:
+
+  {{:a=>[2,3]}=>1}.case(0)   # SQL: CASE WHEN a IN (2, 3) THEN 1 ELSE 0 END
+  [[{:a=>[2,3]}, 1]].case(0) # SQL: CASE WHEN a IN (2, 3) THEN 1 ELSE 0 END
+
+Alternative: Sequel.case:
+
+  Sequel.case({:a=>[2,3]}=>1}, 0)
+
+==== sql_expr
+
+Array#sql_expr and Hash#sql_expr treat the receiver as a conditions specifier, matching all of the conditions in the array.
+
+  {:a=>1, :b=>[2, 3]}.sql_expr     # SQL: a = 1 AND b IN (2, 3)
+  [[:a, 1], [:b, [2, 3]]].sql_expr # SQL: a = 1 AND b IN (2, 3)
+
+Alternative: Sequel.expr:
+
+  Sequel.expr(:a=>1, :b=>[2, 3])
+
+==== sql_negate
+
+Array#sql_negate and Hash#sql_negate treat the receiver as a conditions specifier, matching none of the conditions in the array:
+
+  {:a=>1, :b=>[2, 3]}.sql_negate     # SQL: a != 1 AND b NOT IN (2, 3)
+  [[:a, 1], [:b, [2, 3]]].sql_negate # SQL: a != 1 AND b NOT IN (2, 3)
+
+Alternative: Sequel.negate:
+
+  Sequel.negate(:a=>1, :b=>[2, 3])
+
+==== sql_or
+
+Array#sql_or nd Hash#sql_or treat the receiver as a conditions specifier, matching any of the conditions in the array:
+
+  {:a=>1, :b=>[2, 3]}.sql_or     # SQL: a = 1 OR b IN (2, 3)
+  [[:a, 1], [:b, [2, 3]]].sql_or # SQL: a = 1 OR b IN (2, 3)
+
+Alternative: Sequel.or:
+
+  Sequel.or(:a=>1, :b=>[2, 3])
+
+=== Array
+
+==== sql_value_list
+
+Array#sql_value_list wraps the array in an array subclass, which Sequel will always treat as a value list and not a conditions specifier.  By default, Sequel treats arrays of two element arrays as a conditions specifier.
+
+  DB[:a].filter('(a, b) IN ?', [[1, 2], [3, 4]]) # SQL: (a, b) IN ((1 = 2) AND (3 = 4))
+  DB[:a].filter('(a, b) IN ?', [[1, 2], [3, 4]].sql_value_list) # SQL: (a, b) IN ((1, 2), (3, 4))
+
+Alternative: Sequel.value_list:
+
+  Sequel.value_list([[1, 2], [3, 4]])
+
+==== sql_string_join
+
+Array#sql_string_join joins all of the elements in the array in an SQL string concatentation expression:
+
+  [:a].sql_string_join # SQL: a
+  [:a, :b].sql_string_join # SQL: a || b
+  [:a, 'b'].sql_string_join # SQL: a || 'b'
+  ['a', :b].sql_string_join(' ') # SQL: 'a' || ' ' || b
+
+Alternative: Sequel.join:
+
+  Sequel.join(['a', :b], ' ')
+
+=== Hash & Symbol
+
+==== &
+
+Hash#& and Symbol#& return a Sequel boolean expression, matching the condition specified by the receiver and the condition specified by the given argument:
+
+  :a & :b         # SQL: a AND b
+  {:a=>1} & :b    # SQL: a = 1 AND b
+  {:a=>true} & :b # SQL: a IS TRUE AND b
+
+Alternative: Sequel.&:
+
+  Sequel.&({:a=>1}, :b)
+
+==== |
+
+Hash#| returns a Sequel boolean expression, matching the condition specified by the receiver or the condition specified by the given argument:
+
+  :a | :b         # SQL: a OR b
+  {:a=>1} | :b    # SQL: a = 1 OR b
+  {:a=>true} | :b # SQL: a IS TRUE OR b
+
+Alternative: Sequel.|:
+
+  Sequel.|({:a=>1}, :b)
+