sequel 3.37.0 → 3.38.0

data/doc/reflection.rdoc

@@ -58,12 +58,12 @@ The hash may also contain entries for:
 
 Database#schema takes a table symbol and returns column information in an array with each element being an array with two elements.  The first elements of the subarray is a column symbol, and the second element is a hash of information about that column.  The hash should include the following keys:
 
-* :allow_null - Whether NULL/nil is an allowed value for this column. Used by the Sequel::Model typecasting code.
-* :db_type - The type of column the database provided, as a string.  Used by the schema_dumper plugin for a more specific type translation.
-* :default - The default value of the column, as either a string or nil.  Uses a database specific format. Used by the schema_dumper plugin for converting to a ruby value.
-* :primary_key - Whether this column is one of the primary key columns for the table.  Used by the Sequel::Model code to determine primary key columns.
-* :ruby_default - The default value of the column as a ruby object, or nil if there is no default or the default could not be successfully parsed into a ruby object.
-* :type - The type of column, as a symbol (e.g. :string).  Used by the Sequel::Model typecasting code.
+:allow_null :: Whether NULL/nil is an allowed value for this column. Used by the Sequel::Model typecasting code.
+:db_type :: The type of column the database provided, as a string.  Used by the schema_dumper plugin for a more specific type translation.
+:default :: The default value of the column, as either a string or nil.  Uses a database specific format. Used by the schema_dumper plugin for converting to a ruby value.
+:primary_key :: Whether this column is one of the primary key columns for the table.  Used by the Sequel::Model code to determine primary key columns.
+:ruby_default :: The default value of the column as a ruby object, or nil if there is no default or the default could not be successfully parsed into a ruby object.
+:type :: The type of column, as a symbol (e.g. :string).  Used by the Sequel::Model typecasting code.
 
 Example:
 

data/doc/release_notes/3.38.0.txt

