sequel 4.26.0 → 5.37.0

data/doc/sharding.rdoc

@@ -1,7 +1,7 @@
-= Read-Only Slaves/Writable Master and Database Sharding
+= Primary/Replica Configurations and Database Sharding
 
-Sequel has support for read only slave databases
-with a writable master database, as well as database sharding (where you can
+Sequel has support for primary/replica configurations (writable primary
+database with read only replicas databases), as well as database sharding (where you can
 pick a server to use for a given dataset).  Support for both
 features is database independent, and should work for all database adapters
 that ship with Sequel.
@@ -13,7 +13,7 @@ option.  Using the :servers database option makes Sequel use a connection pool
 class that supports sharding, and the minimum required to enable sharding
 support is to use the empty hash:
 
-  DB=Sequel.connect('postgres://master_server/database', :servers=>{})
+  DB=Sequel.connect('postgres://primary_server/database', servers: {})
 
 In most cases, you are probably not going to want to use an empty hash.  Keys in the server hash are
 not restricted to type, but the general recommendation is to use a symbol
@@ -28,69 +28,69 @@ a :host entry in each shard's hash.
 Note that all servers should have the same schema for all
 tables you are accessing, unless you really know what you are doing.
 
-== Master and Slave Database Configurations
+== Primary and Replica Database Configurations
 
-=== Single Read-Only Slave, Single Master
+=== Single Primary, Single Replica
 
-To use a single, read-only slave that handles SELECT queries, the following
+To use a single, read-only replica that handles SELECT queries, the following
 is the simplest configuration:
 
-  DB=Sequel.connect('postgres://master_server/database', \
-    :servers=>{:read_only=>{:host=>'slave_server'}})
+  DB=Sequel.connect('postgres://primary_server/database', 
+    servers: {read_only: {host: 'replica_server'}})
 
-This will use the slave_server for SELECT queries and master_server for
+This will use the replica_server for SELECT queries and primary_server for
 other queries.
 
 If you want to ensure your queries are going to a specific database, you
 can force this for a given query by using the .server method and passing 
 the symbol name defined in the connect options. For example:
 
-  # Force the SELECT to run on the master
+  # Force the SELECT to run on the primary server
   DB[:users].server(:default).all
 
-  # Force the SELECT to run on the read-only slave
-  DB[:users].server(:read_only).all
+  # Force the DELETE to run on the read-only replica
+  DB[:users].server(:read_only).delete
 
-=== Multiple Read-Only Slaves, Single Master
+=== Single Primary, Multiple Replicas
 
-Let's say you have 4 slave database servers with names slave_server0,
-slave_server1, slave_server2, and slave_server3.
+Let's say you have 4 replica servers with names replica_server0,
+replica_server1, replica_server2, and replica_server3.
 
   num_read_only = 4
   read_only_host = rand(num_read_only)
   read_only_proc = proc do |db|
-    {:host=>"slave_server#{(read_only_host+=1) % num_read_only}"}
+    {host: "replica_server#{(read_only_host+=1) % num_read_only}"}
   end
-  DB=Sequel.connect('postgres://master_server/database', \
-    :servers=>{:read_only=>read_only_proc})
+  DB=Sequel.connect('postgres://primary_server/database',
+    servers: {read_only: read_only_proc})
 
-This will use one of the slave servers for SELECT queries and use the
-master_server for other queries.  It's also possible to pick a random host
+This will use one of the replica servers for SELECT queries and use the
+primary server for other queries.  It's also possible to pick a random host
 instead of using the round robin approach presented above, but that can result
 in less optimal resource usage.
 
-=== Multiple Read-Only Slaves, Multiple Masters
+=== Multiple Primary, Multiple Replicas
 
-This involves the same basic idea as the multiple slaves, single master, but
-it shows that the master database is named :default.  So for 4 masters and
-4 slaves:
+This involves the same basic idea as the multiple replicas, single primary, but
+it shows that the primary database is named :default.  So for 4 primary servers and
+4 replica servers:
 
   num_read_only = 4
   read_only_host = rand(num_read_only)
   read_only_proc = proc do |db|
-    {:host=>"slave_server#{(read_only_host+=1) % num_read_only}"}
+    {host: "replica_server#{(read_only_host+=1) % num_read_only}"}
   end
   num_default = 4
   default_host = rand(num_default)
   default_proc = proc do |db|
-    {:host=>"master_server#{(default_host+=1) % num_default}"}
+    {host: "primary_server#{(default_host+=1) % num_default}"}
   end
-  DB=Sequel.connect('postgres://master_server/database', \
-    :servers=>{:default=>default_proc, :read_only=>read_only_proc})
+  DB=Sequel.connect('postgres://primary_server/database',
+    servers: {default: default_proc, read_only: read_only_proc})
   
 == Sharding
 
-There is specific support in Sequel for handling master/slave database
+There is specific support in Sequel for handling primary/replica database
 combinations, with the only necessary setup being the database configuration.
 However, since sharding is always going to be implementation dependent, Sequel
 supplies the basic infrastructure, but you have to tell it which server to use
@@ -100,16 +100,16 @@ of 16 shards).  First, you need to configure the database:
 
   servers = {}
   (('0'..'9').to_a + ('a'..'f').to_a).each do |hex|
