sequel 3.21.0 → 3.41.0

data/doc/bin_sequel.rdoc

@@ -0,0 +1,144 @@
+= bin/sequel
+
+bin/sequel is the name used to refer to the "sequel" command line tool that ships with the sequel gem.  By default, bin/sequel provides an IRB shell with the +DB+ constant set to a Sequel::Database object created using the database connection string provided on the command line.  For example, to connect to a new in-memory SQLite database using the sqlite adapter, you can use the following:
+
+  sequel sqlite:/
+
+This is very useful for quick testing of ideas, and does not affect the environment, since the in-memory SQLite database is destroyed when the program exits.
+
+== Running from a git checkout
+
+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.
+
+== Choosing the Database to Connect to
+
+=== Connection String
+
+In general, you probably want to provide a connection string argument to bin/sequel, indicating the adapter and database connection information you want to use.  For example:
+
+  sequel sqlite:/
+  sequel postgres://user:pass@host/database_name
+  sequel mysql2://user:pass@host/database_name
+
+See the {Connecting to a database guide}[link:files/doc/opening_databases_rdoc.html] for more details about and examples of connection strings.
+
+=== YAML Connection File
+
+Instead of specifying the database connection using a connection string, you can provide the path to a YAML configuration file containing the connection information.  This YAML file can contain a single options hash, or it can contain a nested hash, where the top-level hash uses environment keys with hash values for
+each environment.  Using the -e option with a yaml connection file, you can choose which environment to use if using a nested hash.
+
+  sequel -e production config/database.yml
+
+Note that bin/sequel does not directly support ActiveRecord YAML configuration files, as they use different names for some options.
+
+=== Mock Connection
+
+If you don't provide a connection string or YAML connection file, Sequel will start with a mock database.  The mock database allows you to play around with Sequel without any database at all, and can be useful if you just want to test things out and generate SQL without actually getting results from a database.
+
+  sequel
+
+Sequel also has the ability to use the mock adapter with database-specific syntax, allowing you to pretend you are connecting to a specific type of database without actually connecting to one.  To do that, you need to use a connection string:
+
+  sequel mock://postgres
+
+== Not Just an IRB shell
+
+bin/sequel is not just an IRB shell, it can also do far more.
+
+=== Execute Code
+
+bin/sequel can also be used to execute other ruby files with +DB+ preset to the database given on the command line:
+
+  sequel postgres://host/database_name path/to/some_file.rb
+
+On modern versions of Linux, this means that you can use bin/sequel in a shebang line:
+
+  #!/path/to/bin/sequel postgres://host/database_name
+
+If you want to quickly execute a small piece of ruby code, you can use the -c option:
+
+  sequel -c "p DB.tables" postgres://host/database_name
+
+Similarly, if data is piped into bin/sequel, it will be executed:
+
+  echo "p DB.tables" | sequel postgres://host/database_name
+
+=== Migrate Databases
+
+With -m option, Sequel will migrate the database given using the migration directory provided by -m:
+
+  sequel -m /path/to/migrations/dir postgres://host/database
+
+You can use the -M attribute to set the version to migrate to:
+
+  sequel -m /path/to/migrations/dir -M 3 postgres://host/database
+
+See the {migration guide}[link:files/doc/migration_rdoc.html] for more details about migrations.
+
+=== Dump Schemas
+
+Using the -d or -D options, Sequel will dump the database's schema in Sequel migration format to the standard output:
+
+  sequel -d postgres://host/database
+
+To save this information to a file, use a standard shell redirection:
+
+  sequel -d postgres://host/database > /path/to/migrations/dir/001_base_schema.rb
+
+The -d option dumps the migration in database-independent format, the -D option dumps it in database-specific format.
+
+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
+
+=== Copy Databases
+
+Using the -C option, Sequel can copy the contents of one database to another, even between different database types.  Using this option, you provide two connection strings on the command line:
+
+  sequel -C mysql://host1/database postgres://host2/database2
+
+This copies the table structure, table data, indexes, and foreign keys from the MySQL database to the PostgreSQL database.
+
+== Other Options
+
+Other options not mentioned above are explained briefly here.
+
+=== -E
+
+-E logs all SQL queries to the standard output, so you can see all SQL that Sequel is sending the database.
+
+=== -I include_directory
+
+-I is similar to ruby -I, and specifies an additional $LOAD_PATH directory.
+
+=== -l log_file
+
+-l is similar to -E, but logs all SQL queries to the given file.
+
+=== -L load_directory
+
+-L loads all *.rb files under the given directory.  This is usually used to load Sequel::Model classes into bin/sequel.
+
+=== -N
+
+-N skips testing the connection when creating the Database object.  This is rarely needed.
+
+=== -r require_lib
+
+-r is similar to ruby -r, requiring the given library.
+
+=== -t
+
+-t tells bin/sequel to output full backtraces in the case of an error, which can aid in debugging.
+
+=== -h
+
+-h prints the usage information for bin/sequel.
+
+=== -v
+
+-v prints the Sequel version in use.