@@ -0,0 +1,234 @@
+= New Features
+
+* A pg_row extension has been added that supports PostgreSQL's
+  row-valued/composite types.  You can register support for
+  specific row types:
+
+    DB.register_row_type(:address)
+
+  Then you can create values of that row type:
+
+    ad = DB.row_type(:address, ['555 Foo St.', 'Bar City', '98765'])
+    # or
+    ad = DB.row_type(:address, :street=>'555 Foo St.',
+                          :city=>'Bar City', :zip=>'98765')
+
+  Which you can use in your datasets:
+
+    DB[:people].insert(:name=>'Me', :address=>ad)
+  
+  If you are using the native postgres adapter, when retreiving
+  row type values, they will be returned as instances of the row
+  type, which are hash-like objects:
+
+    ad = DB[:people].get(:address)
+    ad[:street] # => '555 Foo St.'
+    ad[:city]   # => 'Bar City'
+    ad[:zip]    # => '98765'
+
+  If you are also using the pg_array extension, then arrays of
+  composite types are supported automatically.  Composite
+  types can also include arrays of other types as well as other
+  composite types, though recursive composite types are not
+  allowed by PostgreSQL.
+
+  Using arrays and composite types brings one of the benefits
+  of document databases to PostgreSQL, allowing you to store
+  nested structures inside a single row.
+
+* A pg_row_ops extension has been added that adds DSL support
+  for accessing members of row-valued/composite types. You
+  first create a row op:
+
+    r = Sequel.pg_row_op(:row_column)
+
+  Then you can get DSL support for accessing members of that
+  row_column via the #[] method:
+
+    r[:a] # (row_column).a
+
+  This works with composite types containing composite types:
+
+    r[:a][:b] # ((row_column).a).b
+
+  When used in conjunction with the pg_array_ops extension,
+  there is support for composite types that include arrays,
+  as well as arrays of composite types:
+
+    r[1][:a] # (row_column[1]).a
+    r[:a][1] # (row_column).a[1]
+
+  The extension offers additional support for referencing
+  a table's type when it contains a column with the same
+  name, see the RDoc for details.
+
+* A pg_row plugin has been added, that works with the pg_row
+  extension, and allows you to represent row-valued types as
+  Sequel::Model objects (instead of the hash-like objects
+  they use by default).  In your model class, you load the
+  plugin:
+
+    class Address < Sequel::Model(:address)
+      plugin :pg_row
+    end
+
+  Then you can use Address instances in your datasets:
+  
+    ad = Address.new(:street=>'555 Foo St.',
+                     :city=>'Bar City', :zip=>'98765')
+    DB[:people].insert(:name=>'Me', :address=>ad)
+
+  And if you are using the native postgres adapter, the dataset
+  will return the type as a model instance:
+
+    ad = DB[:people].get(:address)
+    ad.street # => '555 Foo St.'
+    ad.city   # => 'Bar City'
+    ad.zip    # => '98765'
+ 
+* A pg_typecast_on_load plugin has been added.  This plugin is
+  designed for use with the jdbc/postgres, do/postgres, and
+  swift/postgres adapters, and it is similar to the
+  typecast_on_load plugin.  However, while the typecast_on_load
+  plugin uses setter methods, the pg_typecast_on_load plugin
+  uses the same code that the native postgres adapter uses for
+  typecasting.
+
+* The tinytds adapter now supports a :textsize option to override
+  the default TEXTSIZE setting.  The FreeTDS default is fairly
+  small (~64k), so if you want to use large blob or text columns,
+  you should probably set this to a value larger than the
+  largest text/blob you want to use.
+
+* Sequel.expr when called with a symbol now splits the symbol and
+  returns an Identifier, QualifiedIdentifier, or AliasedExpression, 
+  depending on the content of the symbol.  Previously, it only
+  wrapped the symbol using a Wrapper.
+
+* Identifier#* and QualifiedIdentifier#* when called without any
+  argument now represent a selection of all columns from the
+  represented table:
+
+    Sequel.expr(:table).*          # table.*
+    Sequel.expr(:schema__table).*  # schema.table.*
+
+  This makes it easier to represent the selection of all columns
+  in a table without using the core extensions.
+
+* Model#values now has a Model#to_hash alias.
+
+* SQL::Blob values now have as, cast, and lit methods even if the
+  core extensions are not loaded.
+
+= Other Improvements
+
+* When loading multiple pg_* extensions into a Database instance,
+  the conversion procs are only reset once instead of once per
+  extension.
+
+* All adapters that access PostgreSQL now store type conversion
+  procs, similar to the native postgres adapter.  This has been
+  added to make it easier to write extensions that support
+  advanced PostgreSQL types.
+
+* Database#schema output on PostgreSQL now includes the type oid
+  for each column.
+
+* You can now register custom array types to specific Database
+  instances, using the :type_procs and :typecast_methods_module
+  options, so it is now possible to have custom array types
+  without affecting global state.
+
+* Dropping of columns with defaults now works correctly on
+  Microsoft SQL Server.  Before, it would fail as the related
+  constraint was not dropped first.
+
+* The MySQL type "double(x,y)" is now recognized as a float type.
+
+* The jdbc/jtds and jdbc/derby adapters now handle nil prepared
+  statement values in more cases.
+
+* Blob prepared statement arguments are now handled correctly on
+  jdbc/db2 and jdbc/oracle.
+
+* Sequel now works around a Time#nsec bug in JRuby 1.6 ruby 1.9 mode
+  when using Time values in prepared statements in the jdbc adapter.
+
+* Java::JavaUtil::UUID types are now returned as ruby strings
+  when converting types in the jdbc adapter.
+
+* Real boolean literals are now used on derby 10.7+.  On derby <10.7
+  Sequel still uses (1 = 1) and (1 != 1) for true and false.  This
+  allows you to use boolean columns with a true/false default on
+  derby 10.7+.
+
+* Clobs are now treated as string types instead of blobs on derby,
+  since treating clob as blob doesn't work there.
+
+* The swift adapter now supports an output identifier method.
+
+* The swift adapter now returns blobs as SQL::Blob instances.
+
+* The schema_dumper extension no longer produces code that requires
+  the core extensions.
+
+* All of Sequel's specs now run without the core extensions loaded,
+  ensuring that none of the internals depend on the core extensions.
+  The only exception is the specs for the core extensions themselves.
+
+= Backwards Compatibility
+
+* The pg_* extensions no longer modify core classes if the
+  core_extensions extension is not loaded.  All methods they added now
+  have equivalent methods on the main Sequel module:
+
+    Sequel.pg_array
+    Sequel.pg_array_op
+    Sequel.hstore
+    Sequel.hstore_op
+    Sequel.pg_json
+    Sequel.pg_range
+    Sequel.pg_range_op
+
+* The Sequel::SQL::IdentifierMethods module has been removed.  This
+  module was only included in Symbol if the core_extensions were
+  enabled.  Since it only defined a single method, now the core
+  extensions just define that method directly on Symbol.
+
+* The swift adapter now requires swift-db-{postgres,mysql,sqlite3}
+  gems instead of the swift gem.  swift/postgres requires
+  swift-db-postgres 0.2.0+, swift/sqlite requires swift-db-sqlite
+  0.1.2+, and swift/mysql requires swift-db-mysql.
+
+* Sequel will no longer typecast a string to a PostgreSQL array
+  or hstore column in a model column setter.  This is because the
+  parsers that Sequel uses were designed to support only
+  PostgreSQL's output format.  It's unlikely that a user would
+  provide that format for typecasting, and while there aren't known
+  security issues with the parsers, they were not designed to handle
+  arbtirary user input, so typecasting from string is no longer
+  allowed and will now raise an error.
+
+  The only reason such typecasting was allowed in the first place
+  was to work around issues in the jdbc/postgres, do/postgres, and
+  swift/postgres adapters, using the the typecast_on_load plugin.
+  If you were previously using the typecast_on_load plugin for
+  hstore or array columns, you need to switch to using the new
+  pg_typecast_on_load plugin.
+
+* The private get_conversion_procs method in the postgres adapter
+  no longer accepts an argument.
+
+* The Sequel::Postgres::PGArray::DatabaseMethods singleton
+  define_array_typecast_method method has been removed.  This
+  method was designed for internal use.
+
+* The change to make Sequel.expr split symbols can cause the
+  following type of code to break:
+
+    Sequel.expr(:column___alias).desc
+
+  This is because expr now returns an AliasedExpression, which
+  doesn't support the desc method.  However, as you can't
+  apply an order to an aliased expression, nobody should be
+  relying on this.

data/doc/schema_modification.rdoc

@@ -241,12 +241,12 @@ both take the same options as +index+.
   end
   
 Instead of using a block, you can use arguments that will be handled similarly
-to <tt>Dataset#filter</tt>:
+to <tt>Dataset#where</tt>:
 
   create_table(:artists) do
     primary_key :id
     String :name
-    constraint(:name_length_range, :char_length.sql_function(:name)=>3..50)
+    constraint(:name_length_range, Sequel.function(:char_length, :name)=>3..50)
   end
   
 ==== +check+
@@ -299,9 +299,6 @@ hash:
     add_column :copies_sold, Integer, :default=>0
   end
 
-When adding a column, it's a good idea to provide a default value, unless you
-want the value for all rows to be set to NULL.
-
 === +drop_column+
 
 As you may expect, +drop_column+ takes a column name and drops the column.  It's
@@ -439,7 +436,7 @@ There is no database independent method to drop an unnamed constraint.  Generall
 database will give it a name automatically, and you will have to figure out what it is.
 For that reason, you should not add unnamed constraints that you ever might need to remove.
 