-    servers[hex.to_sym] = {:host=>"hash_host_#{hex}"}
+    servers[hex.to_sym] = {host: "hash_host_#{hex}"}
   end
-  DB=Sequel.connect('postgres://hash_host/hashes', :servers=>servers)
+  DB=Sequel.connect('postgres://hash_host/hashes', servers: servers)
   
 This configures 17 servers, the 16 shard servers (/hash_host_[0-9a-f]/), and 1
 default server which will be used if no shard is specified ("hash_host").  If
 you want the default server to be one of the shard servers (e.g. hash_host_a),
 it's easiest to do:
 
-  DB=Sequel.connect('postgres://hash_host_a/hashes', :servers=>servers)
+  DB=Sequel.connect('postgres://hash_host_a/hashes', servers: servers)
 
 That will still set up a second pool of connections for the default server,
 since it considers the default server and shard servers independent.  Note that
@@ -120,7 +120,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).where(: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.
@@ -133,37 +133,39 @@ the shard to use.  This is fairly easy using a Sequel::Model:
     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)
+        server(hash[0...1].to_sym).where(hash: hash).get(:plaintext)
       end
     end
   end
   
   Rainbow.plaintext_for_hash("e580726d31f6e1ad216ffd87279e536d1f74e606")
 
+=== :servers_hash Option
+
 The connection pool can be further controlled to change how it handles attempts
 to access shards that haven't been configured.  The default is
 to assume the :default shard.  However, you can specify a
 different shard using the :servers_hash option when connecting
 to the database:
 
-  DB = Sequel.connect('postgres://...', :servers_hash=>Hash.new(:some_shard))
+  DB = Sequel.connect('postgres://...', servers_hash: Hash.new(:some_shard))
 
 You can also use this feature to raise an exception if an
 unconfigured shard is used:
 
-  DB = Sequel.connect('postgres://...', :servers_hash=>Hash.new{raise 'foo'})
+  DB = Sequel.connect('postgres://...', servers_hash: Hash.new{raise 'foo'})
 
 If you specify a :servers_hash option to raise an exception for non configured
 shards you should also explicitly specify a :read_only entry in your :servers option
 for the case where a shard is not specified. In most cases it is sufficient
 to make the :read_only entry the same as the :default shard:
 
-  servers = {:read_only => {}}
+  servers = {read_only: {}}
   (('0'..'9').to_a + ('a'..'f').to_a).each do |hex|
-    servers[hex.to_sym] = {:host=>"hash_host_#{hex}"}
+    servers[hex.to_sym] = {host: "hash_host_#{hex}"}
   end
-  DB=Sequel.connect('postgres://hash_host/hashes', :servers=>servers, 
-    :servers_hash=>Hash.new{raise Exception.new("Invalid Server")}) 
+  DB=Sequel.connect('postgres://hash_host/hashes', servers: servers, 
+    servers_hash: Hash.new{raise "Invalid Server"}) 
 
 === Sharding Plugin
 
@@ -176,7 +178,7 @@ work well with shards.  You just need to remember to set to model to use the plu
     plugin :sharding
   end
 
-  Rainbow.server(:a).first(:id=>1).update(:plaintext=>'VGM')
+  Rainbow.server(:a).first(id: 1).update(plaintext: 'VGM')
 
 If all of your models are sharded, you can set all models to use the plugin via:
 
@@ -186,7 +188,7 @@ If all of your models are sharded, you can set all models to use the plugin via:
 
 By default, you must specify the server/shard you want to use for every dataset/action,
 or Sequel will use the default shard.  If you have a group of queries that should use the
-same shard, it can get a bit redundent to specify the same shard for all of them.
+same shard, it can get a bit redundant 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:
@@ -194,7 +196,7 @@ access inside the block to the given shard by default:
   DB.extension :server_block
   DB.with_server(:a) do
     # this SELECT query uses the "a" shard
-    if r = Rainbow.first(:hash=>/31337/)
+    if r = Rainbow.first(hash: /31337/)
       r.count += 1
       # this UPDATE query also uses the "a" shard
       r.save
@@ -209,6 +211,19 @@ you retrieve the models inside the block and save them outside of the block.  If
 need to do that, call the server method explicitly on the dataset used to retrieve the
 model objects.
 
