RubyGems - tdiary - Versions diffs - 5.0.9 → 5.0.10 - Mend

tdiary 5.0.9 → 5.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4114) hide show

data/vendor/bundle/gems/sequel-5.9.0/doc/prepared_statements.rdoc DELETED

@@ -1,144 +0,0 @@
-= Prepared Statements and Bound Variables
-Sequel has support for prepared statements and bound variables.  No matter which
-database you are using, the Sequel prepared statement/bound variable API remains
-the same.  There is native support for prepared statements/bound variables on
-the following adapters:
-* ibmdb (prepared statements only)
-* jdbc
-* mysql (server prepared statements using literalized connection variables)
-* mysql2 (full support on 0.4+, otherwise server prepared statements using literalized connection variables)
-* oracle (requires type specifiers for nil/NULL values)
-* postgres (when using the pg driver)
-* sqlite
-* tinytds
-Support on other adapters is emulated.
-You can use the prepared_statements model plugin to automatically use prepared
-statements for some common model actions such as saving or deleting a model
-instance, or looking up a model based on a primary key.
-== Placeholders
-Generally, when using prepared statements (and certainly when using bound
-variables), you need to put placeholders in your SQL to indicate where you
-want your bound arguments to appear.  Database support and syntax vary
-significantly for placeholders (e.g. :name, $1, ?).  Sequel abstracts all of
-that and allows you to specify placeholders by using the :$name format for
-placeholders, e.g.:
-  ds = DB[:items].where(name: :$n)
-You can use these placeholders in most places where you can use the value
-directly.  For example, if you want to use placeholders while also using
-raw SQL, you can do:
-  ds = DB["SELECT * FROM items WHERE name = ?", :$n]
-== Bound Variables
-Using bound variables for this query is simple:
-  ds.call(:select, n: 'Jim')
-This will do the equivalent of selecting records that have the name 'Jim'. It
-returns all records, and can take a block that is passed to <tt>Dataset#all</tt>.
-Deleting or returning the first record works similarly:
-  ds.call(:first, n: 'Jim') # First record with name 'Jim'
-  ds.call(:delete, n: 'Jim') # Delete records with name 'Jim'
-For inserting/updating records, you should also specify a value hash, which
-may itself contain placeholders:
-  # Insert record with 'Jim', note that the previous filter is ignored
-  ds.call(:insert, {n: 'Jim'}, name: :$n)
-  # Change name to 'Bob' for all records with name of 'Jim'
-  ds.call(:update, {n: 'Jim', new_n: 'Bob'}, name: :$new_n)
-== Prepared Statements
-Prepared statement support is similar to bound variable support, but you
-use <tt>Dataset#prepare</tt> with a name, and <tt>Dataset#call</tt> or <tt>Database#call</tt> later with the values:
-  ds = DB[:items].where(name: :$n)
-  ps = ds.prepare(:select, :select_by_name)
-  ps.call(n: 'Jim')
-  DB.call(:select_by_name, n: 'Jim') # same
-The <tt>Dataset#prepare</tt> method returns a prepared statement, and also stores a
-copy of the prepared statement in the database for later use.  For insert
-and update queries, the hash to insert/update is passed to +prepare+:
-  ps1 = DB[:items].prepare(:insert, :insert_with_name, name: :$n)
-  ps1.call(n: 'Jim')
-  DB.call(:insert_with_name, n: 'Jim') # same
-  ds = DB[:items].where(name: :$n)
-  ps2 = ds.prepare(:update, :update_name, name: :$new_n)
-  ps2.call(n: 'Jim', new_n: 'Bob')
-  DB.call(:update_name, n: 'Jim', new_n: 'Bob') # same
-== Implementation Issues
-Currently, creating a prepared statement uses Object#extend, which can hurt
-performance.  For high performance applications, it's recommended to create
-all of your prepared statements upon application initialization, and not
-to create prepared statements dynamically at runtime.
-== Database support
-=== PostgreSQL
-If you are using the postgres-pr driver, PostgreSQL uses the
-default emulated support.  If you are using ruby-pg, there is native support
-for both prepared statements and bound variables.  Prepared statements are
-always server side.
-=== SQLite
-SQLite supports both prepared statements and bound variables.
-=== MySQL/Mysql2
-The MySQL and Mysql2 <0.4 ruby drivers do not support bound variables, so the bound
-variable methods are emulated.  It uses server side prepared statements.
-Mysql2 0.4+ supports both prepared statements and bound variables.
-=== JDBC
-JDBC supports both prepared statements and bound variables.  Whether these
-are server side or client side depends on the JDBC driver.  For PostgreSQL
-over JDBC, you can add the prepareThreshold=N parameter to the connection
-string, which will use a server side prepared statement after N calls to
-the prepared statement.
-=== TinyTDS
-Uses the sp_executesql stored procedure with bound variables, since
-Microsoft SQL Server doesn't support true prepared statements.
-=== IBM_DB
-DB2 supports both prepared statements and bound variables.
-=== Oracle
-Oracle supports both prepared statements and bound variables.  Prepared
-statements (OCI8::Cursor objects) are cached per connection.  If you
-ever plan to use a nil/NULL value as a bound variable/prepared statement
-value, you must specify the type in the placeholder using a __* suffix.
-You can use any of the schema types that Sequel supports, such as
-:$name__string or :$num__integer.  Using blobs as bound variables is
-not currently supported.
-=== All Others
-Support is emulated.