-On MySQL, you must specify the type of constraint via a <tt>:type</tt> option:
+On some databases, you must specify the type of constraint via a <tt>:type</tt> option:
 
   alter_table(:albums) do
     drop_constraint(:albums_pk, :type=>:primary_key)
@@ -513,6 +510,16 @@ if you are using foreign keys and the database is enforcing referential
 integrity.  In general, you need to drop the tables containing the foreign
 keys before the tables containing the primary keys they reference.
 
+=== <tt>drop_table?</tt>
+
+<tt>drop_table?</tt> is similar to drop_table, except that it only drops
+the table if the table does not already exist.  On some databases, it uses
+<tt>IF NOT EXISTS</tt>, on others it does a separate query to check for
+existence.
+
+This should not be used inside migrations, as if the the tbale does not
+exist, it may mess up the migration.
+
 === +rename_table+
 
 You can rename an existing table using +rename_table+.  Like +rename_column+,
@@ -522,7 +529,7 @@ the first argument is the current name, and the second is the new name:
 
 === <tt>create_table!</tt>
 
-<tt>create_table!</tt> with the bang drops the table if it exists
+<tt>create_table!</tt> drops the table if it exists
 before attempting to create it, so:
 
   create_table!(:artists)
@@ -531,7 +538,7 @@ before attempting to create it, so:
 
 is the same as:
 
-  drop_table(:artists) if table_exists?(:artists)
+  drop_table?(:artists)
   create_table(:artists)
     primary_key :id
   end
@@ -541,7 +548,7 @@ mess up the migration.
 
 === <tt>create_table?</tt>
 
-<tt>create_table?</tt> with a question mark only creates the table if it does
+<tt>create_table?</tt> only creates the table if it does
 not already exist, so:
 
   create_table?(:artists)
@@ -550,9 +557,11 @@ not already exist, so:
 
 is the same as:
 
-  create_table(:artists)
-    primary_key :id
-  end unless table_exists?(:artists)
+  unless table_exists?(:artists)
+    create_table(:artists)
+      primary_key :id
+    end 
+  end
 
 Like <tt>create_table!</tt>, it should not be used inside migrations.
 
@@ -564,7 +573,7 @@ the same name, while +create_view+ will probably raise an error.  Both methods
 take the name as the first argument, and either an string or a dataset as the
 second argument:
 
-  create_view(:gold_albums, DB[:albums].filter{copies_sold > 500000})
+  create_view(:gold_albums, DB[:albums].where{copies_sold > 500000})
   create_or_replace_view(:gold_albums, "SELECT * FROM albums WHERE copies_sold > 500000")
 
 === +drop_view+

data/doc/sharding.rdoc

@@ -109,7 +109,7 @@ schemas, so you should always have a default server that works.
 
 To set the shard for a given query, you use the Dataset#server method:
 
-  DB[:hashes].server(:a).filter(:hash=>/31337/)
+  DB[:hashes].server(:a).where(:hash=>/31337/)
   
 That will return all matching rows on the hash_host_a shard that have a hash
 column that contains 31337.
@@ -119,10 +119,11 @@ work, you might want to add a method to the dataset that automatically sets
 the shard to use.  This is fairly easy using a Sequel::Model:
 
   class Rainbow < Sequel::Model(:hashes)
-    def_dataset_method(:plaintext_for_hash) do |hash|
-      raise(ArgumentError, 'Invalid SHA-1 Hash') unless /\A[0-9a-f]{40}\z/.match(hash)
-      row = self.server(hash[0...1].to_sym).first(:hash=>hash)
-      row[:plaintext] if row
+    dataset_module do
+      def plaintext_for_hash(hash)
+        raise(ArgumentError, 'Invalid SHA-1 Hash') unless /\A[0-9a-f]{40}\z/.match(hash)
+        server(hash[0...1].to_sym).where(:hash=>hash).get(:plaintext)
+      end
     end
   end
   
@@ -179,8 +180,7 @@ same shard, it can get a bit redundent to specify the same shard for all of them
 The server_block extension adds a Database#with_server method that scopes all database
 access inside the block to the given shard by default:
 
-  Sequel.extension :server_block
-  DB.extend Sequel::ServerBlock
+  DB.extension :server_block
   DB.with_server(:a) do
     # this SELECT query uses the "a" shard
     if r = Rainbow.first(:hash=>/31337/)
@@ -208,8 +208,7 @@ shards on the fly, but it is a bit cumbersome to work with truly arbitrary serve
 The arbitrary_servers extension allows you to pass a server/shard options hash as the
 server to use, and those options will be merged directly into the database's default options:
 
-  Sequel.extension :arbitrary_servers
-  DB.pool.extend Sequel::ArbitraryServers
+  DB.extension :arbitrary_servers
   DB[:rainbows].server(:host=>'hash_host_a').all
   # or
   DB[:rainbows].server(:host=>'hash_host_b', :database=>'backup').all

data/doc/sql.rdoc

@@ -73,10 +73,14 @@ You can also use <tt>Database#<<</tt>:
 
 === Other Places
 
-Almost everywhere in Sequel, you can drop down to literal SQL by providing a literal string, which you can create with <tt>String#lit</tt>:
+Almost everywhere in Sequel, you can drop down to literal SQL by providing a literal string, which you can create with <tt>Sequel.lit</tt>:
 
   DB[:albums].select('name') # SELECT 'name' FROM albums