+The with_server method also supports a second argument for the default read_only server
+to use, which can be useful if you are mixing sharding and primary/replica servers:
+
+  DB.extension :server_block
+  DB.with_server(:a, :a_read_only) do
+    # this SELECT query uses the "a_read_only" shard
+    if r = Rainbow.first(hash: /31337/)
+      r.count += 1
+      # this UPDATE query also uses the "a" shard
+      r.save
+    end
+  end
+
 === arbitrary_servers Extension
 
 By default, Sequel's sharding support is designed to work with predefined shards.  It ships
@@ -220,13 +235,13 @@ The arbitrary_servers extension allows you to pass a server/shard options hash a
 server to use, and those options will be merged directly into the database's default options:
 
   DB.extension :arbitrary_servers
-  DB[:rainbows].server(:host=>'hash_host_a').all
+  DB[:rainbows].server(host: 'hash_host_a').all
   # or
-  DB[:rainbows].server(:host=>'hash_host_b', :database=>'backup').all
+  DB[:rainbows].server(host: 'hash_host_b', database: 'backup').all
 
 arbitrary_servers is designed to work well in conjunction with the server_block extension:
 
-  DB.with_server(:host=>'hash_host_b', :database=>'backup') do
+  DB.with_server(host: 'hash_host_b', database: 'backup') do
     DB.synchronize do
       # All queries here default to the backup database on hash_host_b
     end
@@ -255,3 +270,15 @@ the Database, just remove that option.  If you are setting:
   Sequel.single_threaded = true 
 
 just remove or comment out that code.
+
+== JDBC
+
+If you are using the jdbc adapter, note that it does not handle separate
+options such as +:host+, +:user+, and +:port+.  If you would like to use
+the +:servers+ option when connecting to a JDBC database, each hash value in
+the +servers+ option should contain a +:uri+ key with a JDBC connection string
+for that shard as the value.  Example:
+
+  DB=Sequel.connect('jdbc:postgresql://primary_server/database', 
+    servers: {read_only: {uri: 'jdbc:postgresql://replica_server/database'}})
+

data/doc/sql.rdoc

@@ -14,7 +14,7 @@ For SELECT queries, you should probably use <tt>Database#fetch</tt> with a strin
     puts row[:name]
   end
 
-<tt>Database#fetch</tt> will take the query you give it, execute it on the database, and yield a hash with column symbol keys for each row returned.  If you want to use some placeholder variables, you can set the placeholders with ? and add the arguments to fetch:
+<tt>Database#fetch</tt> will take the query you give it, execute it on the database, and yield a hash with column symbol keys for each row returned.  If you want to use some placeholder variables, you can set the placeholders with ? and add the corresponding arguments to +fetch+:
 
   DB.fetch("SELECT * FROM albums WHERE name LIKE ?", 'A%') do |row|
     puts row[:name]
@@ -22,13 +22,13 @@ For SELECT queries, you should probably use <tt>Database#fetch</tt> with a strin
 
 You can also use named placeholders by starting the placeholder with a colon, and using a hash for the argument:
 
-  DB.fetch("SELECT * FROM albums WHERE name LIKE :pattern", :pattern=>'A%') do |row|
+  DB.fetch("SELECT * FROM albums WHERE name LIKE :pattern", pattern: 'A%') do |row|
     puts row[:name]
   end
 
-This can be helpful for long queries where it is difficult to match the ? with the arguments.
+This can be helpful for long queries where it is difficult to match the question marks in the query with the arguments.
 
-What Sequel actually does internally is two separate things.  It first creates a dataset representing the query, and then it executes the dataset's SQL code to retrieve the objects.  Often, you want to define a dataset at some point, but not execute it till later.  You can do this by leaving off the block, and storing the dataset in a variable:
+What Sequel actually does internally is two separate things.  It first creates a dataset representing the query, and then it executes the dataset's SQL code to retrieve the objects.  Often, you want to define a dataset at some point, but not execute it until later.  You can do this by leaving off the block, and storing the dataset in a variable:
 
   ds = DB.fetch("SELECT * FROM albums")
 
@@ -41,7 +41,7 @@ You should note that <tt>Database#[]</tt> calls <tt>Database#fetch</tt> if a str
   ds = DB["SELECT * FROM albums"]
   ds.each{|r| puts r[:name]}
 
-However, note that <tt>Database#[]</tt> cannot take a block directly, you have to call +each+ on the returned dataset.  There are plenty of other methods besides +each+, one is +all+ which returns all records as an array:
+However, note that <tt>Database#[]</tt> cannot take a block directly, you have to call +each+ on the returned dataset.  There are plenty of other methods besides +each+. For example, the +all+ method returns all records in the dataset as an array:
 
   DB["SELECT * FROM albums"].all # [{:id=>1, :name=>'RF', ...}, ...]
 
