sequel 3.11.0 → 3.12.0

data/doc/model_hooks.rdoc

@@ -0,0 +1,198 @@
+= Model Hooks
+
+This guide is based on http://guides.rubyonrails.org/activerecord_validations_callbacks.html
+
+== Overview
+
+Model hooks, also known as model callbacks, are used to specify actions that occur at a given point in a model instance's lifecycle, such as before or after the model object is saved, created, updated, destroyed, or validated.
+
+== Basic Usage
+
+<tt>Sequel::Model</tt> uses instance methods for hooks.  To define a hook on a model, you just add an instance method to the model class:
+
+  class Album < Sequel::Model
+    def before_create
+      self.created_at ||= Time.now
+      super
+    end
+  end
+
+The one important thing to note here is the call to +super+ inside the hook.  Whenever you override one of Sequel::Model's methods, you should be calling +super+ to get the default behavior.  Many of Sequel's built in plugins work by overriding the hook methods and calling +super+.  If you use these plugins and override the hook methods but do not call +super+, it's likely the plugins will not work correctly.
+
+== Available Hooks
+
+Sequel calls hooks in the following order when saving/creating a new object (one that does not already exist in the database):
+
+* +before_validation+
+* +after_validation+
+* +before_save+
+* +before_create+
+* INSERT QUERY
+* +after_create+
+* +after_save+
+
+Sequel calls hooks in the following order when saving an existing object:
+
+* +before_validation+
+* +after_validation+
+* +before_save+
+* +before_update+
+* UPDATE QUERY
+* +after_update+
+* +after_save+
+
+Note that all of the hook calls are the same, except that +before_create+ and +after_create+ are used for a new object, and +before_update+ and +after_update+ are used for an existing object.  Note that +before_save+ is called in both cases, before either +before_create+ or +before_update+, and that +after_save+ is also called in both cases, after either +after_create+ or +after_update+.
+
+Also note that the validation hooks are not called if the <tt>:validate => false</tt> option is passed to save.  However, the validation hooks are called if you call <tt>Model#valid?</tt> manually:
+
+* +before_validation+
+* VALIDATION HAPPENS
+* +after_validation+
+
+Sequel calls hooks in the following order when destroying an existing object:
+
+* +before_destroy+
+* DELETE QUERY
+* +after_destroy+
+
+Note that these hooks are only called when using <tt>Model#destroy</tt>, they are not called if you use <tt>Model#delete</tt>.
+
+<tt>Sequel::Model</tt> does support one additional hook, +after_intialize+, which is called after the model object has been initalized.  It can be used to set default attribute values for new objects, since by default new <tt>Sequel::Model</tt> objects have no attributes, and the attributes are not filled in until the model object is saved.  You should be careful when you are using +after_initialize+, since it is called for every created record.  So if you run a query that returns 1000 model objects, it will be called 1000 times.
+
+== Running Hooks
+
+Sequel does not provide a simple way to turn off the running of save/create/update hooks.  If you attempt to save a model object, the save hooks are always called.  All model instance methods that modify the database call save in some manner, so you can be sure that if you define the hooks, they will be called when you save the object.
+
+However, you should note that there are plenty of ways to modify the database without saving a model object.  One example is by using plain datasets, or one of the model's dataset methods:
+
+  Album.filter(:name=>'RF').update(:copies_sold=>:copies_sold + 1)
+  # UPDATE albums SET copies_sold = copies_sold + 1 WHERE name = 'RF'
+
+In this case, the +update+ method is called on the dataset returned by <tt>Album.filter</tt>.  Even if there is only a single object with the name RF, this will not call any hooks.  If you want model hooks to be called, you need to make sure to operate on a model object:
+
+  album = Album.first(:name=>'RF')
+  album.update(:copies_sold=>album.copies_sold + 1)
+  # UPDATE albums SET copies_sold = 2 WHERE id = 1
+
+For the destroy hooks, you need to make sure you call +destroy+ on the object:
+
+  album.destroy # runs destroy hooks
+
+== Skipping Hooks
+
+Sequel makes it easy to skip destroy hooks by calling +delete+ instead of +destroy+:
+
+  album.delete # does not run destroy hooks
+
+However, skipping hooks is a bad idea in general and should be avoided.  As mentioned above, Sequel doesn't allow you to turn off the running of save hooks. If you know what you are doing and really want to skip them, you need to drop down to the dataset level to do so.  This can be done for a specific model object by using the +this+ method for a dataset that represents a single object:
+
+  album.this # dataset
+
+The +this+ dataset works just like any other dataset, so you can call +update+ on it to modify it:
+
+  album.this.update(:copies_sold=>:copies_sold + 1)
+
+If you want to insert a row into the model's table without running the creation hooks, you can use <tt>Model.insert</tt> instead of <tt>Model.create</tt>:
+
+  Album.insert(:name=>'RF') # does not run hooks
+
+== Halting Hook Processing
+
+Sequel uses a convention that if any <tt>before_*</tt> hook method returns false (but not nil), that the action will be canceled.  You can use this to implement validation-like behavior, that will run even if validations are skipped.  For example:
+
+  class Album < Sequel::Model
+    def before_save
+      return false if name == ''
+      super
+    end
+  end
+
+While returning false is not really recommended, you should be aware of this behavior so that you do not inadvertently return false.
+
+By default, Sequel runs hooks other than validation hooks inside a transaction, so if you abort the hook by returning false in a before hook or by raising an exception in the hook, Sequel will rollback the transaction.  However, note that the implicit use of transactions when saving and destroying model objects is conditional (it depends on the model instance's +use_transactions+ setting).
+
+== Conditional Hooks
+
+Sometimes you only take to take a certain action in a hook if the object meets a certain condition.  For example, let's say you only want to make sure a timestamp is set when updating if the object is at a certain status level:
+
+  class Album < Sequel::Model
+    def before_update
+      self.timestamp ||= Time.now if status_id > 3
+      super
+    end
+  end
+
+Note how this hook action is made conditional just be using the standard ruby +if+ conditional.  Sequel makes it easy to handle conditional hook actions by using standard ruby conditionals inside the instance methods.
+
+== Using Hooks in Multiple Classes
+
+If you want all your model classes to use the same hook, you can just define that hook in Sequel::Model:
+
+  class Sequel::Model
+    def before_create
+      self.created_at ||= Time.now
+      super
+    end
+  end
+
+Just remember to call +super+ whenever you override the method in a subclass.  Note that +super+ is also used when overriding the hook in <tt>Sequel::Model</tt> itself.  This is important as if you add any plugins to Sequel::Model itself, if you override a hook in <tt>Sequel::Model</tt> and do not call +super+, the plugin may not work correctly.
+
+If you don't want all classes to use the same hook, but want to reuse hooks in multiple classes, you should use a plugin or a simple module:
+
+=== Plugin
+
+  module SetCreatedAt
+    module InstanceMethods
+      def before_create
+        self.created_at ||= Time.now
+        super
+      end
+    end
+  end
+  Album.plugin(SetCreatedAt)
+  Artist.plugin(SetCreatedAt)
+
+=== Simple Module
+
+  module SetCreatedAt
+    def before_create
+      self.created_at ||= Time.now
+      super
+    end
+  end
+  Album.send(:include, SetCreatedAt)
+  Artist.send(:include, SetCreatedAt)
+
+== +super+ Ordering
+
+While it's not enforced anywhere, it's a good idea to make +super+ the last expression when you override a before hook, and the first expression when you override an after hook:
+
+  class Album < Sequel::Model
+    def before_save
+      self.updated_at ||= Time.now
+      super
+    end
+
+    def after_save
+      super
+      AuditLog.create(:log=>"Album #{name} created")
+    end
+  end
+
+This allows the following general principles to be true:
+
+* before hooks are run in reverse order of inclusion
+* after hooks are run in order of inclusion
+
+So if you define the same before hook in both a model and a plugin that the model uses, the hooks will be called in this order:
+
+* model before hook
+* plugin before hook
+* plugin after hook
+* model after hook
+
+Again, Sequel does not enforce that, and you are free to call +super+ in an order other than the recommended one (just make sure that you call it).
+
+== +hook_class_methods+
+
+While it's recommended to write your hooks as instance methods, Sequel ships with a +hook_class_methods+ plugin that allows you to define hooks via class methods. It exists mostly for legacy compatibility, but is still supported. 

data/doc/querying.rdoc

@@ -12,80 +12,6 @@ While you can easily use raw SQL with Sequel, a large part of the
 advantage you get from using Sequel is Sequel's ability to abstract
 SQL from you and give you a much nicer interface.
 
-== Setup
-
-Some examples in this guide assume you will be using Sequel::Model
-for modeling, but most should work with plain datasets.  The examples
-specific to Sequel::Model will have [Sequel::Model] in the heading.
-
-Many of the examples in this guide will refer to the following model
-classes:
-
-  # All classes use :id as the primary key column
-  
-  class Artist < Sequel::Model
-    one_to_many :albums
-    one_to_one :address
-  end
-  
-  class Album < Sequel::Model
-    many_to_one :artist
-    one_to_many :tracks
-    many_to_many :tags
-  end
-  
-  class Address < Sequel::Model
-    many_to_one :artist
-  end
-  
-  class Tag < Sequel::Model
-    many_to_many :albums
-  end
-  
-  class Track < Sequel::Model
-    many_to_one :album
-  end
-
-If you want to play with the code examples, here's some Sequel code
-that will set up the database structure for you:
-
-  DB.create_table(:artists) do
-    primary_key :id
-    String :name
-  end
-  
-  DB.create_table(:albums) do
-    primary_key :id
-    foreign_key :artist_id, :artists
-    String :name
-  end
-  
-  DB.create_table(:addresses) do
-    primary_key :id
-    foreign_key :artist_id, :artists, :unique=>true
-    String :street
-    String :city
-    String :state
-    String :zip
-  end
-  
-  DB.create_table(:tags) do
-    primary_key :id
-    String :tag
-  end
-  
-  DB.create_table(:albums_tags) do
-    foreign_key :album_id, :albums
-    foreign_key :tag_id, :tags
-  end
-  
-  DB.create_table(:tracks) do
-    primary_key :id
-    foreign_key :album_id, :albums
-    Integer :number
-    String :name
-  end
-  
 == Retrieving Objects
 
 Sequel provides a few separate methods for retrieving objects from the
@@ -111,7 +37,7 @@ by its primary key value:
 
   # Find artist with primary key (id) 1
   artist = Artist[1]
-  # SQL: SELECT * FROM artists WHERE id = 1
+  # SELECT * FROM artists WHERE id = 1
   => #<Artist @values={:name=>"YJM", :id=>1}>
 
 If there is no record with the given primary key, nil will be returned.
@@ -122,24 +48,24 @@ If you just want the first record in the dataset,
 <tt>Sequel::Dataset#first</tt> is probably the most obvious method to use:
 
   artist = Artist.first
-  # SQL: SELECT * FROM artists LIMIT 1
+  # SELECT * FROM artists LIMIT 1
   => #<Artist @values={:name=>"YJM", :id=>1}>
 
 Any options you pass to +first+ will be used as a filter:
 
   artist = Artist.first(:name => 'YJM')
-  # SQL: SELECT * FROM artists WHERE (name = 'YJM') LIMIT 1
+  # SELECT * FROM artists WHERE (name = 'YJM') LIMIT 1
   => #<Artist @values={:name=>"YJM", :id=>1}>
   
   artist = Artist.first(:name.like('Y%'))
-  # SQL: SELECT * FROM artists WHERE (name LIKE 'Y%') LIMIT 1
+  # SELECT * FROM artists WHERE (name LIKE 'Y%') LIMIT 1
   => #<Artist @values={:name=>"YJM", :id=>1}>
   
 <tt>Sequel::Dataset#[]</tt> is basically an alias for +first+, except it
 requires an argument:
 
   DB[:artists][:name => 'YJM']
-  # SQL: SELECT * FROM artists WHERE (name = 'YJM') LIMIT 1
+  # SELECT * FROM artists WHERE (name = 'YJM') LIMIT 1
   => {:name=>"YJM", :id=>1}
 
 Note that while Model.[] allows you to pass a primary key directly,
@@ -153,13 +79,13 @@ that last requires that the dataset be ordered.  Without an order, any
 object can be considered the first as well as the last.
 
   artist = Artist.order(:name).last
-  # SQL: SELECT * FROM artists ORDER BY name DESC LIMIT 1
+  # SELECT * FROM artists ORDER BY name DESC LIMIT 1
   => #<Artist @values={:name=>"YJM", :id=>1}>
 
 Note that all +last+ does is reverse the order of the dataset and then
 call +first+.  This is why +last+ raises a Sequel::Error if there is no
 order on the dataset, because otherwise it would provide the same record
-as +first+, and most users would fine that confusing.
+as +first+, and most users would find that confusing.
 
 Note that +last+ is not necessarily going to give you the last record
 in the dataset unless you give the dataset an unambiguous order.
@@ -171,7 +97,7 @@ a specific column.  For this <tt>Sequel::Dataset#get</tt> is the method
 you want:
 
   artist_name = Artist.get(:name)
-  # SQL: SELECT name FROM artists LIMIT 1
+  # SELECT name FROM artists LIMIT 1
   => "YJM"
 
 === Retrieving Multiple Objects
@@ -183,7 +109,7 @@ dataset, in which case <tt>Sequel::Dataset#all</tt> is the method you
 want to use:
 
   artists = Artist.all
-  # SQL: SELECT * FROM artists
+  # SELECT * FROM artists
   => [#<Artist @values={:name=>"YJM", :id=>1}>,
       #<Artist @values={:name=>"AS", :id=>2}>]
 
@@ -194,7 +120,7 @@ method named each that yields hashes or model objects as they are retrieved
 from the database:
 
   Artist.each{|x| p x.name}
-  # SQL: SELECT * FROM artists
+  # SELECT * FROM artists
   "YJM"
   "AS"
 
@@ -202,9 +128,808 @@ This means that all of the methods in the Enumerable module are available,
 such as +map+:
 
   artist_names = Artist.map{|x| x.name}
-  # SQL: SELECT * FROM artists
+  # SELECT * FROM artists
   => ["YJM", "AS"]
 
 ==== As an Array of Column Values
 
-At 1.2.2 in Rails Guide
+Sequel also has an extended +map+ method that takes an argument.  If you
+provide an argument to +map+, it will return an array of values for the
+given column.  So the previous example can be handled more easily with:
+
+  artist_names = Artist.map(:name)
+  # SELECT * FROM artists
+  => ["YJM", "AS"]
+
+One difference between these two ways of return an array of values is
+that providing +map+ with an argument is really doing:
+
+  artist_names = Artist.map{|x| x[:name]} # not x.name
+
+Note that regardless of whether you provide +map+ with an argument, it
+does not modify the columns selected.  If you only want to select a
+single column and return an array of the columns values, you can use
++select_map+:
+
+  artist_names = Artist.select_map(:name)
+  # SELECT name FROM artists
+  => ["YJM", "AS"]
+
+It's also common to want to order such a map, so Sequel provides a
++select_order_map+ method as well:
+
+  artist_names = Artist.select_order_map(:name)
+  # SELECT name FROM artists ORDER BY name
+  => ["AS", "YJM"]
+
+==== As a Hash
+
+Sequel makes it easy to take an SQL query and return it as a ruby hash,
+using the +to_hash+ method:
+
+  artist_names = Artist.to_hash(:name, :id)
+  # SELECT * FROM artists
+  => {"YJM"=>1, "AS"=>2}
+
+As you can see, the +to_hash+ method uses the first symbol as the key
+and the second symbol as the value.  So if you swap the two arguments:
+
+  artist_names = Artist.to_hash(:id, :name)
+  # SELECT * FROM artists
+  => {1=>"YJM", 2=>"AS"}
+
+If you only provide one argument to +to_hash+, it uses the entire hash
+or model object as the value:
+
+  artist_names = DB[:artists].to_hash(:name)
+  # SELECT * FROM artists
+  => {"YJM"=>{:id=>1, :name=>"YJM"}, "AS"=>{:id=>2, :name=>"AS"}}
+
+Model datasets have a +to_hash+ method that can be called without any
+arguments, in which case it will use the primary key as the key and
+the model object as the value.  This can be used to easily create an
+identity map:
+
+  artist_names = Artist.to_hash
+  # SELECT * FROM artists
+  => {1=>#<Artist @values={:id=>1, :name=>"YGM"}>,
+      2=>#<Artist @values={:id=>2, :name=>"AS"}>}
+
+Note that +to_hash+ never modifies the columns selected.  However, just
+like Sequel has a +select_map+ method to modify the columns selected and
+return an array, Sequel also has a +select_hash+ method to modify the
+columns selected and return a hash:
+
+  artist_names = Artist.select_hash(:name, :id)
+  # SELECT name, id FROM artists
+  => {"YJM"=>1, "AS"=>2}
+
+== Modifying datasets 
+
+Note that the retrieval methods discussed above just return
+the row(s) included in the existing dataset.  In most cases,
+you aren't interested in every row in a table, but in a subset
+of the rows, based on some criteria.  In Sequel, filtering
+the dataset is generally done separately than retrieving
+the records.
+
+There are really two types of dataset methods that you will
+be using:
+
+1. Methods that return row(s), discussed above
+2. Methods that return modified datasets, discussed below
+
+Sequel uses a method chaining, functional style API to
+modify datasets.  Let's start with a simple example.
+
+This is a basic dataset that includes all records in the
+table +artists+:
+
+  ds1 = DB[:artists]
+  # SELECT * FROM artists
+
+Let's say we are only interested in the artists whose names
+start with "A":
+
+  ds2 = ds1.where(:name.like('A%'))
+  # SELECT * FROM artists WHERE name LIKE 'A%'
+
+Here we see that +where+ returns a dataset that adds a +WHERE+
+clause to the query.  It's important to note that +where+ does
+not modify the receiver:
+
+  ds1
+  # SELECT * FROM artists
+  ds2
+  # SELECT * FROM artists WHERE name LIKE 'A%'
+ 
+In Sequel, most dataset methods that you will be using will
+not modify the dataset itself, so you can freely use the dataset in multiple
+places without worrying that its usage in one place will affect its usage
+in another place.  This is what is meant by a functional style API.
+
+Let's say we only want to select the id and name columns, and that
+we want to order by name:
+
+  ds3 = ds.order(:name).select(:id, :name)
+  # SELECT id, name FROM artists WHERE name LIKE 'A%' ORDER BY name
+  
+Note how you don't need to assign the returned value of order to a variable,
+and then call select on that.  Because order just returns a dataset, you can
+call select directly on the returned dataset.  This is what is meant by a
+method chaining API.
+
+Also note how you can call methods that modify different clauses in any order.
+In this case, the WHERE clause was added first, then the ORDER clause, then the
+SELECT clause was modified.  This makes for a flexible API, where you can modify
+any part of the query at any time.
+
+== Filters
+
+Filtering is probably the most common dataset modifying action done in Sequel.
+Both the +where+ and +filter+ methods filter the dataset by modifying the
+dataset's WHERE clause.  While not quite aliases of each other, they operate
+the same in most cases.  Both accept a wide variety of input formats, discussed
+below.
+
+=== Hashes
+
+The most common format for providing filters is via a hash.  In general, Sequel
+treats conditions specified with a hash as equality or inclusion.  What type
+of condition is used depends on the values in the hash.
+
+Unless Sequel has special support for the value's class, it uses a simple
+equality statement:
+
+  Artist.filter(:id=>1)
+  # SELECT * FROM artists WHERE id = 1
+
+  Artist.filter(:name=>'YJM')
+  # SELECT * FROM artists WHERE name = 'YJM'
+
+For arrays, Sequel uses the IN operator.
+
+  Artist.filter(:id=>[1, 2])
+  # SELECT * FROM artists WHERE id IN (1, 2)
+
+For datasets, Sequel uses the IN operator with a subselect:
+
+  Artist.filter(:id=>Album.select(:artist_id))
+  # SELECT * FROM artists WHERE id IN (
+  #   SELECT artist_id FROM albums)
+
+For boolean values such as nil, true, and false, Sequel uses the IS operator:
+
+  Artist.filter(:id=>nil)
+  # SELECT * FROM artists WHERE id IS NULL
+
+For ranges, Sequel uses a pair of inequality statements:
+
+  Artist.filter(:id=>1..5)
+  # SELECT * FROM artists WHERE id >= 1 AND id <= 5
+
+Finally, for regexps, Sequel uses an SQL regular expression.  Note that this
+is probably only supported on PostgreSQL and MySQL.
+
+  Artist.filter(:name=>/JM$/)
+  # SELECT * FROM artists WHERE name ~ 'JM$'
+
+If there are multiple arguments in the hash, the filters are ANDed together:
+
+  Artist.filter(:id=>1, :name=>/JM$/)
+  # SELECT * FROM artists WHERE id = 1 AND name ~ 'JM$'
+
+This works the same as if you used two separate filter calls:
+
+  Artist.filter(:id=>1).filter(:name=>/JM$/)
+  # SELECT * FROM artists WHERE id = 1 AND name ~ 'JM$'
+
+=== Array of Two Element Arrays
+
+If you use an array of two element arrays, it is treated as a hash.  The only
+advantage to using an array of two element arrays is that it allows you to
+duplicate keys, so you can do:
+
+  Artist.filter([[:name, /JM$/], [:name, /^YJ/]])
+  # SELECT * FROM artists WHERE name ~ 'JM$' AND name ~ '^YJ'
+
+=== Virtual Row Blocks
+
+If a block is passed to filter, it is treated as a virtual row block:
+
+  Artist.filter{id > 5}
+  # SELECT * FROM artists WHERE id > 5
+
+You can learn more about virtual row blocks in the {"Virtual Rows" guide}[link:files/doc/virtual_rows_rdoc.html].
+
+You can provide both regular arguments and a block, in which case the results
+will be ANDed together:
+
+  Artist.filter(:name=>'A'...'M'){id > 5}
+  # SELECT * FROM artists WHERE name >= 'A' AND name < 'M' AND id > 5
+
+=== Symbols
+
+If you have a boolean column in the database, and you want only true
+values, you can just provide the column symbol to filter:
+
+  Artist.where(:retired)
+  # SELECT * FROM artists WHERE retired
+
+=== SQL::Expression
+
+Sequel has a DSL that allows easily creating SQL expressions.  These SQL
+expressions are instances of subclasses of Sequel::SQL::Expression. You've
+already seen an example earlier:
+
+  Artist.filter(:name.like('Y%'))
+  # SELECT * FROM artists WHERE name LIKE 'Y%'
+
+In this case Symbol#like returns a Sequel::SQL::BooleanExpression object,
+which is used directly in the filter.
+
+You can use the DSL to create arbitrarily complex expressions.  SQL::Expression
+objects support the & operator for +AND+, the | operator for +OR+, and the ~ operator
+for inversion:
+
+  Artist.filter(:name.like('Y%') & ({:b=>1} | ~{:c=>3}))
+  # SELECT * FROM artists WHERE name LIKE 'Y%' AND (b = 1 OR c != 3)
+
+You can combine these expression operators with the virtual row support:
+
+  Artist.filter{(a > 1) & ~((b(c) < 1) | d)}
+  # SELECT * FROM artists WHERE a > 1 AND b(c) >= 1 AND NOT d
+
+Note the use of parentheses when using the & and | operators, as they have lower
+precedence than other operators.  The following will not work:
+
+  Artist.filter{a > 1 & ~(b(c) < 1 | d)}
+  # Raises a TypeError, as it calls Integer#| with a Sequel::SQL::Identifier
+
+=== Strings with Placeholders
+
+Assuming you want to get your hands dirty and write some SQL, Sequel allows you
+to use strings using placeholders for the values:
+
+  Artist.filter("name LIKE ?", 'Y%')
+  # SELECT * FROM artists WHERE name LIKE 'Y%'
+
+This is the most common type of placeholder, where each question mark is substituted
+with the next argument:
+
+  Artist.filter("name LIKE ? AND id = ?", 'Y%', 5)
+  # SELECT * FROM artists WHERE name LIKE 'Y%' AND id = 5
+
+You can also use named placeholders with a hash, where the named placeholders use
+colons before the placeholder names:
+
+  Artist.filter("name LIKE :name AND id = :id", :name=>'Y%', :id=>5)
+  # SELECT * FROM artists WHERE name LIKE 'Y%' AND id = 5
+
+You don't have to provide any placeholders if you don't want to:
+
+  Artist.filter("id = 2")
+  # SELECT * FROM artists WHERE id = 2
+
+However, if you are using any untrusted input, you should definitely be using placeholders.
+In general, unless you are hardcoding values in the strings, you should use placeholders.
+You should never pass a string that has been built using interpolation, unless you are
+sure of what you are doing.
+
+  Artist.filter("id = #{params[:id]}") # Don't do this!
+  Artist.filter("id = ?", params[:id]) # Do this instead
+  Artist.filter(:id=>params[:id]) # Even better
+
+=== Inverting
+
+You may be wondering how to specify a not equals condition in Sequel, or the NOT IN
+operator.  Sequel has generic support for inverting conditions, so to write a not
+equals condition, you write an equals condition, and invert it:
+
+  Artist.filter(:id=>5).invert
+  # SELECT * FROM artists WHERE id != 5
+
+Note that +invert+ inverts the entire filter:
+
+  Artist.filter(:id=>5).filter{name > 'A'}.invert
+  # SELECT * FROM artists WHERE id != 5 OR name <= 'A'
+
+In general, +invert+ is used rarely, since +exclude+ allows you to invert only specific
+filters:
+
+  Artist.exclude(:id=>5)
+  # SELECT * FROM artists WHERE id != 5
+  
+  Artist.filter(:id=>5).exclude{name > 'A'}
+  # SELECT * FROM artists WHERE id = 5 OR name <= 'A'
+
+So to do a NOT IN with an array:
+
+  Artist.exclude(:id=>[1, 2])
+  # SELECT * FROM artists WHERE id NOT IN (1, 2)
+
+Or to use the NOT LIKE operator:
+
+  Artist.exclude(:name.like('%J%'))
+  # SELECT * FROM artists WHERE name NOT LIKE '%J%'
+ 
+=== Removing
+
+To remove all existing filters, use +unfiltered+:
+
+  Artist.filter(:id=>1).unfiltered
+  # SELECT * FROM artists
+
+== Ordering
+
+Sequel offers quite a few methods to manipulate the SQL ORDER BY clause.  The
+most basic of these is +order+:
+
+  Artist.order(:id)
+  # SELECT * FROM artists ORDER BY id
+
+You can specify multiple arguments to order by more than one column:
+
+  Album.order(:artist_id, :id)
+  # SELECT * FROM album ORDER BY artist_id, id
+
+Note that unlike +filter+, +order+ replaces an existing order, it does not
+append to an existing order:
+
+  Artist.order(:id).order(:name)
+  # SELECT * FROM artists ORDER BY name
+  
+If you want to add a column to the end of the existing order:
+
+  Artist.order(:id).order_append(:name)
+  # SELECT * FROM artists ORDER BY id, name
+
+If you want to add a column to the beginning of the existing order:
+
+  Artist.order(:id).order_prepend(:name)
+  # SELECT * FROM artists ORDER BY name, id
+
+=== Reversing
+
+Just like you can invert an existing filter, you can reverse an existing
+order, using +reverse+:
+
+  Artist.order(:id).reverse
+  # SELECT FROM artists ORDER BY id DESC
+
+As you might expect, +reverse+ is not used all that much.  In general,
+<tt>Symbol#desc</tt> is used more commonly to specify a descending order
+for columns:
+
+  Artist.order(:id.desc)
+  # SELECT FROM artists ORDER BY id DESC
+
+This allows you to easily use both ascending and descending orders:
+
+  Artist.order(:name, :id.desc)
+  # SELECT FROM artists ORDER BY name, id DESC
+
+=== Removing
+
+Just like you can remove filters with +unfiltered+, you can remove
+orders with +unordered+:
+
+  Artist.order(:name).unordered
+  # SELECT * FROM artists
+
+== Selected Columns
+
+Sequel offers a few methods to manipulate the columns selected.  As
+you may be able to guess, the main method used is +select+:
+
+  Artist.select(:id, :name)
+  # SELECT id, name FROM artists
+
+You just specify all of the columns that you are selecting as
+arguments to the method.
+
+If you are dealing with model objects, you'll want to include the
+primary key if you want to update or destroy the object.  You'll
+also want to include any keys (primary or foreign) related to
+associations you plan to use.
+
+If a column is not selected, and you attempt to access it, you will
+get nil:
+
+  artist = Artist.select(:name).first
+  # SELECT name FROM artists LIMIT 1
+
+  artist[:id]
+  # => nil
+
+Like +order+, +select+ replaces the existing selected columns:
+
+  Artist.select(:id).select(:name)
+  # SELECT name FROM artists
+
+To add to the existing selected columns, use +select_append+:
+
+  Artist.select(:id).select_append(:name)
+  # SELECT id, name FROM artists
+
+To remove specifically selected columns, and default back to all
+columns, use +select_all+:
+
+  Artist.select(:id).select_all
+  # SELECT * FROM artists
+
+=== Distinct
+
+To treat duplicate rows as a single row when retrieving the records,
+use +distinct+:
+
+  Artist.distinct.select(:name)
+  # SELECT DISTINCT name FROM artists
+
+Note that DISTINCT is a separate SQL clause, it's not a function
+that you pass to select.
+
+== Limit and Offset
+
+You can limit the dataset to a given number of rows using +limit+:
+
+  Artist.limit(5)
+  # SELECT * FROM artists LIMIT 5
+
+You can provide a second argument to +limit+ to specify an offset:
+
+  Artist.limit(5, 10)
+  # SELECT * FROM artists LIMIT 5 OFFSET 10
+
+This would return the 11th through 15th records in the original
+dataset.
+
+To remove a limit from a dataset, use +unlimited+:
+
+  Artist.limit(5, 10).unlimited
+  # SELECT * FROM artists
+
+== Grouping
+
+The SQL GROUP BY clause is used to combine multiple rows based on
+the values of a given group of columns.
+
+To modify the GROUP BY clause of the SQL statement, you use +group+:
+
+  Album.group(:artist_id)
+  # SELECT * FROM albums GROUP BY artist_id
+
+You can remove an existing grouping using +ungrouped+:
+
+  Album.group(:artist_id).ungrouped
+  # SELECT * FROM albums
+ 
+A common use of grouping is to count based on the number of grouped rows,
+and Sequel provides a +group_and_count+ method to make this easier:
+
+  Album.group_and_count(:artist_id)
+  # SELECT artist_id, COUNT(*) AS count FROM albums GROUP BY artist_id
+
+This will return the number of albums for each artist_id.
+
+== Having
+
+The SQL HAVING clause is similar to the WHERE clause, except that
+filters the results after the grouping has been applied, instead of
+before.  One possible use is if you only wanted to return artists
+who had at least 10 albums:
+
+  Album.group_and_count(:artist_id).having{count >= 10}
+  # SELECT artist_id, COUNT(*) AS count FROM albums
+  # GROUP BY artist_id HAVING count >= 10
+
+If you have an existing HAVING clause on your dataset, then +filter+
+will add to the HAVING clause instead of the WHERE clause:
+
+  Album.group_and_count(:artist_id).
+   having{count >= 10}.filter{count < 15}
+  # SELECT artist_id, COUNT(*) AS count FROM albums
+  # GROUP BY artist_id HAVING count >= 10 AND count < 15
+
+Unlike +filter+, +where+ always affects the WHERE clause:
+
+  Album.group_and_count(:artist_id).
+   having{count >= 10}.where(:name.like('A%'))
+  # SELECT artist_id, COUNT(*) AS count FROM albums
+  # WHERE name LIKE 'A%' GROUP BY artist_id HAVING count >= 10
+
+Both the WHERE clause and the HAVING clause are removed by +unfiltered+:
+
+  Album.group_and_count(:artist_id).having{count >= 10}.
+   where(:name.like('A%')).unfiltered
+  # SELECT artist_id, COUNT(*) AS count FROM albums GROUP BY artist_id
+
+== Joins
+
+Sequel makes it very easy to join a dataset to another table or dataset.
+The underlying method used is +join_table+:
+
+  Album.join_table(:inner, :artists, :id=>:artist_id)
+  # SELECT * FROM albums
+  # INNER JOIN artists ON artists.id = albums.artist_id
+
+In most cases, you won't call +join_table+ directly, as Sequel provides
+shortcuts for all common (and most uncommon) join types. For example
++join+ does an inner join:
+
+  Album.join(:artists, :id=>:artist_id)
+  # SELECT * FROM albums
+  # INNER JOIN artists ON artists.id = albums.artist_id
+
+And +left_join+ does a LEFT JOIN:
+
+  Album.left_join(:artists, :id=>:artist_id)
+  # SELECT * FROM albums
+  # LEFT JOIN artists ON artists.id = albums.artist_id
+
+=== Table/Dataset to Join
+
+For all of these specialized join methods, the first argument is
+generally the name of the table to which you are joining.  However, you
+can also provide a model class:
+
+  Album.join(Artist, :id=>:artist_id)
+
+Or a dataset, in which case a subselect is used:
+
+  Album.join(Artist.filter{name < 'A'}, :id=>:artist_id)
+  # SELECT * FROM albums
+  # INNER JOIN (SELECT * FROM artists WHERE (name < 'A')) AS t1
+  #  ON (t1.id = albums.artist_id)
+
+=== Join Conditions
+
+The second argument to the specialized join methods is the conditions 
+to use when joining, which is similar to a filter expression, with
+a few minor exceptions.
+
+==== Implicit Qualification
+
+A hash used as the join conditions operates similarly to a filter,
+except that unqualified symbol keys are automatically qualified
+with the table from the first argument, and unqualified symbol values
+are automatically qualified with the first table or the last table
+joined.  This implicit qualification is one of the reasons that joins
+in Sequel are easy to specify:
+
+  Album.join(:artists, :id=>:artist_id)
+  # SELECT * FROM albums
+  # INNER JOIN artists ON artists.id = albums.artist_id
+
+Note how the <tt>:id</tt> symbol is automatically qualified with +artists+,
+while the +artist_id+ symbol is automatically qualified with +albums+.
+
+Because Sequel uses the last joined table for implicit qualifications
+of values, you can do things like:
+
+  Album.join(:artists, :id=>:artist_id).
+   join(:members, :artist_id=>:id)
+  # SELECT * FROM albums
+  # INNER JOIN artists ON artists.id = albums.artist_id
+  # INNER JOIN members ON members.artist_id = artists.id
+
+Note that when joining to the +members+ table, +artist_id+ is qualified
+with +members+ and +id+ is qualified with +artists+.
+
+While a good default, implicit qualification is not always correct:
+
+  Album.join(:artists, :id=>:artist_id).
+   join(:tracks, :album_id=>:id)
+  # SELECT * FROM albums
+  # INNER JOIN artists ON artists.id = albums.artist_id
+  # INNER JOIN tracks ON tracks.album_id = artists.id
+
+Note here how +id+ is qualified with +artists+ instead of +albums+. This
+is wrong as the foreign key <tt>tracks.album_id</tt> refers to <tt>albums.id</tt>, not
+<tt>artists.id</tt>.  To fix this, you need to explicitly qualify when joining:
+
+  Album.join(:artists, :id=>:artist_id).
+   join(:tracks, :album_id=>:albums__id)
+  # SELECT * FROM albums
+  # INNER JOIN artists ON artists.id = albums.artist_id
+  # INNER JOIN tracks ON tracks.album_id = albums.id
+
+Just like in filters, an array of two element arrays is treated the same
+as a hash, but allows for duplicate keys:
+
+  Album.join(:artists, [[:id, :artist_id], [:id, 1..5]])
+  # SELECT * FROM albums INNER JOIN artists
+  #  ON artists.id = albums.artist_id
+  #   AND artists.id >= 1 AND artists.id <= 5
+
+And just like in the hash case, unqualified symbol elements in the
+array are implicitly qualified.
+
+==== USING Joins
+
+The most common type of join conditions is a JOIN ON, as displayed
+above.  However, the SQL standard allows for join conditions to be
+specified with JOIN USING, which Sequel makes easy to use.
+
+JOIN USING is useful when the columns you are using have the same
+names in both tables.  For example, if instead of having a primary
+column named +id+ in all of your tables, you use +artist_id+ in your
++artists+ table and +album_id+ in your +albums+ table, you could do:
+
+  Album.join(:artists, [:artist_id])
+  # SELECT * FROM albums INNER JOIN artists USING (artist_id)
+
+See here how you specify the USING columns as an array of symbols.
+
+==== NATURAL Joins
+
+NATURAL Joins take it one step further than USING joins, by assuming
+that all columns with the same names in both tables should be
+used for joining:
+
+  Album.natural_join(:artists)
+  # SELECT * FROM albums NATURAL JOIN artists
+
+In this case, you don't even need to specify any conditions.
+
+==== Join Blocks
+
+You can provide a block to any of the join methods that accept
+conditions.  This block should accept 3 arguments, the table alias
+for the table currently being joined, the table alias for the last
+table joined (or first table), and an array of previous
+<tt>Sequel::SQL::JoinClause</tt>s.
+
+This allows you to qualify columns similar to how the implicit
+qualification works, without worrying about the specific aliases
+being used.  For example, lets say you wanted to join the albums
+and artists tables, but only want albums where the artist's name
+comes before the album's name.
+
+  Album.join(:artists, :id=>:artist_id) do |j, lj, js|
+    :name.qualify(j) < :name.qualify(lj)
+  end
+  # SELECT * FROM albums INNER JOIN artists
+  # ON artists.id = albums.artist_id
+  # AND artists.name < albums.name
+
+Because greater than can't be expressed with a hash in Sequel, you
+need to use a block and qualify the tables manually.
+
+== From
+
+In general, the FROM table is the first clause populated when creating
+a dataset.  For a standard Sequel::Model, the dataset already has the
+FROM clause populated, and the most common way to create datasets is
+with the <tt>Database#[]</tt> method, which populates the FROM clause.
+
+However, you can modify the tables you are selecting FROM using +from+:
+
+  Album.from(:albums, :old_albums)
+  # SELECT * FROM albums, old_albums
+
+Be careful with this, as multiple tables in the FROM clause use a cross
+join by default, so the number of rows will be number of albums times the
+number of old albums.
+
+Using multiple FROM tables and setting conditions in the WHERE clause is
+an old-school way of joining tables:
+
+  DB.from(:albums, :artists).where(:artists__id=>:albums__artist_id)
+  # SELECT * FROM albums, artists WHERE artists.id = albums.artist_id
+
+=== Using the current dataset in a subselect
+
+In some cases, you may want to wrap the current dataset in a subselect.
+Here's an example using +from_self+:
+
+  Album.order(:artist_id).limit(100).from_self.group(:artist_id)
+  # SELECT * FROM (SELECT * FROM albums ORDER BY artist_id LIMIT 100)
+  #  AS t1 GROUP BY artist_id
+
+This is slightly different than without +from_self+:
+
+  Album.order(:artist_id).limit(100).group(:artist_id)
+  # SELECT * FROM albums GROUP BY artist_id ORDER BY name LIMIT 100
+
+Without +from_self+, you are doing the grouping, and limiting the number
+of grouped records returned to 100.  So assuming you have albums by more
+than 100 artists, you'll end up with 100 results.
+
+With +from_self+, you are limiting the number of records before grouping.
+So if the artist with the lowest id had 100 albums, you'd get 1 result,
+not 100.
+
+== Locking for Update
+
+Sequel allows you to easily add a FOR UPDATE clause to your queries so
+that the records returned can't be modified by another query until the
+current transaction commits.  You just use the +for_update+ dataset
+method when returning the rows:
+
+  DB.transaction do
+    album = Album.for_update.first(:id=>1)
+    # SELECT * FROM albums WHERE id = 1 FOR UPDATE
+    album.num_tracks += 1
+    album.save
+  end
+
+This will ensure that no other connection modifies the row between when you select
+it and when the transaction ends.
+
+=== Optimistic Locking
+
+One of Sequel's built-in model plugins is an optimistic locking plugin, which provides
+a database independent way to detect and raise an error if two different connections
+modify the same row.  It's useful for things like web forms where you cannot keep a
+transaction open while the user is looking at the form, because of the web's
+stateless nature.
+
+== Custom SQL
+
+Sequel makes it easy to use custom SQL by providing it to the <tt>Database#[]</tt>
+method as a string:
+
+  DB["SELECT * FROM artists"]
+  # SELECT * FROM artists
+
+You can also use the +with_sql+ dataset method to return a dataset that uses that
+exact SQL:
+
+  DB[:albums].with_sql("SELECT * FROM artists")
+  # SELECT * FROM artists
+
+With either of these methods, you can use placeholders:
+
+  DB["SELECT * FROM artists WHERE id = ?", 5]
+  # SELECT * FROM artists WHERE id = 5
+
+  DB[:albums].with_sql("SELECT * FROM artists WHERE id = :id", :id=>5)
+  # SELECT * FROM artists WHERE id = 5
+
+== Checking for Records
+
+If you just want to know whether the current dataset would return any rows, use <tt>empty?</tt>:
+
+  Album.empty?
+  # SELECT 1 FROM albums LIMIT 1
+  => false
+
+  Album.filter(:id=>0).empty?
+  # SELECT 1 FROM albums WHERE id = 0 LIMIT 1
+  => true
+
+  Album.filter(:name.like('R%')).empty?
+  # SELECT 1 FROM albums WHERE name LIKE 'R%' LIMIT 1
+  => false
+
+== Aggregate Calculations
+
+The SQL standard defines a few helpful methods to get aggreate information about
+datasets, such as +count+, +sum+, +avg+, +min+, and +max+.  There are dataset methods
+for each of these aggregate functions.
+
++count+ just returns the number of records in the dataset.
+
+  Album.count
+  # SELECT COUNT(*) AS count FROM albums LIMIT 1
+  => 2
+  
+The other methods take a column argument and call the aggregate function with
+the argument:
+
+  Album.sum(:id)
+  # SELECT sum(id) FROM albums LIMIT 1
+  => 3
+
+  Album.avg(:id)
+  # SELECT avg(id) FROM albums LIMIT 1
+  => 1.5
+
+  Album.min(:id)
+  # SELECT min(id) FROM albums LIMIT 1
+  => 1
+
+  Album.max(:id)
+  # SELECT max(id) FROM albums LIMIT 1
+  => 2