-  DB[:albums].select('name'.lit) # SELECT name FROM albums
+  DB[:albums].select(Sequel.lit('name')) # SELECT name FROM albums
+
+For a simpler way of creating literal strings, you can also use the {core_extensions extension}[link:files/doc/core_extensions_rdoc.html], which adds the <tt>String#lit</tt> method, and other methods that integrate Sequel's DSL with the ruby language:
+
+  DB[:albums].select('name'.lit)
 
 So you can use Sequel's DSL everywhere you find it helpful, and fallback to literal SQL if the DSL can't do what you want or you just find literal SQL easier.
 
@@ -129,9 +133,9 @@ Also note that specifying the period inside the symbol doesn't work if you are q
 
   :"table.column" # "table.column"
 
-The other way to qualify an identifier is to use the +qualify+ method on the column symbol with the table symbol:
+The other way to qualify an identifier is to use the <tt>Sequel.qualify</tt> with the table and column symbols:
 
-  :column.qualify(:table) # "table"."column"
+  Sequel.qualify(:table, :column) # "table"."column"
 
 Another way to generate identifiers is to use Sequel's {virtual row support}[link:files/doc/virtual_rows_rdoc.html]:
 
@@ -169,37 +173,37 @@ You can combine this with implicit qualification:
 
   :table__column___alias # "table"."column" AS "alias"
 
-You can also use the +as+ method on symbols and most Sequel-specific expression objects:
+You can also use the <tt>Sequel.as</tt> method to create an alias, and the +as+ method on most Sequel-specific expression objects:
 
-  :column.as(:alias) # "column" AS "alias"
-  :column.qualify(:table).as(:alias) # "table"."column" AS "alias"
+  Sequel.as(:column, :alias) # "column" AS "alias"
+  Sequel.qualify(:table, :column).as(:alias) # "table"."column" AS "alias"
 
 === Functions
 
 The easiest way to use SQL functions is via a virtual row:
 
-  DB[:albums].select{function{}} # SELECT function() FROM "albums"
-  DB[:albums].select{function(col1, col2)} # SELECT function("col1", "col2") FROM "albums"
+  DB[:albums].select{func{}} # SELECT func() FROM "albums"
+  DB[:albums].select{func(col1, col2)} # SELECT func("col1", "col2") FROM "albums"
 
-You can also use the +sql_function+ method on the symbol that contains the function name:
+You can also use the <tt>Sequel.function</tt> method on the symbol that contains the function name:
 
-  :function.sql_function # function()
-  :function.sql_function(:col1, :col2) # function("col1", "col2")
+  Sequel.function(:func) # func()
+  Sequel.function(:func, :col1, :col2) # func("col1", "col2")
 
 === Aggregate Functions
 
 Aggregate functions work the same way as normal functions, since they share the same syntax:
 
-  :sum.sql_function(:column) # sum(column)
+  Sequel.function(:sum, :column) # sum(column)
 
 However, if you want to use the DISTINCT modifier to an aggregate function, you either have to use literal SQL or a virtual row block:
 
-  :sum.sql_function('DISTINCT column'.lit) # sum(DISTINCT column)
+  Sequel.function(:sum, Sequel.lit('DISTINCT column')) # sum(DISTINCT column)
   DB[:albums].select{sum(:distinct, :column){}} # SELECT sum(DISTINCT column) FROM albums
 
 If you want to use the wildcard as the sole argument of the aggregate function, you again have to use literal SQL or a virtual row block:
 
-  :count.sql_function('*'.lit) # count(*)
+  Sequel.function(:count, Sequel.lit('*')) # count(*)
   DB[:albums].select{count(:*){}} # SELECT count(*) FROM albums
 
 Note that Sequel provides helper methods for aggregate functions such as +count+, +sum+, +min+, +max+, +avg+, and +group_and_count+, which handle common uses of aggregate functions.
@@ -232,28 +236,35 @@ You can also specify this as an array of two element arrays:
 
 === Not Equal Operator (!=)
 
-You can specify a not equals condition by inverting the hash or array of two element arrays using +sql_negate+ or ~:
+You can specify a not equals condition by inverting the hash or array of two element arrays using <tt>Sequel.negate</tt> or <tt>Sequel.~</tt>:
+
+  Sequel.negate(:column => 1)   # ("column" != 1)
+  Sequel.negate([[:column, 1]]) # ("column" != 1)
+  Sequel.~(:column => 1)        # ("column" != 1)
+  Sequel.~([[:column, 1]])      # ("column" != 1)
 
-  {:column => 1}.sql_negate # ("column" != 1)
-  [[:column, 1]].sql_negate # ("column" != 1)
-  ~{:column => 1} # ("column" != 1)
-  ~[[:column, 1]] # ("column" != 1)
+The difference between the two is that negate only works on hashes and arrays of element arrays, and it negates all entries in the, while ~ does a general inversion.  This is best shown by an example with multiple entries:
+
+  Sequel.negate(:column => 1, :foo => 2)   # (("column" != 1) AND (foo != 2))
+  Sequel.~(:column => 1, :foo => 2)        # (("column" != 1) OR (foo != 2))
 
 The most common need for not equals is in filters, in which case you can use the +exclude+ method:
 
   DB[:albums].exclude(:column=>1) # SELECT * FROM "albums" WHERE ("column" != 1)
 
+Note that +exclude+ does a generalized inversion, similar to <tt>Sequel.~</tt>.
+
 === Inclusion and Exclusion Operators (IN, NOT IN)
 
 Sequel also uses hashes to specify inclusion, and inversions of those hashes to specify exclusion:
 
   {:column=>[1, 2, 3]} # ("column" IN (1, 2, 3))
-  ~{:column=>[1, 2, 3]} # ("column" NOT IN (1, 2, 3))
+  Sequel.~(:column=>[1, 2, 3]) # ("column" NOT IN (1, 2, 3))
 
 As you may have guessed, Sequel switches from an = to an IN when the hash value is an array.  It also does this for datasets, which easily allows you to test for inclusion and exclusion in a subselect:
 
   {:column=>DB[:albums].select(:id)} # ("column" IN (SELECT "id" FROM "albums"))