@@ -78,7 +78,7 @@ Almost everywhere in Sequel, you can drop down to literal SQL by providing a lit
   DB[:albums].select('name') # 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}[rdoc-ref:doc/core_extensions.rdoc], which adds the <tt>String#lit</tt> method, and other methods that integrate Sequel's DSL with the ruby language:
+For a simpler way of creating literal strings, you can also use the {core_extensions extension}[rdoc-ref:doc/core_extensions.rdoc], 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)
 
@@ -113,7 +113,7 @@ Now that you know how to see what SQL is being used, let's jump in and see how t
 
 === Identifiers
 
-In Sequel, SQL identifiers are usually specified as ruby symbols:
+In Sequel, SQL identifiers are usually specified as Ruby symbols:
 
   :column # "column"
 
@@ -121,30 +121,33 @@ As you can see, Sequel quotes identifiers by default.  Depending on your databas
 
   :column # "COLUMN" on some databases
 
-A plain symbol is usually treated as an unqualified identifier.  However, if you are using multiple tables in a query, and you want to reference a column in one of the tables that has the same name as a column in another one of the tables, you need to qualify that reference.  There's two main ways in Sequel to do that.  The first is implicit qualification inside the symbol, using the double underscore:
-
-  :table__column # "table"."column"
-
-Note that you can't use a period to separate them:
+A plain symbol is usually treated as an unqualified identifier.  However, if you are using multiple tables in a query, and you want to reference a column in one of the tables that has the same name as a column in another one of the tables, you need to qualify that reference.  Note that you can't use a period to separate them: 
 
   :table.column # calls the column method on the symbol
 
 Also note that specifying the period inside the symbol doesn't work if you are quoting identifiers:
 
-  :"table.column" # "table.column"
+  :"table.column" # "table.column" instead of "table"."column"
 
-The other way to qualify an identifier is to use the <tt>Sequel.qualify</tt> with the table and column symbols:
+There are a few different Sequel methods for creating qualified identifier objects.  The recommended way is to explicitly create a qualified identifier by using <tt>Sequel.[]</tt> to create an identifier and call <tt>[]</tt> or +qualify+ on that, or by using the <tt>Sequel.qualify</tt> method with the table and column symbols:
 
+  Sequel[:table][:column]         # "table"."column"
+  Sequel[:column].qualify(:table) # "table"."column"
   Sequel.qualify(:table, :column) # "table"."column"
 
 Another way to generate identifiers is to use Sequel's {virtual row support}[rdoc-ref:doc/virtual_rows.rdoc]:
 
   DB[:albums].select{name} # SELECT "name" FROM "albums"
-  DB[:albums].select{albums__name} # SELECT "albums"."name" FROM "albums"
+  DB[:albums].select{albums[:name]} # SELECT "albums"."name" FROM "albums"
+
+You can also use the symbol_aref extension for creating qualified identifiers:
+
+  Sequel.extension :symbol_aref
+  :table[:column] # "table"."column"
 
 === Numbers
 
-In general, ruby numbers map directly to SQL numbers:
+In general, Ruby numbers map directly to SQL numbers:
 
   # Integers
   1 # 1
@@ -158,25 +161,24 @@ In general, ruby numbers map directly to SQL numbers:
 
 === Strings
 
-In general, ruby strings map directly to SQL strings:
+In general, Ruby strings map directly to SQL strings:
 
   'name' # 'name'
   "name" # 'name'
 
 === Aliasing
 
-Sequel allows for implicit aliasing in column symbols using the triple underscore:
-
-  :column___alias # "column" AS "alias"
-
-You can combine this with implicit qualification:
+You can use the <tt>Sequel.as</tt> method to create an alias, and the +as+ method on most Sequel-specific expression objects:
 
-  :table__column___alias # "table"."column" AS "alias"
+  Sequel.as(:column, :alias)                 # "column" AS "alias"
+  Sequel[:column].as(:alias)                 # "column" AS "alias"
+  Sequel[:table][:column].as(:alias)         # "table"."column" AS "alias"
+  (Sequel[:column] + 1).as(:alias)           # ("column" + 1) AS "alias"
 
-You can also use the <tt>Sequel.as</tt> method to create an alias, and the +as+ method on most Sequel-specific expression objects:
+You can also use the symbol_as extension for creating aliased identifiers:
 
-  Sequel.as(:column, :alias) # "column" AS "alias"
-  Sequel.qualify(:table, :column).as(:alias) # "table"."column" AS "alias"
+  Sequel.extension :symbol_as
+  :column.as(:alias) # "column" AS "alias"
 
 If you want to use a derived column list, you can provide an array of column aliases:
 