data/vendor/bundle/gems/sequel-5.9.0/doc/querying.rdoc DELETED

@@ -1,1063 +0,0 @@
-= Querying in Sequel
-This guide is based on http://guides.rubyonrails.org/active_record_querying.html
-== Purpose of this Guide
-Sequel is a flexible and powerful database library
-that supports a wide variety of different querying methods.  This guide
-aims to be a introduction to Sequel's querying support.
-While you can 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 pure-ruby interface. Sequel also ships with
-a {core_extensions extension}[rdoc-ref:doc/core_extensions.rdoc],
-which adds methods to core ruby types to work with Sequel.
-== Retrieving Objects
-Sequel provides a few separate methods for retrieving objects from the
-database.  The underlying method is Sequel::Dataset#each, which yields each
-row as the Sequel::Database provides it.  However, while Dataset#each can and
-often is used directly, in many cases there is a more convenient retrieval
-method you can use.
-=== Sequel::Dataset
-If you are new to Sequel and aren't familiar with Sequel, you should probably
-read the {"Dataset Basics" guide}[rdoc-ref:doc/dataset_basics.rdoc],
-then come back here.
-=== Retrieving a Single Object
-Sequel offers quite a few ways to to retrieve a single object.
-==== Using a Primary Key [Sequel::Model]
-The <tt>Sequel::Model.[]</tt> is the easiest method to use to find a model instance
-by its primary key value:
-  # Find artist with primary key (id) 1
-  artist = Artist[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. If you want
-to raise an exception if no record is found, you can use <tt>Sequel::Model.with_pk!</tt>:
-  artist = Artist.with_pk!(1)
-==== Using +first+
-If you want the first record in the dataset,
-<tt>Sequel::Dataset#first</tt> is probably the most obvious method to use:
-  artist = Artist.first
-  # 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')
-  # SELECT * FROM artists WHERE (name = 'YJM') LIMIT 1
-  # => #<Artist @values={:name=>"YJM", :id=>1}>
-  artist = Artist.first(Sequel.like(:name, 'Y%'))
-  # SELECT * FROM artists WHERE (name LIKE 'Y%' ESCAPE '\') LIMIT 1
-  # => #<Artist @values={:name=>"YJM", :id=>1}>
-If there is no matching row, +first+ will return nil.  If you want to
-raise an exception instead, use <tt>first!</tt>.
-<tt>Sequel::Dataset#[]</tt> is basically an alias for +first+, except it
-requires an argument:
-  DB[:artists][{name: 'YJM'}]
-  # SELECT * FROM artists WHERE (name = 'YJM') LIMIT 1
-  # => {:name=>"YJM", :id=>1}
-Note that while Model.[] allows you to pass a primary key directly,
-Dataset#[] does not (unless it is a model dataset).
-==== Using +last+
-If you want the last record in the dataset,
-<tt>Sequel::Dataset#last</tt> is an obvious method to use.  +last+ requires the
-dataset be ordered, unless the dataset is a model dataset in which case +last+
-will do a reverse order by the primary key field:
-  artist = Artist.last
-  # SELECT * FROM artists ORDER BY id DESC LIMIT 1
-  # => #<Artist @values={:name=>"YJM", :id=>1}>
-Note:
-1. +last+ is equivalent to running a +reverse.first+ query, in other words it reverses the order of the dataset and then calls +first+.  This is why +last+ raises a Sequel::Error when there is no order on a plain dataset - because it will provide the same record as +first+, and most users will find that confusing.
-2. +last+ is not necessarily going to give you the last record in the dataset unless you give the dataset an unambiguous order.
-3. +last+ will ignore +limit+ if chained together in a query because it sets a limit of 1 if no arguments are given.
-==== Retrieving a Single Column Value
-Sometimes, instead of wanting an entire row, you only want the value of
-a specific column.  For this <tt>Sequel::Dataset#get</tt> is the method
-you want:
-  artist_name = Artist.get(:name)
-  # SELECT name FROM artists LIMIT 1
-  # => "YJM"
-==== Retrieving a Multiple Column Values
-If you want the value for multiple columns, you can pass an array to
-<tt>Sequel::Dataset#get</tt>:
-  artist_id, artist_name = Artist.get([:id, :name])
-  # SELECT id, name FROM artists LIMIT 1
-  # => [1, "YJM"]
-=== Retrieving Multiple Objects
-==== As an Array of Hashes or Model Objects
-In many cases, you want an array of all of the rows associated with the
-dataset, in which case <tt>Sequel::Dataset#all</tt> is the method you
-want to use:
-  artists = Artist.all
-  # SELECT * FROM artists
-  # => [#<Artist @values={:name=>"YJM", :id=>1}>,
-  #     #<Artist @values={:name=>"AS", :id=>2}>]
-==== Using an Enumerable Interface
-<tt>Sequel::Dataset</tt> uses an Enumerable Interface, so it provides a
-method named each that yields hashes or model objects as they are retrieved
-from the database:
-  Artist.each{|x| p x.name}
-  # SELECT * FROM artists
-  "YJM"
-  "AS"
-This means that all of the methods in the Enumerable module are available,
-such as +map+:
-  artist_names = Artist.map{|x| x.name}
-  # SELECT * FROM artists
-  # => ["YJM", "AS"]
-==== As an Array of Column Values
-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 returning 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"]
-In all of these cases, you can provide an array of column symbols and
-an array of arrays of values will be returned:
-  artist_names = Artist.select_map([:id, :name])
-  # SELECT id, name FROM artists
-  # => [[1, "YJM"], [2, "AS"]]
-==== As a Hash
-Sequel makes it easy to take an SQL query and return it as a ruby hash,
-using the +as_hash+ method:
-  artist_names = Artist.as_hash(:id, :name)
-  # SELECT * FROM artists
-  # => {1=>"YJM", 2=>"AS"}
-As you can see, the +as_hash+ method uses the first symbol as the key
-and the second symbol as the value.  So if you swap the two arguments the hash
-will have its keys and values transposed:
-  artist_names = Artist.as_hash(:name, :id)
-  # SELECT * FROM artists
-  # => {"YJM"=>1, "AS"=>2}
-Now what if you have multiple values for the same key?  By default, +as_hash+
-will just have the last matching value.  If you care about all matching values,
-use +to_hash_groups+, which makes the values of the array an array of matching
-values, in the order they were received:
-  artist_names = Artist.to_hash_groups(:name, :id)
-  # SELECT * FROM artists
-  # => {"YJM"=>[1, 10, ...], "AS"=>[2, 20, ...]}
-If you only provide one argument to +as_hash+, it uses the entire hash
-or model object as the value:
-  artist_names = DB[:artists].as_hash(:name)
-  # SELECT * FROM artists
-  # => {"YJM"=>{:id=>1, :name=>"YJM"}, "AS"=>{:id=>2, :name=>"AS"}}
-and +to_hash_groups+ works similarly:
-  artist_names = DB[:artists].to_hash_groups(:name)
-  # SELECT * FROM artists
-  # => {"YJM"=>[{:id=>1, :name=>"YJM"}, {:id=>10, :name=>"YJM"}], ...}
-Model datasets have a +as_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.as_hash
-  # SELECT * FROM artists
-  # => {1=>#<Artist @values={:id=>1, :name=>"YGM"}>,
-  #     2=>#<Artist @values={:id=>2, :name=>"AS"}>}
-There is no equivalent handling to +to_hash_groups+, since there would
-only be one matching record, as the primary key must be unique.
-Note that +as_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}
-Likewise, +select_hash_groups+ also exists:
-  artist_names = Artist.select_hash_groups(:name, :id)
-  # SELECT name, id FROM artists
-  # => {"YJM"=>[1, 10, ...], "AS"=>[2, 20, ...]}
-== 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 datasets are frozen and use a method chaining, functional style API
-that returns modified 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(Sequel.like(:name, 'A%'))
-  # SELECT * FROM artists WHERE (name LIKE 'A%' ESCAPE '\')
-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%' ESCAPE '\')
-In Sequel, dataset methods do 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 = ds2.order(:name).select(:id, :name)
-  # SELECT id, name FROM artists WHERE (name LIKE 'A%' ESCAPE '\') 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.  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, inclusion, or identity.  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.where(id: 1)
-  # SELECT * FROM artists WHERE (id = 1)
-  Artist.where(name: 'YJM')
-  # SELECT * FROM artists WHERE (name = 'YJM')
-For arrays, Sequel uses the IN operator with a value list:
-  Artist.where(id: [1, 2])
-  # SELECT * FROM artists WHERE (id IN (1, 2))
-For datasets, Sequel uses the IN operator with a subselect:
-  Artist.where(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.where(id: nil)
-  # SELECT * FROM artists WHERE (id IS NULL)
-For ranges, Sequel uses a pair of inequality statements:
-  Artist.where(id: 1..5)
-  # SELECT * FROM artists WHERE ((id >= 1) AND (id <= 5))
-  Artist.where(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.where(name: /JM$/)
-  # SELECT * FROM artists WHERE (name ~ 'JM$')
-If there are multiple arguments in the hash, the filters are ANDed together:
-  Artist.where(id: 1, name: /JM$/)
-  # SELECT * FROM artists WHERE ((id = 1) AND (name ~ 'JM$'))
-This works the same as if you used two separate +where+ calls:
-  Artist.where(id: 1).where(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.where([[:name, /JM$/], [:name, /^YJ/]])
-  # SELECT * FROM artists WHERE ((name ~ 'JM$')) AND ((name ~ '^YJ'))
-=== Virtual Row Blocks
-If a block is passed to a filter, it is treated as a virtual row block:
-  Artist.where{id > 5}
-  # SELECT * FROM artists WHERE (id > 5)
-You can learn more about virtual row blocks in the {"Virtual Rows" guide}[rdoc-ref:doc/virtual_rows.rdoc].
-You can provide both regular arguments and a block, in which case the results
-will be ANDed together:
-  Artist.where(name: 'A'...'M'){id > 5}
-  # SELECT * FROM artists WHERE ((name >= 'A') AND (name < 'M') AND (id > 5))
-Using virtual row blocks, what you can do with single entry hash or an array with
-a single two element array can also be done using the =~ method:
-  Artist.where{id =~ 5}
-  # SELECT * FROM artists WHERE (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.where(Sequel.like(:name, 'Y%'))
-  # SELECT * FROM artists WHERE name LIKE 'Y%' ESCAPE '\'
-In this case Sequel.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 can be created via singleton methods on the Sequel module.  The most common
-method is Sequel.[], which takes any object and wraps it in a SQL::Expression
-object.  In most cases, the SQL::Expression returned supports the & operator for
-+AND+, the | operator for +OR+, and the ~ operator for inversion:
-  Artist.where(Sequel.like(:name, 'Y%') & (Sequel[{b: 1}] | Sequel.~(c: 3)))
-  # SELECT * FROM artists WHERE ((name LIKE 'Y%' ESCAPE '\') AND ((b = 1) OR (c != 3)))
-You can combine these expression operators with the virtual row support:
-  Artist.where{(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.where{a > 1 & ~(b(c) < 1 | d)}
-  # Raises a TypeError
-=== Strings with Placeholders
-Assuming you want to get your hands dirty and use SQL fragments in filters, Sequel allows you
-to do so if you explicitly mark the strings as literal strings using +Sequel.lit+. You can
-use placeholders in the string and pass arguments for the placeholders:
-  Artist.where(Sequel.lit("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.where(Sequel.lit("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.where(Sequel.lit("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.where(Sequel.lit("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.where(Sequel.lit("id = #{params[:id]}")) # Don't do this!
-  Artist.where(Sequel.lit("id = ?", params[:id])) # Do this instead
-  Artist.where(id: params[:id].to_i)              # 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.where(id: 5).invert
-  # SELECT * FROM artists WHERE (id != 5)
-Note that +invert+ inverts the entire filter:
-  Artist.where(id: 5).where{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.where(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(Sequel.like(:name, '%J%'))
-  # SELECT * FROM artists WHERE (name NOT LIKE '%J%' ESCAPE '\')
-You can use Sequel.~ to negate expressions:
-  Artist.where(Sequel.~(id: 5))
-  # SELECT * FROM artists WHERE id != 5
-On Sequel expression objects, you can use ~ to negate them:
-  Artist.where(~Sequel.like(:name, '%J%'))
-  # SELECT * FROM artists WHERE (name NOT LIKE '%J%' ESCAPE '\')
-You can use !~ on Sequel expressions to create negated expressions:
-  Artist.where{id !~ 5}
-  # SELECT * FROM artists WHERE (id != 5)
-=== Removing
-To remove all existing filters, use +unfiltered+:
-  Artist.where(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 +where+, +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+ without an order:
-  Artist.order(:id).reverse
-  # SELECT FROM artists ORDER BY id DESC
-Alternatively, you can provide reverse with the order:
-  Artist.reverse(:id)
-  # SELECT FROM artists ORDER BY id DESC
-To specify a single entry be reversed, <tt>Sequel.desc</tt> can be used:
-  Artist.order(Sequel.desc(:id))
-  # SELECT FROM artists ORDER BY id DESC
-This allows you to easily use both ascending and descending orders:
-  Artist.order(:name, Sequel.desc(:id))
-  # 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
-To select all columns from a given table, provide an argument to
-+select_all+:
-  Artist.select_all(:artists)
-  # SELECT artists.* 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
-You can also call the +offset+ method separately:
-  Artist.limit(5).offset(10)
-  # SELECT * FROM artists LIMIT 5 OFFSET 10
-Either of these would return the 11th through 15th records in the original
-dataset.
-To remove a limit and offset 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
-If you want to add a column to the end of the existing grouping columns:
-  Album.group(:artist_id).group_append(:name)
-  # SELECT * FROM albums GROUP BY artist_id, name
-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.
-If you want to select and group on the same columns, you can use +select_group+:
-  Album.select_group(:artist_id)
-  # SELECT artist_id FROM albums GROUP BY artist_id
-Usually you would add a +select_append+ call after that, to add some sort of
-aggregation:
-  Album.select_group(:artist_id).select_append{sum(num_tracks).as(tracks)}
-  # SELECT artist_id, sum(num_tracks) AS tracks FROM albums GROUP BY 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.function.* >= 10}
-  # SELECT artist_id, count(*) AS count FROM albums
-  # 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.function.* >= 10}.
-   where(:name.like('A%')).unfiltered
-  # SELECT artist_id, count(*) AS count FROM albums GROUP BY artist_id
-== Joins
-Sequel has support for many different SQL join types.
-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 dataset, in which case a subselect is used:
-  Album.join(Artist.where{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 last table joined (or the first
-table in the dataset if there hasn't been a previous join):
-  Album.join(:artists, id: :artist_id)
-  # SELECT * FROM albums
-  # INNER JOIN artists ON (artists.id = albums.artist_id)
-Note how the +id+ 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: Sequel[: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.
-By default, Sequel only qualifies unqualified symbols in the conditions.  However,
-You can provide an options hash with a <tt>qualify: :deep</tt> option to do a deep
-qualification, which can qualify subexpressions.  For example, let's say you are doing
-a JOIN using case insensitive string comparison:
-  Album.join(:artists, {Sequel.function(:lower, :name) =>
-                        Sequel.function(:lower, :artist_name)},
-             qualify: :deep)
-  # SELECT * FROM albums INNER JOIN artists
-  #  ON (lower(artists.name) = lower(albums.artist_name))
-Note how the arguments to lower were qualified correctly in both cases.
-==== 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, assuming the column name is the same 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|
-    Sequel[j][:name] < Sequel[lj][:name]
-  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 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 the model plugins that ships with Sequel 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 for the query 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
-Note that if you specify the dataset using custom SQL, you can still call the dataset
-modification methods, but in many cases they will appear to have no affect:
-  DB["SELECT * FROM artists"].select(:name).order(:id)
-  # SELECT * FROM artists
-You can use the implicit_subquery extension to automatically wrap queries that use
-custom SQL in subqueries if a method is called that would modify the SQL:
-  DB.extension :implicit_subquery
-  DB["SELECT * FROM artists"].select(:name).order(:id)
-  # SELECT name FROM (SELECT * FROM artists) AS t1 ORDER BY id"
-If you must drop down to using custom SQL, it's recommended that you only do so for
-specific parts of a query.  For example, if the reason you are using custom SQL is
-to use a custom operator in the database in the SELECT clause:
-  DB["SELECT name, (foo !@# ?) AS baz FROM artists", 'bar']
-it's better to use Sequel's DSL, and use a literal string for the custom operator:
-  DB[:artists].select(:name, Sequel.lit("(foo !@# ?)", 'bar').as(:baz))
-That way Sequel's method chaining still works, and it increases Sequel's ability to
-introspect the code.
-== 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.where(id: 0).empty?
-  # SELECT 1 FROM albums WHERE (id = 0) LIMIT 1
-  # => true
-  Album.where(Sequel.like(:name, 'R%')).empty?
-  # SELECT 1 FROM albums WHERE (name LIKE 'R%' ESCAPE '\') 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
-If you pass an expression to count, it will return the number of records where
-that expression in not NULL:
-  Album.count(:artist_id)
-  # SELECT count(artist_id) AS count FROM albums LIMIT 1
-  # => 1
-The other methods take a column argument and call the aggregate function with
-the argument:
-  Album.sum(:id)
-  # SELECT sum(id) AS sum FROM albums LIMIT 1
-  # => 3
-  Album.avg(:id)
-  # SELECT avg(id) AS avg FROM albums LIMIT 1
-  # => 1.5
-  Album.min(:id)
-  # SELECT min(id) AS min FROM albums LIMIT 1
-  # => 1
-  Album.max(:id)
-  # SELECT max(id) AS max FROM albums LIMIT 1
-  # => 2