-  ~{:column=>DB[:albums].select(:id)} # ("column" NOT IN (SELECT "id" FROM "albums"))
+  Sequel.~(:column=>DB[:albums].select(:id)) # ("column" NOT IN (SELECT "id" FROM "albums"))
 
 Sequel also supports the SQL EXISTS operator using <tt>Dataset#exists</tt>:
 
@@ -269,19 +280,19 @@ Hashes in Sequel use IS if the value is true, false, or nil:
 
 Negation works the same way as it does for equality and inclusion:
 
-  {:column=>nil).sql_negate # ("column" IS NOT NULL)
-  {:column=>true).sql_negate # ("column" IS NOT TRUE)
-  {:column=>false).sql_negate # ("column" IS NOT FALSE)
+  Sequel.~(:column=>nil) # ("column" IS NOT NULL)
+  Sequel.~(:column=>true) # ("column" IS NOT TRUE)
+  Sequel.~(:column=>false) # ("column" IS NOT FALSE)
 
 === Inversion Operator (NOT)
 
 Sequel's general inversion operator is ~, which works on symbols and most Sequel-specific expression objects:
 
-  ~:column # NOT "column"
+  Sequel.~(:column) # NOT "column"
 
 Note that ~ will actually apply the inversion operation to the underlying object, which is why
   
-  ~{:column=>1}
+  Sequel.~(:column=>1)
 
 produces <tt>(column != 1)</tt> instead of <tt>NOT (column = 1)</tt>.
 
@@ -289,198 +300,229 @@ produces <tt>(column != 1)</tt> instead of <tt>NOT (column = 1)</tt>.
 
 Sequel defines the inequality operators directly on most Sequel-specific expression objects:
 
-  :column.qualify(:table) > 1 # ("table"."column" > 1)
-  :column.qualify(:table) < 1 # ("table"."column" < 1)
-  :function.sql_function >= 1 # (function() >= 1)
-  :function.sql_function(:column) <= 1 # (function("column") <= 1)
+  Sequel.qualify(:table, :column) > 1 # ("table"."column" > 1)
+  Sequel.qualify(:table, :column) < 1 # ("table"."column" < 1)
+  Sequel.function(:func) >= 1 # (func() >= 1)
+  Sequel.function(:func, :column) <= 1 # (func("column") <= 1)
 
-If you want to use them on a symbol, you should call +identifier+ on the symbol:
+If you want to use them on a symbol, you should call <tt>Sequel.expr</tt> with the symbol:
 
-  :column.identifier > 1 # ("column" > 1)
+  Sequel.expr(:column) > 1 # ("column" > 1)
 
 A common use of virtual rows is to handle inequality operators:
 
-  DB[:albums].filter{col1 > col2} # SELECT * FROM "albums" WHERE ("col1" > "col2")
+  DB[:albums].where{col1 > col2} # SELECT * FROM "albums" WHERE ("col1" > "col2")
 
 === Standard Mathematical Operators (+ - * /)
 
-The standard mathematical operates are defined on symbol and most Sequel-specific expression objects:
+The standard mathematical operates are defined on most Sequel-specific expression objects:
+
+  Sequel.expr(:column) + 1 # "column" + 1
+  Sequel.expr(:table__column) - 1 # "table"."column" - 1
+  Sequel.qualify(:table, :column) * 1 # "table"."column" * 1
+  Sequel.expr(:column) / 1 # "column" / 1
 
-  :column + 1 # "column" + 1
-  :table__column - 1 # "table"."column" - 1
-  :column.qualify(:table) * 1 # "table"."column" * 1
-  :column / 1 # "column" / 1
+You can also call the operator methods directly on the Sequel module:
+
+  Sequel.+(:column, 1) # "column" + 1
+  Sequel.-(:table__column, 1) # "table"."column" - 1
+  Sequel.*(Sequel.qualify(:table, :column), 1) # "table"."column" * 1
+  Sequel./(:column, 1) # "column" / 1
 
 Note that the following does not work:
 
-  1 + :column # raises TypeError
+  1 + Sequel.expr(:column) # raises TypeError
 
-For commutative operates such as + and *, this isn't a problem as you can just reorder, but non-commutative operators such as - and / cannot be expressed directly.  However, Sequel comes with an +sql_expr+ extension that adds an +sql_expr+ method to all objects, allowing you to do:
+For commutative operates such as + and *, this isn't a problem as you can just reorder, but non-commutative operators such as - and / cannot be expressed directly.  The solution is to use one of the methods on the Sequel module:
 
-  Sequel.extension :sql_expr
-  1.sql_expr / :column # (1 / "column")
+  Sequel.expr(1) / :column # (1 / "column")
+  Sequel./(1, :column) # (1 / "column")
 
 === Boolean Operators (AND OR)
 
-Sequel defines the & and | methods on symbols, hashes, and most Sequel-specific expression objects to handle AND and OR:
+Sequel defines the & and | methods on most Sequel-specific expression objects to handle AND and OR:
 
-  :column1 & :column2 # ("column1" AND "column2")
-  {:column1=>1} | {:column2=>2} # (("column1" = 1) OR ("column2" = 2))
-  (:function.sql_function > 1) & :column3 # ((function() > 1) AND "column3")
+  Sequel.expr(:column1) & :column2 # ("column1" AND "column2")
+  Sequel.expr(:column1=>1) | {:column2=>2} # (("column1" = 1) OR ("column2" = 2))
+  (Sequel.function(:func) > 1) & :column3 # ((func() > 1) AND "column3")
 
 Note the use of parentheses in the last statement.  If you omit them, you won't get what you expect:
 