@@ -200,11 +202,11 @@ Aggregate functions work the same way as normal functions, since they share the
 
   Sequel.function(:sum, :column) # sum(column)
 
-To use the DISTINCT modifier to an aggregate function, call the distinct method on the function:
+To use the DISTINCT modifier to an aggregate function, call the +distinct+ method on the function expression, which returns a new function expression:
 
   DB[:albums].select{sum(:column).distinct} # SELECT sum(DISTINCT column) FROM albums
 
-If you want to use the wildcard as the sole argument of the aggregate function, use the * method on the Function:
+If you want to use the wildcard as the sole argument of the aggregate function, use the * method on the function expression:
 
   Sequel.function(:count).* # count(*)
   DB[:albums].select{count.function.*} # SELECT count(*) FROM albums
@@ -213,10 +215,10 @@ Note that Sequel provides helper methods for aggregate functions such as +count+
 
 === Window Functions
 
-If the database supports window functions, Sequel can handle them by calling the over method on a Function:
+If the database supports window functions, Sequel can handle them by calling the +over+ method on a function expression:
 
-  DB[:albums].select{function.function.over}
-  # SELECT function() OVER () FROM albums
+  DB[:albums].select{row_number.function.over}
+  # SELECT row_number() OVER () FROM albums
 
   DB[:albums].select{count.function.*.over}
   # SELECT count(*) OVER () FROM albums
@@ -224,17 +226,29 @@ If the database supports window functions, Sequel can handle them by calling the
   DB[:albums].select{function(:col1).over(:partition=>col2, :order=>col3)}
   # SELECT function(col1) OVER (PARTITION BY col2 ORDER BY col3) FROM albums
 
-  DB[:albums].select{function(c1, c2).over(:partition=>[c3, c4], :order=>[c5, c6])}
-  # SELECT function(c1, c2) OVER (PARTITION BY c3, c4 ORDER BY c5, c6) FROM albums
+  DB[:albums].select{function(c1, c2).over(:partition=>[c3, c4], :order=>[c5, c6.desc])}
+  # SELECT function(c1, c2) OVER (PARTITION BY c3, c4 ORDER BY c5, c6 DESC) FROM albums
+
+  DB[:albums].select{function(c1).over(:partition=>c2, :order=>:c3, :frame=>:rows)}
+  # SELECT function(c1) OVER (PARTITION BY c2 ORDER BY c3 ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) FROM albums
+
+  DB[:albums].select{function(c1).over(:partition=>c2, :order=>:c3, :frame=>{:type=>:range, :start=>1, :end=>1})}
+  # SELECT function(c1) OVER (PARTITION BY c2 ORDER BY c3 RANGE BETWEEN 1 PRECEDING AND 1 FOLLOWING) FROM albums
+
+  DB[:albums].select{function(c1).over(:partition=>c2, :order=>:c3, :frame=>{:type=>:groups, :start=>[2, :preceding], :end=>[1, :preceding]})}
+  # SELECT function(c1) OVER (PARTITION BY c2 ORDER BY c3 GROUPS BETWEEN 2 PRECEDING AND 1 PRECEDING) FROM albums
+
+  DB[:albums].select{function(c1).over(:partition=>c2, :order=>:c3, :frame=>{:type=>:range, :start=>:preceding, :exclude=>:current})}
+  # SELECT function(c1) OVER (PARTITION BY c2 ORDER BY c3 RANGE UNBOUNDED PRECEDING EXCLUDE CURRENT ROW) FROM albums
 
 === Schema Qualified Functions
 
-If the database supports schema qualified functions, Sequel can handle them by calling the function method on a QuailfiedIdentifier:
+If the database supports schema qualified functions, Sequel can handle them by calling the +function+ method on a qualified identifier:
 
-  DB[:albums].select{schema__function.function}
+  DB[:albums].select{schema[:function].function}
   # SELECT schema.function() FROM albums
   
-  DB[:albums].select{schema__function.function(col, 2, "a")}
+  DB[:albums].select{schema[:function].function(:col, 2, "a")}
   # SELECT schema.function(col, 2, 'a') FROM albums
 
 === Portable/Emulated Functions
@@ -250,7 +264,7 @@ Some examples are:
 
 Sequel uses hashes to specify equality:
 
-  {:column=>1} # ("column" = 1)
+  {column: 1} # ("column" = 1)
 
 You can also specify this as an array of two element arrays:
 
@@ -264,27 +278,27 @@ For expression objects, you can also use the =~ method:
 
 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.negate([[:column, 1]]) # ("column" != 1)
