sequel 4.26.0 → 5.37.0

data/doc/bin_sequel.rdoc

@@ -10,9 +10,7 @@ This is very useful for quick testing of ideas, and does not affect the environm
 
 If you've installed the sequel gem, then just running "sequel" should load the program, since rubygems should place the sequel binary in your load path.  However, if you want to run bin/sequel from the root of a repository checkout, you should probably do:
 
-  ruby -I lib bin/sequel
-
-The -I lib makes sure that you are using the repository checkout's code.
+  ruby bin/sequel
 
 == Choosing the Database to Connect to
 
@@ -91,6 +89,8 @@ To save this information to a file, use a standard shell redirection:
 
 The -d option dumps the migration in database-independent format, the -D option dumps it in database-specific format.
 
+Note that the support for dumping schema is fairly limited.  It doesn't handle database views, functions, triggers, schemas, partial indexes, functional indexes, and many other things.  You should probably use the database specific tools to handle those.
+
 The -S option dumps the schema cache for all tables in the database, which can speed up the usage of Sequel with models when using the schema_caching extension.  You should provide this option with the path to which to dump the schema:
 
   sequel -S /path/to/schema_cache.db postgres://host/database
@@ -103,6 +103,8 @@ Using the -C option, Sequel can copy the contents of one database to another, ev
 
 This copies the table structure, table data, indexes, and foreign keys from the MySQL database to the PostgreSQL database.
 
+Note that the support for copying is fairly limited.  It doesn't handle database views, functions, triggers, schemas, partial indexes, functional indexes, and many other things. Also, the data type conversion may not be exactly what you want.  It is best designed for quick conversions and testing.  For serious production use, use the database's tools to copy databases for the same database type, and for different database types, use the Sequel API.
+
 == Other Options
 
 Other options not mentioned above are explained briefly here.

data/doc/cheat_sheet.rdoc

@@ -6,7 +6,7 @@
 
   DB = Sequel.sqlite('my_blog.db')
   DB = Sequel.connect('postgres://user:password@localhost/my_db')
-  DB = Sequel.postgres('my_db', :user => 'user', :password => 'password', :host => 'localhost')
+  DB = Sequel.postgres('my_db', user: 'user', password: 'password', host: 'localhost')
   DB = Sequel.ado('mydb')
 
 == Open an SQLite memory database
@@ -18,7 +18,7 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 == Logging SQL statements
 
   require 'logger'
-  DB = Sequel.sqlite '', :loggers => [Logger.new($stdout)]
+  DB = Sequel.sqlite(loggers: [Logger.new($stdout)])
   # or
   DB.loggers << Logger.new($stdout)
 
@@ -38,22 +38,24 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 == Most dataset methods are chainable
 
-  dataset = DB[:managers].where(:salary => 5000..10000).order(:name, :department)
+  dataset = DB[:managers].where(salary: 5000..10000).order(:name, :department)
 
 == Insert rows
 
-  dataset.insert(:name => 'Sharon', :grade => 50)
+  dataset.insert(name: 'Sharon', grade: 50)
 
 == Retrieve rows
 
   dataset.each{|r| p r}
   dataset.all # => [{...}, {...}, ...]
   dataset.first # => {...}
+  dataset.last # => {...}
 
 == Update/Delete rows
 
   dataset.exclude(:active).delete
-  dataset.where('price < ?', 100).update(:active => true)
+  dataset.where{price < 100}.update(:active => true)
+  dataset.where(:active).update(:price => Sequel[:price] * 0.90)
 
 == Datasets are Enumerable
 
@@ -67,8 +69,7 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 === Equality
 
-  dataset.where(:name => 'abc')
-  dataset.where('name = ?', 'abc')
+  dataset.where(name: 'abc')
 
 === Inequality
 
@@ -77,30 +78,27 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 === Inclusion
 
-  dataset.where(:value => 50..100)
+  dataset.where(value: 50..100)
   dataset.where{(value >= 50) & (value <= 100)}
 
-  dataset.where('value IN ?', [50,75,100])
-  dataset.where(:value=>[50,75,100])
-
-  dataset.where(:id=>other_dataset.select(:other_id))
+  dataset.where(value: [50,75,100])
+  dataset.where(id: other_dataset.select(:other_id))
 
 === Subselects as scalar values
 