-  :function.sql_function > 1 & :column3 # (function() > 1)
+  Sequel.function(:func) > 1 & :column3 # (func() > 1)
 
 This is because & has higher precedence than >, so it is parsed as:
 
-  :function.sql_function > (1 & :column3)
+  Sequel.function(:func) > (1 & :column3)
 
 In this case, <tt>:column3.to_int</tt> returns an odd integer, so:
 
   1 & :column3 # => 1
 
+You and also use the <tt>Sequel.&</tt> and <tt>Sequel.|</tt> methods:
+
+  Sequel.&(:column1, :column2) # ("column1" AND "column2")
+  Sequel.|({:column1=>1}, {:column2=>2}) # (("column1" = 1) OR ("column2" = 2))
+
 You can use hashes and arrays of two element arrays to specify AND and OR with equality conditions:
 
   {:column1=>1, :column2=>2} # (("column1" = 1) AND ("column2" = 2))
   [[:column1, 1], [:column2, 2]] # (("column1" = 1) AND ("column2" = 2))
 
-As you can see, these literalize with ANDs by default.  You can use the +sql_or+ method to use OR instead:
+As you can see, these literalize with ANDs by default.  You can use the <tt>Sequel.or</tt> method to use OR instead:
 
-  {:column1=>1, :column2=>2}.sql_or # (("column1" = 1) OR ("column2" = 2))
+  Sequel.or(:column1=>1, :column2=>2) # (("column1" = 1) OR ("column2" = 2))
 
-You've already seen the +sql_negate+ method, which will use ANDs if multiple entries are used:
+You've already seen the <tt>Sequel.negate</tt> method, which will use ANDs if multiple entries are used:
 
-  {:column1=>1, :column2=>2}.sql_negate # (("column1" != 1) AND ("column2" != 2))
+  Sequel.negate(:column1=>1, :column2=>2) # (("column1" != 1) AND ("column2" != 2))
  
-To negate while using ORs, the ~ operator can be used:
+To negate while using ORs, the <tt>Sequel.~</tt> operator can be used:
 
-  ~{:column1=>1, :column2=>2} # (("column1" != 1) OR ("column2" != 2))
+  Sequel.~(:column1=>1, :column2=>2) # (("column1" != 1) OR ("column2" != 2))
 
-Note that <tt>Dataset#exclude</tt> uses ~, not +sql_negate+:
+Note again that <tt>Dataset#exclude</tt> uses ~, not +negate+:
 
   DB[:albums].exclude(:column1=>1, :column2=>2) # SELECT * FROM "albums" WHERE (("column" != 1) OR ("column2" != 2))
 
 === Casts
 
-Casting in Sequel is done with the +cast+ method, which is available on strings, symbols, and most of the Sequel-specific expression objects:
+Casting in Sequel is done with the +cast+ method, which is available on most of the Sequel-specific expression objects:
 
-  :name.cast(:text) # CAST("name" AS text)
-  '1'.cast(:integer) # CAST('1' AS integer)
-  :column.qualify(:table).cast(:date) # CAST("table"."column" AS date)
+  Sequel.expr(:name).cast(:text) # CAST("name" AS text)
+  Sequel.expr('1').cast(:integer) # CAST('1' AS integer)
+  Sequel.qualify(:table, :column).cast(:date) # CAST("table"."column" AS date)
 
-=== Bitwise Mathematical Operators (& | ^ << >> ~)
+You can also use the <tt>Sequel.cast</tt> method:
 
-Sequel allows the use of bitwise mathematical operators on Sequel::SQL::NumericExpression objects:
+  Sequel.cast(:name, :text) # CAST("name" AS text)
 
-  :number + 1 # => #<Sequel::SQL::NumericExpression ...>
-  (:number + 1) & 5 # (("number" + 1) & 5)
+=== Bitwise Mathematical Operators (& | ^ << >> ~)
 
-As you can see, when you use the + operator on a symbol, you get a NumericExpression.  You can turn a symbol into a NumericExpression using +sql_number+:
+Sequel allows the use of bitwise mathematical operators on Sequel::SQL::NumericExpression objects:
 
-  :number.sql_number | 5 # ("number" | 5)
+  Sequel.expr(:number) + 1 # => #<Sequel::SQL::NumericExpression ...>
+  (Sequel.expr(:number) + 1) & 5 # (("number" + 1) & 5)
 
-+sql_number+ also works on the many other Sequel-specific expression objects:
+As you can see, when you use the + operator on a symbol, you get a NumericExpression.  You can turn an expression a NumericExpression using +sql_number+:
 
-  :function.sql_function.sql_number << 7 # (function() << 7)
-  :name.cast(:integer).sql_number >> 8 # (CAST("name" AS integer) >> 8)
+  Sequel.expr(:number).sql_number | 5 # ("number" | 5)
+  Sequel.function(:func).sql_number << 7 # (func() << 7)
+  Sequel.cast(:name, :integer).sql_number >> 8 # (CAST("name" AS integer) >> 8)
 
 Sequel allows you to do the cast and conversion at the same time via +cast_numeric+:
 
-  :name.cast_numeric ^ 9 # (CAST("name" AS integer) ^ 9)
+  Sequel.expr(:name).cast_numeric ^ 9 # (CAST("name" AS integer) ^ 9)
 
-Note that &, |, and ~ are already defined to do AND, OR, and NOT on most objects, so if you want to use the bitwise operators, you need to make sure that they are converted first:
+Note that &, |, and ~ are already defined to do AND, OR, and NOT on most expressions, so if you want to use the bitwise operators, you need to make sure that they are converted first:
 
-  ~:name # NOT "name"
-  ~:name.sql_number # ~"name"
+  ~Sequel.expr(:name) # NOT "name"
+  ~Sequel.expr(:name).sql_number # ~"name"
 
 === String Operators (||, LIKE, Regexp)
 