-  Sequel.~(:column => 1)        # ("column" != 1)
+  Sequel.~(column: 1)           # ("column" != 1)
   Sequel.~([[: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 hash or array, while ~ does a general inversion.  This is best shown by an example with multiple entries:
+The difference between the two is that +negate+ only works on hashes and arrays of element arrays, and it negates all entries in the hash or array, 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))
+  Sequel.negate(column: 1, foo: 2)   # (("column" != 1) AND (foo != 2))
+  Sequel.~(column: 1, foo: 2)        # (("column" != 1) OR (foo != 2))
 
 You can also use the ~ method on an equality expression:
 
   where{~(column =~ 1)} # ("column" != 1)
 
-On Ruby 1.9+, you can use the !~ method:
+Or you can use the !~ method:
 
   where{column !~ 1} # ("column" != 1)
 
 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)
+  DB[:albums].exclude(column: 1) # SELECT * FROM "albums" WHERE ("column" != 1)
 
 Note that +exclude+ does a generalized inversion, similar to <tt>Sequel.~</tt>.
 
@@ -292,19 +306,19 @@ Note that +exclude+ does a generalized inversion, similar to <tt>Sequel.~</tt>.
 
 Sequel also uses hashes to specify inclusion, and inversions of those hashes to specify exclusion:
 
-  {:column=>[1, 2, 3]} # ("column" IN (1, 2, 3))
-  Sequel.~(:column=>[1, 2, 3]) # ("column" NOT IN (1, 2, 3))
+  {column: [1, 2, 3]} # ("column" 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"))
-  Sequel.~(:column=>DB[:albums].select(:id)) # ("column" NOT IN (SELECT "id" FROM "albums"))
+  {column: DB[:albums].select(:id)} # ("column" IN (SELECT "id" FROM "albums"))
+  Sequel.~(column: DB[:albums].select(:id)) # ("column" NOT IN (SELECT "id" FROM "albums"))
 
 Similar to =, you can also use =~ with expressions for inclusion:
 
   where{column =~ [1, 2, 3]} # ("column" IN (1, 2, 3))
 
-and on Ruby 1.9, !~ for exclusion:
+and !~ for exclusion:
 
   where{column !~ [1, 2, 3]} # ("column" NOT IN (1, 2, 3))
 
@@ -314,19 +328,19 @@ Sequel also supports the SQL EXISTS operator using <tt>Dataset#exists</tt>:
 
 === Identity Operators (IS, IS NOT)
 
-Hashes in Sequel use IS if the value is true, false, or nil:
+Hashes in Sequel use IS if the value is +true+, +false+, or +nil+:
 
-  {:column=>nil} # ("column" IS NULL)
-  {:column=>true} # ("column" IS TRUE)
-  {:column=>false} # ("column" IS FALSE)
+  {column: nil}   # ("column" IS NULL)
+  {column: true}  # ("column" IS TRUE)
+  {column: false} # ("column" IS FALSE)
 
 Negation works the same way as it does for equality and inclusion:
 
-  Sequel.~(:column=>nil) # ("column" IS NOT NULL)
-  Sequel.~(:column=>true) # ("column" IS NOT TRUE)
-  Sequel.~(:column=>false) # ("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)
 
-Likewise, =~ works for identity (and Ruby 1.9, !~ for negative identity):
+Likewise, =~ works for identity and !~ for negative identity on expressions:
 
   where{column =~ nil} # ("column" IS NULL)
   where{column !~ nil} # ("column" IS NOT NULL)
@@ -339,7 +353,7 @@ Sequel's general inversion operator is ~, which works on symbols and most Sequel
 
 Note that ~ will actually apply the inversion operation to the underlying object, which is why
   
-  Sequel.~(:column=>1)
+  Sequel.~(column: 1)
 
 produces <tt>(column != 1)</tt> instead of <tt>NOT (column = 1)</tt>.
 
@@ -347,14 +361,14 @@ produces <tt>(column != 1)</tt> instead of <tt>NOT (column = 1)</tt>.
 
 Sequel defines the inequality operators directly on most Sequel-specific expression objects:
 