data/doc/cheat_sheet.rdoc

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

data/doc/core_extensions.rdoc

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

data/doc/dataset_basics.rdoc

@@ -2,7 +2,7 @@
 
 == Introduction
 
-Datasets are probably the thing that separate Sequel from other database libraries.  While most database libraries have specific support for updating all records or only a single record, Sequel's ability to represent SQL queries themselves as objects is what gives Sequel most of its power.  However, if you haven't been exposed to the dataset concept before, it can be a little disorienting.  This document aims to give a basic introduction to datasets and how to use them.
+Datasets are the primary way Sequel uses to access the database. While most database libraries have specific support for updating all records or only a single record, Sequel's ability to represent SQL queries themselves as objects is what gives Sequel most of its power.  However, if you haven't been exposed to the dataset concept before, it can be a little disorienting.  This document aims to give a basic introduction to datasets and how to use them.
 
 == What a Dataset Represents
 
@@ -24,23 +24,23 @@ Here, DB represents your Sequel::Database object, and ds is your dataset, with t
 
 One of the core dataset ideas that should be understood is that datasets use a functional style of modification, in which methods called on the dataset return modified copies of the dataset, they don't modify the dataset themselves:
 
-  ds2 = ds.filter(:id=>1)
+  ds2 = ds.where(:id=>1)
   ds2
   # SELECT * FROM posts WHERE id = 1
   ds
   # SELECT * FROM posts
   
-Note how ds itself is not modified.  This is because ds.filter returns a modified copy of ds, instead of modifying ds itself.  This makes using datasets both thread safe and easy to chain:
+Note how ds itself is not modified.  This is because ds.where returns a modified copy of ds, instead of modifying ds itself.  This makes using datasets both thread safe and easy to chain:
 
   # Thread safe:
   100.times do |i|
     Thread.new do
-      ds.filter(:id=>i).first
+      ds.where(:id=>i).first
     end
   end
   
   # Easy to chain:
-  ds3 = ds.select(:id, :name).order(:name).filter{id < 100}
+  ds3 = ds.select(:id, :name).order(:name).where{id < 100}
   # SELECT id, name FROM posts WHERE id < 100 ORDER BY name
 
 Thread safety you don't really need to worry about, but chainability is core to how Sequel is generally used.  Almost all dataset methods that affect the SQL produced return modified copies of the receiving dataset.
@@ -74,12 +74,12 @@ Most Dataset methods that users will use can be broken down into two types:
 
 Most dataset methods fall into this category, which can be further broken down by the clause they affect:
 
-SELECT:: select, select_all, select_append, select_more
+SELECT:: select, select_all, select_append, select_group, select_more
 FROM:: from, from_self
 JOIN:: join, left_join, right_join, full_join, natural_join, natural_left_join, natural_right_join, natural_full_join, cross_join, inner_join, left_outer_join, right_outer_join, full_outer_join, join_table
-WHERE:: where, filter, exclude, and, or, grep, invert, unfiltered
-GROUP:: group, group_by, group_and_count, ungrouped
-HAVING:: having, filter, exclude, and, or, grep, invert, unfiltered
+WHERE:: where, filter, exclude, exclude_where, and, or, grep, invert, unfiltered
+GROUP:: group, group_by, group_and_count, select_group, ungrouped
+HAVING:: having, filter, exclude, exclude_having, and, or, grep, invert, unfiltered
 ORDER:: order, order_by, order_append, order_prepend, order_more, reverse, reverse_order, unordered
 LIMIT:: limit, unlimited
 compounds:: union, intersect, except
@@ -93,7 +93,7 @@ other:: clone, distinct, naked, server, with_sql
 
 Most other dataset methods commonly used will execute the dataset's SQL on the database:
 
-SELECT (All Records):: all, each, map, to_hash, select_map, select_order_map, select_hash, to_csv
+SELECT (All Records):: all, each, map, to_hash, to_hash_groups, select_map, select_order_map, select_hash, select_hash_groups, to_csv
 SELECT (First Record):: first, last, get, []
 SELECT (Aggregates):: count, avg, max, min, sum, range, interval
 INSERT:: insert, <<, import, multi_insert, insert_multiple