-Sequel allows the use of the string concatenation operator on Sequel::SQL::StringExpression objects, which can be created using the +sql_string+ method:
+Sequel allows the use of the string concatenation operator on Sequel::SQL::StringExpression objects, which can be created using the +sql_string+ method on an expression:
 
-  :name.sql_string + ' - Name' # ("name" || ' - Name')
+  Sequel.expr(:name).sql_string + ' - Name' # ("name" || ' - Name')
 
 Just like for the bitwise operators, Sequel allows you do do the cast and conversion at the same time via +cast_string+:
 
-  :number.cast_string + ' - Number' # (CAST(number AS varchar(255)) || ' - Number')
+  Sequel.expr(:number).cast_string + ' - Number' # (CAST(number AS varchar(255)) || ' - Number')
 
 Note that similar to the mathematical operators, you cannot switch the order the expression and have it work:
 
-  'Name - ' + :name.sql_string # raises TypeError
+  'Name - ' + Sequel.expr(:name).sql_string # raises TypeError
 
-Just like for the mathematical operators, you can use the +sql_expr+ extension to work around this:
+Just like for the mathematical operators, you can use <tt>Sequel.expr</tt> to wrap the object:
 
-  Sequel.extension :sql_expr
-  'Name - '.sql_expr + :name # ('Name - ' || "name")
+  Sequel.expr('Name - ') + :name # ('Name - ' || "name")
   
-Sequel also adds an <tt>Array#sql_string_join</tt> method, which concatenates all of the elements in the array:
+The <tt>Sequel.join</tt> method concatenates all of the elements in the array:
 
-  ['Name', :name].sql_string_join # ('Name' || "name")
+  Sequel.join(['Name', :name]) # ('Name' || "name")
 
 Just like ruby's <tt>String#join</tt>, you can provide an argument for a string used to join each element:
 
-  ['Name', :name].sql_string_join(' - ') # ('Name' || ' - ' || "name")
+  Sequel.join(['Name', :name], ' - ') # ('Name' || ' - ' || "name")
+
+For the LIKE operator, Sequel defines the +like+ and +ilike+ methods on most Sequel-specific expression objects:
 
-For the LIKE operator, Sequel defines the +like+ and +ilike+ methods on symbol and most Sequel-specific expression objects:
+  Sequel.expr(:name).like('A%') # ("name" LIKE 'A%') 
+  Sequel.expr(:name).ilike('A%') # ("name" ILIKE 'A%') 
 
-  :name.like('A%') # ("name" LIKE 'A%') 
-  :name.qualify.ilike('A%') # ("name" ILIKE 'A%') 
+You can also use the <tt>Sequel.like</tt> and <tt>Sequel.ilike</tt> methods:
 
-Note the above syntax, while Sequel's default, is specific to PostgreSQL.  However, most other adapters override the behavior.  For example, on MySQL, Sequel uses LIKE BINARY for +like+, and LIKE for +ilike+.  If the database supports both case sensitive and case insensitive LIKE, then +like+ will use a case sensitive LIKE, and +ilike+ will use a case insensitive LIKE.  Some databases only support case insensitive behavior, in which case +like+ and +ilike+ will act identically.
+  Sequel.like(:name, 'A%') # ("name" LIKE 'A%') 
+  Sequel.ilike(:name, 'A%') # ("name" ILIKE 'A%') 
+
+Note the above syntax for ilike, while Sequel's default, is specific to PostgreSQL.  However, most other adapters override the behavior.  For example, on MySQL, Sequel uses LIKE BINARY for +like+, and LIKE for +ilike+.  If the database supports both case sensitive and case insensitive LIKE, then +like+ will use a case sensitive LIKE, and +ilike+ will use a case insensitive LIKE.
 
 Inverting the LIKE operator works like other inversions:
 
-  ~:name.like('A%') # ("name" NOT LIKE 'A%')
+  ~Sequel.like(:name, 'A%') # ("name" NOT LIKE 'A%')
 
-Sequel also supports SQL regular expressions on MySQL and PostgreSQL.  You can use these by passing a ruby regular expression to the +like+ or +ilike+ method, or by making the regular expression a hash value:
+Sequel also supports SQL regular expressions on MySQL and PostgreSQL.  You can use these by passing a ruby regular expression to +like+ or +ilike+, or by making the regular expression a hash value:
 
-  :name.like(/^A/) # ("name" ~ '^A')
-  ~:name.ilike(/^A/) # ("name" !~* '^A')
+  Sequel.like(:name, /^A/) # ("name" ~ '^A')
+  ~Sequel.ilike(:name, /^A/) # ("name" !~* '^A')
   {:name=>/^A/i} # ("name" ~* '^A')
-  ~{:name=>/^A/} # ("name" !~ '^A')
+  Sequel.~(:name=>/^A/) # ("name" !~ '^A')
 
 Note that using +ilike+ with a regular expression will always make the regexp case insensitive.  If you use +like+ or the hash with regexp value, it will only be case insensitive if the Regexp itself is case insensitive.
 
 === Order Specifications (ASC, DESC)
 
-Sequel supports specifying ascending or descending order using the +asc+ and +desc+ method on symbols and most Sequel-specific expression objects:
+Sequel supports specifying ascending or descending order using the asc+ and +desc+ method on most Sequel-specific expression objects:
+
+  Sequel.expr(:column).asc # "column" ASC
+  Sequel.expr(:column).qualify(:table).desc # "table"."column" DESC
 