-  Sequel.qualify(:table, :column) > 1 # ("table"."column" > 1)
-  Sequel.qualify(:table, :column) < 1 # ("table"."column" < 1)
+  Sequel[:table][:column] > 1 # ("table"."column" > 1)
+  Sequel[: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 <tt>Sequel.expr</tt> with the symbol:
+If you want to use them on a symbol, you should call <tt>Sequel.[]</tt> with the symbol to get an expression object:
 
-  Sequel.expr(:column) > 1 # ("column" > 1)
+  Sequel[:column] > 1 # ("column" > 1)
 
 A common use of virtual rows is to handle inequality operators:
 
@@ -364,33 +378,31 @@ A common use of virtual rows is to handle inequality operators:
 
 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
+  Sequel[:column] + 1 # "column" + 1
+  Sequel[:table][:column] - 1 # "table"."column" - 1
+  Sequel[:table][:column] * 1 # "table"."column" * 1
+  Sequel[:column] / 1 # "column" / 1
+  Sequel[:column] ** 1 # power("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.-(Sequel[:table][:column], 1) # "table"."column" - 1
+  Sequel.*(Sequel[:table][:column], 1) # "table"."column" * 1
   Sequel./(:column, 1) # "column" / 1
+  Sequel.**(:column, 1) # power("column", 1)
 
-Note that the following does not work:
-
-  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.  The solution is to use one of the methods on the Sequel module:
+Note that since Sequel implements support for Ruby's coercion protocol, the following also works:
 
-  Sequel.expr(1) / :column # (1 / "column")
-  Sequel./(1, :column) # (1 / "column")
+  1 + Sequel[:column]
+  1 - Sequel[:table][:column]
 
 === Boolean Operators (AND OR)
 
 Sequel defines the & and | methods on most Sequel-specific expression objects to handle AND and OR:
 
-  Sequel.expr(:column1) & :column2 # ("column1" AND "column2")
-  Sequel.expr(:column1=>1) | {:column2=>2} # (("column1" = 1) OR ("column2" = 2))
+  Sequel[:column1] & :column2 # ("column1" AND "column2")
+  Sequel[{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.
@@ -402,39 +414,39 @@ is parsed as:
 
   Sequel.function(:func) > (1 & :column3)
 
-You and also use the <tt>Sequel.&</tt> and <tt>Sequel.|</tt> methods:
+You can 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))
+  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))
   [[:column1, 1], [:column2, 2]] # (("column1" = 1) AND ("column2" = 2))
 
 As you can see, these literalize with ANDs by default.  You can use the <tt>Sequel.or</tt> method to use OR instead:
 
-  Sequel.or(:column1=>1, :column2=>2) # (("column1" = 1) OR ("column2" = 2))
+  Sequel.or(column1: 1, column2: 2) # (("column1" = 1) OR ("column2" = 2))
 
 You've already seen the <tt>Sequel.negate</tt> method, which will use ANDs if multiple entries are used:
 
-  Sequel.negate(:column1=>1, :column2=>2) # (("column1" != 1) AND ("column2" != 2))
+  Sequel.negate(column1: 1, column2: 2) # (("column1" != 1) AND ("column2" != 2))
  
 To negate while using ORs, the <tt>Sequel.~</tt> operator can be used:
 
-  Sequel.~(:column1=>1, :column2=>2) # (("column1" != 1) OR ("column2" != 2))
+  Sequel.~(column1: 1, column2: 2) # (("column1" != 1) OR ("column2" != 2))
 
 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))
+  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 most of the Sequel-specific expression objects:
 
-  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)
+  Sequel[:name].cast(:text) # CAST("name" AS text)
+  Sequel['1'].cast(:integer) # CAST('1' AS integer)
+  Sequel[:table][:column].cast(:date) # CAST("table"."column" AS date)
 
 You can also use the <tt>Sequel.cast</tt> method:
 
@@ -444,72 +456,72 @@ You can also use the <tt>Sequel.cast</tt> method:
 
 Sequel allows the use of bitwise mathematical operators on Sequel::SQL::NumericExpression objects:
 
-  Sequel.expr(:number) + 1 # => #<Sequel::SQL::NumericExpression ...>
-  (Sequel.expr(:number) + 1) & 5 # (("number" + 1) & 5)
+  Sequel[:number] + 1 # => #<Sequel::SQL::NumericExpression ...>
+  (Sequel[:number] + 1) & 5 # (("number" + 1) & 5)
 
 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+:
 