-  dataset.where('price > (SELECT avg(price) + 100 FROM table)')
   dataset.where{price > dataset.select(avg(price) + 100)}
 
 === LIKE/Regexp
 
   DB[:items].where(Sequel.like(:name, 'AL%'))
-  DB[:items].where(:name => /^AL/)
+  DB[:items].where(name: /^AL/)
 
 === AND/OR/NOT
 
   DB[:items].where{(x > 5) & (y > 10)}.sql 
   # SELECT * FROM items WHERE ((x > 5) AND (y > 10))
 
-  DB[:items].where(Sequel.or(:x => 1, :y => 2) & Sequel.~(:z => 3)).sql 
+  DB[:items].where(Sequel.or(x: 1, y: 2) & Sequel.~(z: 3)).sql 
   # SELECT * FROM items WHERE (((x = 1) OR (y = 2)) AND (z != 3))
 
 === Mathematical operators
@@ -111,11 +109,18 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
   DB[:items].where{price - 100 < avg(price)}.sql 
   # SELECT * FROM items WHERE ((price - 100) < avg(price))
 
+=== Raw SQL Fragments
+
+  dataset.where(Sequel.lit('id= 1'))
+  dataset.where(Sequel.lit('name = ?', 'abc'))
+  dataset.where(Sequel.lit('value IN ?', [50,75,100]))
+  dataset.where(Sequel.lit('price > (SELECT avg(price) + 100 FROM table)'))
+
 == Ordering
 
-  dataset.order(:kind)
-  dataset.reverse_order(:kind)
-  dataset.order(Sequel.desc(:kind), :name)
+  dataset.order(:kind) # kind
+  dataset.reverse(:kind) # kind DESC
+  dataset.order(Sequel.desc(:kind), :name) # kind DESC, name
 
 == Limit/Offset
 
@@ -125,11 +130,12 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
 
 == Joins
 
-  DB[:items].left_outer_join(:categories, :id => :category_id).sql 
+  DB[:items].left_outer_join(:categories, id: :category_id).sql 
   # SELECT * FROM items
   # LEFT OUTER JOIN categories ON categories.id = items.category_id
 
-  DB[:items].join(:categories, :id => :category_id).join(:groups, :id => :items__group_id) 
+  DB[:items].join(:categories, id: :category_id).
+    join(:groups, id: Sequel[:items][:group_id]) 
   # SELECT * FROM items
   # INNER JOIN categories ON categories.id = items.category_id
   # INNER JOIN groups ON groups.id = items.group_id
@@ -142,79 +148,100 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
   dataset.avg(:price)
   dataset.sum(:stock)
 
-  dataset.group_and_count(:category)
+  dataset.group_and_count(:category).all
   dataset.select_group(:category).select_append{avg(:price)}
 
 == SQL Functions / Literals
 
-  dataset.update(:updated_at => Sequel.function(:NOW))
-  dataset.update(:updated_at => Sequel.lit('NOW()'))
+  dataset.update(updated_at: Sequel.function(:NOW))
+  dataset.update(updated_at: Sequel.lit('NOW()'))
 