-  :column.asc # "column" ASC
-  :column.qualify(:table).desc # "table"."column" DESC
+You can also use the <tt>Sequel.asc</tt> and <tt>Sequel.desc</tt> methods:
+
+  Sequel.asc(:column) # "column" ASC
+  Sequel.desc(Sequel.expr(:column).qualify(:table)) # "table"."column" DESC
+
+On some databases, you can specify null ordering:
+
+  Sequel.asc(:column, :nulls=>:first) # "column" ASC NULLS FIRST
+  Sequel.desc(Sequel.expr(:column).qualify(:table), :nulls=>:last) # "table"."column" DESC NULLS LAST
 
 === All Columns (.*)
 
-To select all columns in a table, Sequel supports the * method on symbols without an argument:
+To select all columns in a table, Sequel supports the * method on identifiers without an argument:
 
-  :table.* # "table".*
+  Sequel.expr(:table).* # "table".*
 
 === CASE statements
 
-Sequel allows the easy production of SQL CASE statements using the +case+ method of hashes and arrays of two element arrays.  The argument to +case+ is the default value, the keys of the hash (or first element in each array) is the WHEN condition, and the values of the hash (or second element in each array) is the THEN result.  Here are some examples:
+Sequel allows the easy production of SQL CASE statements using the <tt>Sequel.case</tt> method.  The first argument is a hash or array of two element arrays representing the conditions, the second argument is the default value (ELSE).   The keys of the hash (or first element in each array) is the WHEN condition, and the values of the hash (or second element in each array) is the THEN result.  Here are some examples:
 
-  {:column=>1}.case(0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
-  [[column, 1]].case(0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
-  {{:column=>nil}=>1}.case(0) # (CASE WHEN (column IS NULL) THEN 1 ELSE 0 END)
+  Sequel.case({:column=>1, 0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
+  Sequel.case([[column, 1]], 0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
+  Sequel.case({{:column=>nil}=>1}, 0) # (CASE WHEN (column IS NULL) THEN 1 ELSE 0 END)
 
 If the hash or array has multiple arguments, multiple WHEN clauses are used:
 
-  {:c=>1, :d=>2}.case(0) # (CASE WHEN "c" THEN 1 WHEN "d" THEN 2 ELSE 0 END)
-  [[:c, 1], [:d, 2]].case(0) # (CASE WHEN "c" THEN 1 WHEN "d" THEN 2 ELSE 0 END)
+  Sequel.case({:c=>1, :d=>2}, 0) # (CASE WHEN "c" THEN 1 WHEN "d" THEN 2 ELSE 0 END)
+  Sequel.case([[:c, 1], [:d, 2]], 0) # (CASE WHEN "c" THEN 1 WHEN "d" THEN 2 ELSE 0 END)
 
 If you provide a 2nd argument to CASE, it goes between CASE and WHEN:
 
-  {2=>1, 3=>5}.case(0, :column) # (CASE column WHEN 2 THEN 1 WHEN 3 THEN 5 ELSE 0 END)
+  Sequel.case({2=>1, 3=>5}, 0, :column) # (CASE column WHEN 2 THEN 1 WHEN 3 THEN 5 ELSE 0 END)
 
 === Subscripts/Array Access ([])
 
-Sequel supports SQL subscripts using the +sql_subscript+ method on symbols and most Sequel-specific expression objects:
+Sequel supports SQL subscripts using the +sql_subscript+ method on most Sequel-specific expression objects:
+
+  Sequel.expr(:column).sql_subscript(3) # column[3]
+  Sequel.expr(:column).qualify(:table).sql_subscript(3) # table.column[3]
+
+You can also use the <tt>Sequel.subscript</tt> method:
 
-  :column.sql_subscript(3) # column[3]
-  :column.qualify(:table).sql_subscript(3) # table.column[3]
+  Sequel.subscript(:column, 3) # column[3]
 
 Just like in SQL, you can use any expression as a subscript:
 
-  :column.sql_subscript(:function.sql_function) # column[function()]
+  Sequel.subscript(:column, Sequel.function(:func)) # column[func()]
 
 == Building Queries in Sequel
 
@@ -504,12 +546,12 @@ If you don't want to select from any FROM tables, use no arguments:
 
 Once you have your dataset object, you build queries by chaining methods, usually with one method per clause in the query:
 
-  DB[:albums].select(:id, :name).where(:name.like('A%')).order(:name)
+  DB[:albums].select(:id, :name).where(Sequel.like(:name, 'A%')).order(:name)
   # SELECT id, name FROM albums WHERE (name LIKE 'A%') ORDER BY name
 
 Note that the order of your method chain is not usually important unless you have multiple methods that affect the same clause:
 
-  DB[:albums].order(:name).where(:name.like('A%')).select(:id, :name)
+  DB[:albums].order(:name).where(Sequel.like(:name, 'A%')).select(:id, :name)
   # SELECT id, name FROM albums WHERE (name LIKE 'A%') ORDER BY name
 
 === Using the Same Dataset for SELECT, INSERT, UPDATE, and DELETE
@@ -524,13 +566,13 @@ Also note that while the SELECT clause is displayed when you look at a dataset,
 
 In general, the +insert+, +update+, and +delete+ methods use the appropriate clauses you defined on the dataset:
 
-  ds = DB[:albums].filter(:id=>1)
+  ds = DB[:albums].where(:id=>1)
   ds.all # SELECT * FROM albums WHERE (id = 1)
   ds.insert(:name=>'RF') # INSERT INTO albums (name) VALUES ('RF')
   ds.update(:name=>'RF') # UPDATE albums SET name = 'RF' WHERE (id = 1)
   ds.delete # DELETE FROM albums WHERE (id = 1)
 
-Note how +update+ and +delete+ used the +filter+ argument, but that +insert+ did not, because INSERT doesn't use a WHERE clause.
+Note how +update+ and +delete+ used the +where+ argument, but that +insert+ did not, because INSERT doesn't use a WHERE clause.
 
 === Methods Used for Each SQL Clause