-  Sequel.expr(:number).sql_number | 5 # ("number" | 5)
+  Sequel[: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+:
 
-  Sequel.expr(:name).cast_numeric ^ 9 # (CAST("name" AS integer) ^ 9)
+  Sequel[:name].cast_numeric ^ 9 # (CAST("name" AS integer) ^ 9)
 
 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:
 
-  ~Sequel.expr(:name) # NOT "name"
-  ~Sequel.expr(:name).sql_number # ~"name"
+  ~Sequel[:name] # NOT "name"
+  ~Sequel[: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 on an expression:
 
-  Sequel.expr(:name).sql_string + ' - Name' # ("name" || ' - Name')
+  Sequel[: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+:
+Just like for the bitwise operators, Sequel allows you to do the cast and conversion at the same time via +cast_string+:
 
-  Sequel.expr(:number).cast_string + ' - Number' # (CAST(number AS varchar(255)) || ' - Number')
+  Sequel[: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 - ' + Sequel.expr(:name).sql_string # raises TypeError
+  'Name - ' + Sequel[:name].sql_string # raises TypeError
 
-Just like for the mathematical operators, you can use <tt>Sequel.expr</tt> to wrap the object:
+Just like for the mathematical operators, you can use <tt>Sequel.[]</tt> to wrap the object:
 
-  Sequel.expr('Name - ') + :name # ('Name - ' || "name")
+  Sequel['Name - '] + :name # ('Name - ' || "name")
   
 The <tt>Sequel.join</tt> method concatenates all of the elements in the array:
 
   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:
+Just like Ruby's <tt>String#join</tt>, you can provide an argument for a string used to join each element:
 
   Sequel.join(['Name', :name], ' - ') # ('Name' || ' - ' || "name")
 
 For the LIKE operator, Sequel defines the +like+ and +ilike+ methods on most Sequel-specific expression objects:
 
-  Sequel.expr(:name).like('A%') # ("name" LIKE 'A%' ESCAPE '\') 
-  Sequel.expr(:name).ilike('A%') # ("name" ILIKE 'A%' ESCAPE '\') 
+  Sequel[:name].like('A%') # ("name" LIKE 'A%' ESCAPE '\') 
+  Sequel[:name].ilike('A%') # ("name" ILIKE 'A%' ESCAPE '\') 
 
 You can also use the <tt>Sequel.like</tt> and <tt>Sequel.ilike</tt> methods:
 
   Sequel.like(:name, 'A%') # ("name" LIKE 'A%' ESCAPE '\') 
   Sequel.ilike(:name, 'A%') # ("name" ILIKE 'A%' ESCAPE '\') 
 
-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.
+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:
 
   ~Sequel.like(:name, 'A%') # ("name" NOT LIKE 'A%' ESCAPE '\')
 
-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:
+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:
 
   Sequel.like(:name, /^A/) # ("name" ~ '^A')
   ~Sequel.ilike(:name, /^A/) # ("name" !~* '^A')
-  {:name=>/^A/i} # ("name" ~* '^A')
-  Sequel.~(:name=>/^A/) # ("name" !~ '^A')
+  {name: /^A/i} # ("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.
 
@@ -517,36 +529,37 @@ Note that using +ilike+ with a regular expression will always make the regexp ca
 
 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
+  Sequel[:column].asc # "column" ASC
+  Sequel[:table][:column].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
+  Sequel.desc(Sequel[:table][:column]) # "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
+  Sequel.desc(Sequel[:table][:column], :nulls=>:last) # "table"."column" DESC NULLS LAST
 
 === All Columns (.*)
 
-To select all columns in a table, Sequel supports the * method on identifiers without an argument:
+To select all columns in a table, Sequel supports the * method on identifiers and qualified without an argument:
 
-  Sequel.expr(:table).* # "table".*
+  Sequel[:table].*          # "table".*
+  Sequel[:schema][:table].* # "schema"."table".*
 
 === CASE statements
 
-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:
+Sequel supports 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:
 
-  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)
+  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:
 
-  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)
   Sequel.case([[:c, 1], [:d, 2]], 0) # (CASE WHEN "c" THEN 1 WHEN "d" THEN 2 ELSE 0 END)
 
 If you provide a 3rd argument to <tt>Sequel.case</tt>, it goes between CASE and WHEN:
@@ -557,8 +570,8 @@ If you provide a 3rd argument to <tt>Sequel.case</tt>, it goes between CASE and
 
 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]
+  Sequel[:column].sql_subscript(3) # column[3]
+  Sequel[:table][:column].sql_subscript(3) # table.column[3]
 
 You can also use the <tt>Sequel.subscript</tt> method:
 
@@ -574,7 +587,7 @@ In Sequel, the SQL queries are build with method chaining.
 
 === Creating Datasets
 
-You generally start by creating a dataset by calling <tt>Dataset#[]</tt> with a symbol specifying the table name:
+You generally start creating a dataset by calling <tt>Dataset#[]</tt> with a symbol specifying the table name:
 
   DB[:albums] # SELECT * FROM albums
 
@@ -582,7 +595,7 @@ If you want to select from multiple FROM tables, use multiple arguments:
 
   DB[:albums, :artists] # SELECT * FROM albums, artists
 
-If you don't want to select from any FROM tables, just call dataset:
+If you don't want to select from any FROM tables, just call +dataset+:
 
   DB.dataset # SELECT *
 
@@ -616,7 +629,7 @@ In general, the +insert+, +update+, and +delete+ methods use the appropriate cla
   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 +where+ argument, but that +insert+ did not, because INSERT doesn't use a WHERE clause.
+Note how +update+ and +delete+ used the +where+ argument, but +insert+ did not, because INSERT doesn't use a WHERE clause.
 
 === Methods Used for Each SQL Clause