-  dataset.update(:updated_at => Sequel.lit("DateValue('1/1/2001')"))
-  dataset.update(:updated_at => Sequel.function(:DateValue, '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
 
   DB.create_table :items do
     primary_key :id
-    String :name, :unique => true, :null => false
-    TrueClass :active, :default => true
+    String :name, unique: true, null: false
+    TrueClass :active, default: true
     foreign_key :category_id, :categories
-    DateTime :created_at
+    DateTime :created_at, default: Sequel::CURRENT_TIMESTAMP, :index=>true
     
-    index :created_at
+    index [:category_id, :active]
   end
 
   DB.drop_table :items
 
 == Aliasing
 
+  DB[:items].select(Sequel[: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)
+  DB[:items].select{name.as(:item_name)}
+  # SELECT name AS item_name FROM items
+
+  DB[Sequel[:items].as(:items_table)].select{items_table[:name].as(:item_name)}
   # SELECT items_table.name AS item_name FROM items AS items_table
 
 == Transactions
 
   DB.transaction do
-    dataset.insert(:first_name => 'Inigo', :last_name => 'Montoya')
-    dataset.insert(:first_name => 'Farm', :last_name => 'Boy')
-  end # Either both are inserted or neither are inserted
+    # BEGIN
+    dataset.insert(first_name: 'Inigo', last_name: 'Montoya')
+    dataset.insert(first_name: 'Farm', last_name: 'Boy')
+  end
+  # COMMIT
+
 
-Database#transaction is re-entrant:
+Transactions are reentrant:
 
-  DB.transaction do # BEGIN issued only here
+  DB.transaction do
+    # BEGIN
     DB.transaction do
-      dataset << {:first_name => 'Inigo', :last_name => 'Montoya'}
+      dataset.insert(first_name: 'Inigo', last_name: 'Montoya')
     end
-  end # COMMIT issued only here
+  end
+  # COMMIT
 
 Transactions are aborted if an error is raised:
 
   DB.transaction do
+    # BEGIN
     raise "some error occurred"
-  end # ROLLBACK issued and the error is re-raised
+  end
+  # ROLLBACK issued and the error is re-raised
 
 Transactions can also be aborted by raising Sequel::Rollback:
 
   DB.transaction do
-    raise(Sequel::Rollback) if something_bad_happened
-  end # ROLLBACK issued and no error raised
+    # BEGIN
+    raise(Sequel::Rollback)
+  end
+  # ROLLBACK issued and no error raised
 
 Savepoints can be used if the database supports it:
 
   DB.transaction do
-    dataset << {:first_name => 'Farm', :last_name => 'Boy'} # Inserted
-    DB.transaction(:savepoint=>true) do # This savepoint is rolled back
-      dataset << {:first_name => 'Inigo', :last_name => 'Montoya'} # Not inserted
-      raise(Sequel::Rollback) if something_bad_happened
+    dataset.insert(first_name: 'Farm', last_name: 'Boy') # Inserted
+    DB.transaction(savepoint: true) do # This savepoint is rolled back
+      dataset.insert(first_name: 'Inigo', last_name: 'Montoya') # Not inserted
+      raise(Sequel::Rollback)
     end
-    dataset << {:first_name => 'Prince', :last_name => 'Humperdink'} # Inserted
+    dataset.insert(first_name: 'Prince', last_name: 'Humperdink') # Inserted
   end
 
-== Miscellaneous:
+== Retrieving SQL
 
   dataset.sql # "SELECT * FROM items"
+  dataset.insert_sql(a: 1) # "INSERT INTO items (a) VALUES (1)"
+  dataset.update_sql(a: 1) # "UPDATE items SET a = 1"
   dataset.delete_sql # "DELETE FROM items"
-  dataset.columns # => array of columns in the result set, does a SELECT
+
+== Basic introspection
+
+  dataset.columns # => [:id, :name, ...]
+  DB.tables # => [:items, ...]
+  DB.views # => [:new_items, ...]
   DB.schema(:items) # => [[:id, {:type=>:integer, ...}], [:name, {:type=>:string, ...}], ...]
+  DB.indexes(:items) # => {:index_name => {:columns=>[:a], :unique=>false}, ...}
+  DB.foreign_key_list(:items) # => [{:name=>:items_a_fk, :columns=>[:a], :key=>[:id], :table=>:other_table}, ...]

data/doc/code_order.rdoc

@@ -1,13 +1,13 @@
 = Code Order
 
-In Sequel, the order in which code is executed is important.  This
+In Sequel, the order in which code is executed during initialization is important.  This
 guide provides the recommended way to order your Sequel code.  Some
 of these guidelines are not strictly necessary, but others are, and
 this guide will be specific about which are strictly necessary.
 
 == Require Sequel
 
-This is sort of a no brainer, but you need to require the library
+This is sort of a no-brainer, but you need to require the library
 first.  This is a strict requirement, none of the other code can
 be executed unless the library has been required first. Example:
 
@@ -18,13 +18,6 @@ be executed unless the library has been required first. Example:
 Global extensions are loaded with Sequel.extension, and affect
 other parts of Sequel or the general ruby environment.  It's not
 necessary to load them first, but it is a recommended practice.
-
-The exception to this is global extensions that integrate with
-Database-specific extensions, where the Database-specific
-extension should be loaded first (such as some of the pg_*
-extensions).  In those cases, the global extensions should be
-loaded after the Database-specific extensions.
-
 Example:
 
   Sequel.extension :blank
@@ -77,12 +70,37 @@ copied into the subclass when model subclasses are created.  Example:
 == Load Model Classes
 
 After you have established a database connection, and configured your
-global model configration and global plugins, you can load your model
+global model configuration and global plugins, you can load your model
 classes.  It's recommended to have a separate file for each model class,
 unless the model classes are very simple.  Example:
 
   Dir['./models/*.rb'].each{|f| require f}
 
+== Finalize Associations and Freeze Model Classes and Database
+
+After all the models have been setup, you can finalize the associations.
+This can speed up association reflection methods by doing a lookup in
+advance to find the associated class, and cache related association
+information in the association itself.
+
+Additionally, in production and testing, you should freeze the
+model classes and Database instance, so that you can detect
+unsafe runtime modification of the configuration:
+
+  model_classes.each(&:finalize_associations)
+  model_classes.each(&:freeze)
+  DB.freeze
+
+The `subclasses` plugin can be used to keep track of all model classes
+that have been setup in your application. Finalizing their associations
+and freezing them can easily be achieved through the plugin:
+
+  # Register the plugin before setting up the models
+  Sequel::Model.plugin :subclasses
+  # ... setup models
+  # Now finalize associations & freeze models by calling the plugin:
+  Sequel::Model.freeze_descendents
+
 == Disconnect If Using Forking Webserver with Code Preloading
 
 If you are using a forking webserver such as unicorn or passenger, with

data/doc/core_extensions.rdoc

@@ -10,12 +10,18 @@ Historically, Sequel added methods to many of the core classes, and usage of tho
 
 While Sequel never overrode 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:
+Alternatives for the core extension methods were 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))
 
+or with virtual rows:
+
+  DB[:table].select{column.as(Integer)}.
+    where{column.like('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
@@ -40,6 +46,16 @@ All of Sequel's extensions to the core classes are stored in Sequel's core_exten
 
 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.
 
+== Refinements
+
+Most of the these extensions can be added on a per-file basis using refinements (if you are using Ruby 2.0+).  To use refinements, first load them:
+
+  Sequel.extension :core_refinements
+
+Then for each file where you want to use the refinements:
+
+  using Sequel::CoreRefinements
+
 == 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.
@@ -53,8 +69,9 @@ Symbol#as and String#as return Sequel aliased expressions using the provided ali
   :a.as(:b)  # SQL: a AS b
   'a'.as(:b) # SQL: 'a' AS b
 
-Alternative: Sequel.as:
+Alternatives:
 
+  Sequel[:a].as(:b)
   Sequel.as(:a, :b)
 
 ==== cast
@@ -64,8 +81,9 @@ Symbol#cast and String#cast return Sequel cast expressions for typecasting in th
   :a.cast(Integer)  # SQL: CAST(a AS integer)
   'a'.cast(Integer) # SQL: CAST('a' AS integer)
 
-Alternative: Sequel.cast:
+Alternatives:
 
+  Sequel[:a].cast(Integer)
   Sequel.cast(:a, Integer)
 
 ==== cast_numeric
@@ -75,8 +93,9 @@ Symbol#cast_numeric and String#cast_numeric return Sequel cast expressions for t
   :a.cast_numeric         # SQL: CAST(a AS integer)
   'a'.cast_numeric(Float) # SQL: CAST('a' AS double precision)
 
-Alternative: Sequel.cast_numeric:
+Alternative:
 
+  Sequel[:a].cast_numeric
   Sequel.cast_numeric(:a)
 
 ==== cast_string
@@ -86,21 +105,23 @@ Symbol#cast_string and String#cast_string return Sequel cast expressions for typ
   :a.cast_string         # SQL: CAST(a AS varchar(255))
   'a'.cast_string(:text) # SQL: CAST('a' AS text)
 
-Alternative: Sequel.cast_string:
+Alternatives:
 
+  Sequel[:a].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.
+Symbol#identifier wraps the symbol in an Sequel identifier object.  If symbol splitting is enabled (no longer the default), it also makes sure the symbol will not be split.  If symbol splitting is disabled (the default), there is little reason to use this).
 
-  :table__column.identifier # SQL: table__column
+  :column.identifier # SQL: column
 
-Alternative: Sequel.identifier:
+Alternatives:
 
-  Sequel.identifier(:table__column)
+  Sequel[:column]
+  Sequel.identifier(:column)
 
 ==== asc
 
@@ -108,8 +129,9 @@ Symbol#asc is used to define an ascending order on a column.  It exists mostly f
 
   :a.asc # SQL: a ASC
 
-Alternative: Sequel.asc:
+Alternatives:
 
+  Sequel[:a].asc
   Sequel.asc(:a)
 
 ==== desc
@@ -118,8 +140,9 @@ Symbol#desc is used to defined a descending order on a column.  The returned val
 
   :a.desc # SQL: a DESC
 
-Alternative: Sequel.desc:
+Alternatives:
 
+  Sequel[:a].desc
   Sequel.desc(:a)
 
 ==== +, -, *, /
@@ -130,13 +153,25 @@ The standard mathematical operators are defined on Symbol, and return a Sequel n
     :a - :b # SQL: a - b
     :a * :b # SQL: a * b
     :a / :b # SQL: a / b 
+    :a ** :b # SQL: power(a, b)
+
+Sequel also supports ruby's coercion protocols on symbols (note that this does not work when using refinements):
+
+    1 + :b # SQL: 1 + b
 
 Alternatives:
 
+    Sequel[:a] + :b
+    Sequel[:a] - :b
+    Sequel[:a] * :b
+    Sequel[:a] / :b
+    Sequel[:a] ** :b
+
     Sequel.+(:a, :b)
     Sequel.-(:a, :b)
     Sequel.*(:a, :b)
     Sequel./(:a, :b)
+    Sequel.**(:a, :b)
 
 ==== *
 
@@ -144,9 +179,9 @@ The * operator is overloaded on Symbol such that if it is called with no argumen
 
   :a.* # SQL: a.*
 
-Alternative: Sequel.expr.*:
+Alternative:
 
-  Sequel.expr(:a).*
+  Sequel[:a].*
 
 ==== qualify
 
@@ -154,11 +189,11 @@ Symbol#qualify qualifies the identifier (e.g. a column) with a another identifie
 
   :column.qualify(:table) # SQL: table.column
 
-Alternative: Sequel.qualify:
+Alternative:
 
-  Sequel.qualify(:table, :column)
+  Sequel[: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.
+Note the reversed order of the arguments.  For the Symbol#qualify method, the argument is the qualifier, while for Sequel[][], the first [] is the qualifier, and the second [] is the identifier.
 
 ==== like
 
@@ -166,8 +201,9 @@ Symbol#like returns a case sensitive LIKE expression between the identifier and
 
   :a.like('b%') # SQL: a LIKE 'b%' ESCAPE '\'
 
-Alternative: Sequel.like:
+Alternatives:
 
+  Sequel[:a].like('b%')
   Sequel.like(:a, 'b%')
 
 ==== ilike
@@ -176,8 +212,9 @@ Symbol#ilike returns a case insensitive LIKE expression between the identifier a
 
   :a.ilike('b%') # SQL: a ILIKE 'b%' ESCAPE '\'
 
-Alternative: Sequel.ilike:
+Alternatives:
 
+  Sequel[:a].ilike('b%')
   Sequel.ilike(:a, 'b%')
 
 ==== sql_subscript
@@ -186,8 +223,9 @@ Symbol#sql_subscript returns a Sequel expression representing an SQL array acces
 
   :a.sql_subscript(1) # SQL: a[1]
 
-Alternative: Sequel.subscript:
+Alternatives:
 
+  Sequel[:a].sql_subscript(1)
   Sequel.subscript(:a, 1)
 
 ==== extract
@@ -196,12 +234,11 @@ Symbol#extract does a datetime part extraction from the receiver:
 
   :a.extract(:year) # SQL: extract(year FROM a)
 
-Alternative: Sequel.extract:
+Alternatives:
 
+  Sequel[:a].extract(:year)
   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:
@@ -210,11 +247,11 @@ These Symbol methods are used to force the treating of the object as a specific
   :a.sql_number << 1  # SQL: a << 1
   :a.sql_string + 'a' # SQL: a || 'a'
 
-Alternative: Sequel.expr:
+Alternatives:
 
-  Sequel.expr(:a).sql_boolean
-  Sequel.expr(:a).sql_number
-  Sequel.expr(:a).sql_string
+  Sequel[:a].sql_boolean
+  Sequel[:a].sql_number
+  Sequel[:a].sql_string
 
 ==== sql_function
 
@@ -224,8 +261,9 @@ Symbol#sql_function returns an SQL function call expression object:
   :sum.sql_function(:a) # SQL: sum(a)
   :concat.sql_function(:a, :b) # SQL: concat(a, b)
 
-Alternative: Sequel.function:
+Alternatives:
 
+  Sequel[:sum].function(:a)
   Sequel.function(:sum, :a)
 
 === String
@@ -237,9 +275,10 @@ String#lit creates a literal string, using placeholders if any arguments are giv
   'a'.lit          # SQL: a
   '"a" = ?'.lit(1) # SQL: "a" = 1
 
-Alternative: Sequel.lit:
+Alternatives:
 
   Sequel.lit('a')
+  Sequel.lit('a = ?', 1)
 
 ==== to_sequel_blob
 
@@ -247,7 +286,7 @@ String#to_sequel_blob returns the string wrapper in Sequel blob object.  Often b
 
   "a\0".to_sequel_blob # SQL: X'6100'
 
-Alternative: Sequel.blob:
+Alternative:
 
   Sequel.blob("a\0")
 
@@ -257,12 +296,13 @@ Alternative: Sequel.blob:
 
 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: [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.~:
+Alternatives:
 
-   Sequel.~(:a=>1, :b=>[2, 3])
+   ~Sequel[a: 1, b: [2, 3]]
+   Sequel.~(a: 1, b: [2, 3])
 
 === Hash & Array
 
@@ -270,45 +310,45 @@ Alternative: Sequel.~:
 
 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
+  {{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:
+Alternative:
 
-  Sequel.case({{:a=>[2,3]}=>1}, 0)
+  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)
   [[:a, 1], [:b, [2, 3]]].sql_expr # SQL: a = 1 AND b IN (2, 3)
 
-Alternative: Sequel.expr:
+Alternative:
 
-  Sequel.expr(:a=>1, :b=>[2, 3])
+  Sequel[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)
   [[:a, 1], [:b, [2, 3]]].sql_negate # SQL: a != 1 AND b NOT IN (2, 3)
 
-Alternative: Sequel.negate:
+Alternative:
 
-  Sequel.negate(:a=>1, :b=>[2, 3])
+  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)
   [[:a, 1], [:b, [2, 3]]].sql_or # SQL: a = 1 OR b IN (2, 3)
 
-Alternative: Sequel.or:
+Alternative:
 
-  Sequel.or(:a=>1, :b=>[2, 3])
+  Sequel.or(a: 1, b: [2, 3])
 
 === Array
 
@@ -316,10 +356,10 @@ Alternative: Sequel.or:
 
 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))
+  DB[:a].where('(a, b) IN ?', [[1, 2], [3, 4]])                # SQL: (a, b) IN ((1 = 2) AND (3 = 4))
+  DB[:a].where('(a, b) IN ?', [[1, 2], [3, 4]].sql_value_list) # SQL: (a, b) IN ((1, 2), (3, 4))
 
-Alternative: Sequel.value_list:
+Alternative:
 
   Sequel.value_list([[1, 2], [3, 4]])
 
@@ -327,12 +367,12 @@ Alternative: Sequel.value_list:
 
 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].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:
+Alternative:
 
   Sequel.join(['a', :b], ' ')
 
@@ -342,23 +382,24 @@ Alternative: Sequel.join:
 
 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
+  :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.&:
+Alternatives:
 
-  Sequel.&({:a=>1}, :b)
+  Sequel[a: 1] & :b
+  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.|:
+  :a | :b        # SQL: a OR b
+  {a: 1} | :b    # SQL: a = 1 OR b
+  {a: true} | :b # SQL: a IS TRUE OR b
 
-  Sequel.|({:a=>1}, :b)
+Alternative:
 
+  Sequel[a: 1] | :b
+  Sequel.|({a: 1}, :b)