sequel 4.49.0 → 5.0.0

data/doc/sql.rdoc

@@ -22,7 +22,7 @@ For SELECT queries, you should probably use <tt>Database#fetch</tt> with a strin
 
 You can also use named placeholders by starting the placeholder with a colon, and using a hash for the argument:
 
-  DB.fetch("SELECT * FROM albums WHERE name LIKE :pattern", :pattern=>'A%') do |row|
+  DB.fetch("SELECT * FROM albums WHERE name LIKE :pattern", pattern: 'A%') do |row|
     puts row[:name]
   end
 
@@ -121,21 +121,15 @@ As you can see, Sequel quotes identifiers by default.  Depending on your databas
 
   :column # "COLUMN" on some databases
 
-A plain symbol is usually treated as an unqualified identifier.  However, if you are using multiple tables in a query, and you want to reference a column in one of the tables that has the same name as a column in another one of the tables, you need to qualify that reference.  There are two main ways in Sequel to do that.  The first is implicit qualification inside the symbol, using the double underscore:
-
-  :table__column # "table"."column"
-
-This works by default, but it is possible to turn off by setting <tt>Sequel.split_symbols = false</tt>.
-
-Note that you can't use a period to separate them:
+A plain symbol is usually treated as an unqualified identifier.  However, if you are using multiple tables in a query, and you want to reference a column in one of the tables that has the same name as a column in another one of the tables, you need to qualify that reference.  Note that you can't use a period to separate them: 
 
   :table.column # calls the column method on the symbol
 
 Also note that specifying the period inside the symbol doesn't work if you are quoting identifiers:
 
-  :"table.column" # "table.column"
+  :"table.column" # "table.column" instead of "table"."column"
 
-The second way is to explicitly create a qualified identifier either by using <tt>Sequel.[]</tt> to create an identifier and call <tt>[]</tt> or +qualify+ on that, or by using the <tt>Sequel.qualify</tt> method with the table and column symbols:
+There are a few different Sequel methods for creating qualified identifier objects.  The recommended way is to explicitly create a qualified identifier by using <tt>Sequel.[]</tt> to create an identifier and call <tt>[]</tt> or +qualify+ on that, or by using the <tt>Sequel.qualify</tt> method with the table and column symbols:
 
   Sequel[:table][:column]         # "table"."column"
   Sequel[:column].qualify(:table) # "table"."column"
@@ -148,6 +142,7 @@ Another way to generate identifiers is to use Sequel's {virtual row support}[rdo
 
 You can also use the symbol_aref extension for creating qualified identifiers:
 
+  Sequel.extension :symbol_aref
   :table[:column] # "table"."column"
 
 === Numbers
@@ -173,24 +168,16 @@ In general, Ruby strings map directly to SQL strings:
 
 === Aliasing
 
-Sequel allows for implicit aliasing in column symbols using the triple underscore:
-
-  :column___alias # "column" AS "alias"
-
-You can combine this with implicit qualification:
-
-  :table__column___alias # "table"."column" AS "alias"
-
-As with creating qualified identifiers via a double underscore, this works by default, but it is possible to turn off by setting <tt>Sequel.split_symbols = false</tt>.
-
-You can also use the <tt>Sequel.as</tt> method to create an alias, and the +as+ method on most Sequel-specific expression objects:
+You can use the <tt>Sequel.as</tt> method to create an alias, and the +as+ method on most Sequel-specific expression objects:
 
   Sequel.as(:column, :alias)                 # "column" AS "alias"
   Sequel[:column].as(:alias)                 # "column" AS "alias"
   Sequel[:table][:column].as(:alias)         # "table"."column" AS "alias"
+  (Sequel[:column] + 1).as(:alias)           # ("column" + 1) AS "alias"
 
 You can also use the symbol_as extension for creating aliased identifiers:
 
+  Sequel.extension :symbol_as
   :column.as(:alias) # "column" AS "alias"
 
 If you want to use a derived column list, you can provide an array of column aliases:
@@ -215,11 +202,11 @@ Aggregate functions work the same way as normal functions, since they share the
 
   Sequel.function(:sum, :column) # sum(column)
 
-To use the DISTINCT modifier to an aggregate function, call the +distinct+ method on the function:
+To use the DISTINCT modifier to an aggregate function, call the +distinct+ method on the function expression, which returns a new function expression:
 
   DB[:albums].select{sum(:column).distinct} # SELECT sum(DISTINCT column) FROM albums
 
-If you want to use the wildcard as the sole argument of the aggregate function, use the * method on the Function:
+If you want to use the wildcard as the sole argument of the aggregate function, use the * method on the function expression:
 
   Sequel.function(:count).* # count(*)
   DB[:albums].select{count.function.*} # SELECT count(*) FROM albums
@@ -228,10 +215,10 @@ Note that Sequel provides helper methods for aggregate functions such as +count+
 
 === Window Functions
 
-If the database supports window functions, Sequel can handle them by calling the +over+ method on a Function:
+If the database supports window functions, Sequel can handle them by calling the +over+ method on a function expression:
 
-  DB[:albums].select{function.function.over}
-  # SELECT function() OVER () FROM albums
+  DB[:albums].select{row_number.function.over}
+  # SELECT row_number() OVER () FROM albums
 
   DB[:albums].select{count.function.*.over}
   # SELECT count(*) OVER () FROM albums
@@ -244,12 +231,12 @@ If the database supports window functions, Sequel can handle them by calling the
 
 === Schema Qualified Functions
 
-If the database supports schema qualified functions, Sequel can handle them by calling the +function+ method on a QuailfiedIdentifier:
+If the database supports schema qualified functions, Sequel can handle them by calling the +function+ method on a qualified identifier:
 
   DB[:albums].select{schema[:function].function}
   # SELECT schema.function() FROM albums
   
-  DB[:albums].select{schema[:function].function(col, 2, "a")}
+  DB[:albums].select{schema[:function].function(:col, 2, "a")}
   # SELECT schema.function(col, 2, 'a') FROM albums
 
 === Portable/Emulated Functions
@@ -265,7 +252,7 @@ Some examples are:
 
 Sequel uses hashes to specify equality:
 
-  {:column=>1} # ("column" = 1)
+  {column: 1} # ("column" = 1)
 
 You can also specify this as an array of two element arrays:
 
@@ -279,27 +266,27 @@ For expression objects, you can also use the =~ method:
 
 You can specify a not equals condition by inverting the hash or array of two element arrays using <tt>Sequel.negate</tt> or <tt>Sequel.~</tt>:
 
-  Sequel.negate(:column => 1)   # ("column" != 1)
+  Sequel.negate(column: 1)      # ("column" != 1)
   Sequel.negate([[:column, 1]]) # ("column" != 1)
-  Sequel.~(:column => 1)        # ("column" != 1)
+  Sequel.~(column: 1)           # ("column" != 1)
   Sequel.~([[:column, 1]])      # ("column" != 1)
 
 The difference between the two is that +negate+ only works on hashes and arrays of element arrays, and it negates all entries in the hash or array, while ~ does a general inversion.  This is best shown by an example with multiple entries:
 
-  Sequel.negate(:column => 1, :foo => 2)   # (("column" != 1) AND (foo != 2))
-  Sequel.~(:column => 1, :foo => 2)        # (("column" != 1) OR (foo != 2))
+  Sequel.negate(column: 1, foo: 2)   # (("column" != 1) AND (foo != 2))
+  Sequel.~(column: 1, foo: 2)        # (("column" != 1) OR (foo != 2))
 
 You can also use the ~ method on an equality expression:
 
   where{~(column =~ 1)} # ("column" != 1)
 
-On Ruby 1.9+, you can use the !~ method:
+Or you can use the !~ method:
 
   where{column !~ 1} # ("column" != 1)
 
 The most common need for not equals is in filters, in which case you can use the +exclude+ method:
 
-  DB[:albums].exclude(:column=>1) # SELECT * FROM "albums" WHERE ("column" != 1)
+  DB[:albums].exclude(column: 1) # SELECT * FROM "albums" WHERE ("column" != 1)
 
 Note that +exclude+ does a generalized inversion, similar to <tt>Sequel.~</tt>.
 
@@ -307,19 +294,19 @@ Note that +exclude+ does a generalized inversion, similar to <tt>Sequel.~</tt>.
 
 Sequel also uses hashes to specify inclusion, and inversions of those hashes to specify exclusion:
 
-  {:column=>[1, 2, 3]} # ("column" IN (1, 2, 3))
-  Sequel.~(:column=>[1, 2, 3]) # ("column" NOT IN (1, 2, 3))
+  {column: [1, 2, 3]} # ("column" IN (1, 2, 3))
+  Sequel.~(column: [1, 2, 3]) # ("column" NOT IN (1, 2, 3))
 
 As you may have guessed, Sequel switches from an = to an IN when the hash value is an array.  It also does this for datasets, which easily allows you to test for inclusion and exclusion in a subselect:
 
-  {:column=>DB[:albums].select(:id)} # ("column" IN (SELECT "id" FROM "albums"))
-  Sequel.~(:column=>DB[:albums].select(:id)) # ("column" NOT IN (SELECT "id" FROM "albums"))
+  {column: DB[:albums].select(:id)} # ("column" IN (SELECT "id" FROM "albums"))
+  Sequel.~(column: DB[:albums].select(:id)) # ("column" NOT IN (SELECT "id" FROM "albums"))
 
 Similar to =, you can also use =~ with expressions for inclusion:
 
   where{column =~ [1, 2, 3]} # ("column" IN (1, 2, 3))
 
-and on Ruby 1.9, !~ for exclusion:
+and !~ for exclusion:
 
   where{column !~ [1, 2, 3]} # ("column" NOT IN (1, 2, 3))
 
@@ -331,17 +318,17 @@ Sequel also supports the SQL EXISTS operator using <tt>Dataset#exists</tt>:
 
 Hashes in Sequel use IS if the value is +true+, +false+, or +nil+:
 
-  {:column=>nil} # ("column" IS NULL)
-  {:column=>true} # ("column" IS TRUE)
-  {:column=>false} # ("column" IS FALSE)
+  {column: nil}   # ("column" IS NULL)
+  {column: true}  # ("column" IS TRUE)
+  {column: false} # ("column" IS FALSE)
 
 Negation works the same way as it does for equality and inclusion:
 
-  Sequel.~(:column=>nil) # ("column" IS NOT NULL)
-  Sequel.~(:column=>true) # ("column" IS NOT TRUE)
-  Sequel.~(:column=>false) # ("column" IS NOT FALSE)
+  Sequel.~(column: nil)   # ("column" IS NOT NULL)
+  Sequel.~(column: true)  # ("column" IS NOT TRUE)
+  Sequel.~(column: false) # ("column" IS NOT FALSE)
 
-Likewise, =~ works for identity (and Ruby 1.9, !~ for negative identity):
+Likewise, =~ works for identity and !~ for negative identity on expressions:
 
   where{column =~ nil} # ("column" IS NULL)
   where{column !~ nil} # ("column" IS NOT NULL)
@@ -354,7 +341,7 @@ Sequel's general inversion operator is ~, which works on symbols and most Sequel
 
 Note that ~ will actually apply the inversion operation to the underlying object, which is why
   
-  Sequel.~(:column=>1)
+  Sequel.~(column: 1)
 
 produces <tt>(column != 1)</tt> instead of <tt>NOT (column = 1)</tt>.
 
@@ -367,7 +354,7 @@ Sequel defines the inequality operators directly on most Sequel-specific express
   Sequel.function(:func) >= 1 # (func() >= 1)
   Sequel.function(:func, :column) <= 1 # (func("column") <= 1)
 
-If you want to use them on a symbol, you should call <tt>Sequel.[]</tt> with the symbol:
+If you want to use them on a symbol, you should call <tt>Sequel.[]</tt> with the symbol to get an expression object:
 
   Sequel[:column] > 1 # ("column" > 1)
 
@@ -403,7 +390,7 @@ Note that since Sequel implements support for Ruby's coercion protocol, the foll
 Sequel defines the & and | methods on most Sequel-specific expression objects to handle AND and OR:
 
   Sequel[:column1] & :column2 # ("column1" AND "column2")
-  Sequel[:column1=>1] | {:column2=>2} # (("column1" = 1) OR ("column2" = 2))
+  Sequel[{column1: 1}] | {column2: 2} # (("column1" = 1) OR ("column2" = 2))
   (Sequel.function(:func) > 1) & :column3 # ((func() > 1) AND "column3")
 
 Note the use of parentheses in the last statement.  If you omit them, you won't get what you expect.
@@ -418,28 +405,28 @@ is parsed as:
 You can also use the <tt>Sequel.&</tt> and <tt>Sequel.|</tt> methods:
 
   Sequel.&(:column1, :column2) # ("column1" AND "column2")
-  Sequel.|({:column1=>1}, {:column2=>2}) # (("column1" = 1) OR ("column2" = 2))
+  Sequel.|({column1: 1}, {column2: 2}) # (("column1" = 1) OR ("column2" = 2))
 
 You can use hashes and arrays of two element arrays to specify AND and OR with equality conditions:
 
-  {:column1=>1, :column2=>2} # (("column1" = 1) AND ("column2" = 2))
+  {column1: 1, column2: 2} # (("column1" = 1) AND ("column2" = 2))
   [[:column1, 1], [:column2, 2]] # (("column1" = 1) AND ("column2" = 2))
 
 As you can see, these literalize with ANDs by default.  You can use the <tt>Sequel.or</tt> method to use OR instead:
 
-  Sequel.or(:column1=>1, :column2=>2) # (("column1" = 1) OR ("column2" = 2))
+  Sequel.or(column1: 1, column2: 2) # (("column1" = 1) OR ("column2" = 2))
 
 You've already seen the <tt>Sequel.negate</tt> method, which will use ANDs if multiple entries are used:
 
-  Sequel.negate(:column1=>1, :column2=>2) # (("column1" != 1) AND ("column2" != 2))
+  Sequel.negate(column1: 1, column2: 2) # (("column1" != 1) AND ("column2" != 2))
  
 To negate while using ORs, the <tt>Sequel.~</tt> operator can be used:
 
-  Sequel.~(:column1=>1, :column2=>2) # (("column1" != 1) OR ("column2" != 2))
+  Sequel.~(column1: 1, column2: 2) # (("column1" != 1) OR ("column2" != 2))
 
 Note again that <tt>Dataset#exclude</tt> uses ~, not +negate+:
 
-  DB[:albums].exclude(:column1=>1, :column2=>2) # SELECT * FROM "albums" WHERE (("column" != 1) OR ("column2" != 2))
+  DB[:albums].exclude(column1: 1, column2: 2) # SELECT * FROM "albums" WHERE (("column" != 1) OR ("column2" != 2))
 
 === Casts
 
@@ -521,8 +508,8 @@ Sequel also supports SQL regular expressions on MySQL and PostgreSQL.  You can u
 
   Sequel.like(:name, /^A/) # ("name" ~ '^A')
   ~Sequel.ilike(:name, /^A/) # ("name" !~* '^A')
-  {:name=>/^A/i} # ("name" ~* '^A')
-  Sequel.~(:name=>/^A/) # ("name" !~ '^A')
+  {name: /^A/i} # ("name" ~* '^A')
+  Sequel.~(name: /^A/) # ("name" !~ '^A')
 
 Note that using +ilike+ with a regular expression will always make the regexp case insensitive.  If you use +like+ or the hash with regexp value, it will only be case insensitive if the Regexp itself is case insensitive.
 
@@ -545,21 +532,22 @@ On some databases, you can specify null ordering:
 
 === All Columns (.*)
 
-To select all columns in a table, Sequel supports the * method on identifiers without an argument:
+To select all columns in a table, Sequel supports the * method on identifiers and qualified without an argument:
 
-  Sequel[:table].* # "table".*
+  Sequel[:table].*          # "table".*
+  Sequel[:schema][:table].* # "schema"."table".*
 
 === CASE statements
 
-Sequel allows the easy production of SQL CASE statements using the <tt>Sequel.case</tt> method.  The first argument is a hash or array of two element arrays representing the conditions, the second argument is the default value (ELSE).  The keys of the hash (or first element in each array) is the WHEN condition, and the values of the hash (or second element in each array) is the THEN result.  Here are some examples:
+Sequel supports SQL CASE statements using the <tt>Sequel.case</tt> method.  The first argument is a hash or array of two element arrays representing the conditions, the second argument is the default value (ELSE).  The keys of the hash (or first element in each array) is the WHEN condition, and the values of the hash (or second element in each array) is the THEN result.  Here are some examples:
 
-  Sequel.case({:column=>1}, 0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
-  Sequel.case([[column, 1]], 0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
-  Sequel.case({{:column=>nil}=>1}, 0) # (CASE WHEN (column IS NULL) THEN 1 ELSE 0 END)
+  Sequel.case({column: 1}, 0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
+  Sequel.case([[:column, 1]], 0) # (CASE WHEN "column" THEN 1 ELSE 0 END)
+  Sequel.case({{column: nil}=>1}, 0) # (CASE WHEN (column IS NULL) THEN 1 ELSE 0 END)
 
 If the hash or array has multiple arguments, multiple WHEN clauses are used:
 
-  Sequel.case({:c=>1, :d=>2}, 0) # (CASE WHEN "c" THEN 1 WHEN "d" THEN 2 ELSE 0 END)
+  Sequel.case({c: 1, d: 2}, 0) # (CASE WHEN "c" THEN 1 WHEN "d" THEN 2 ELSE 0 END)
   Sequel.case([[:c, 1], [:d, 2]], 0) # (CASE WHEN "c" THEN 1 WHEN "d" THEN 2 ELSE 0 END)
 
 If you provide a 3rd argument to <tt>Sequel.case</tt>, it goes between CASE and WHEN:

data/doc/testing.rdoc

@@ -156,13 +156,11 @@ SEQUEL_COLUMNS_INTROSPECTION :: Use the columns_introspection extension when run
 SEQUEL_CONNECTION_VALIDATOR :: Use the connection validator extension when running the specs
 SEQUEL_DUPLICATE_COLUMNS_HANDLER :: Use the duplicate columns handler extension with value given when running the specs
 SEQUEL_ERROR_SQL :: Use the error_sql extension when running the specs
-SEQUEL_FREEZE_DATASETS :: Use the freeze_datasets extension when running the specs
 SEQUEL_FREEZE_DATABASE :: Freeze the database before running the integration specs
 SEQUEL_IDENTIFIER_MANGLING :: Use the identifier_mangling extension when running the specs
-SEQUEL_MODEL_PREPARED_STATEMENTS :: Use the prepared_statements and prepared_statements_associations plugins when running the specs
-SEQUEL_NO_AUTO_LITERAL_STRINGS :: Use the no_auto_string_literals extension when running the specs
+SEQUEL_MODEL_PREPARED_STATEMENTS :: Use the prepared_statements plugin when running the specs
 SEQUEL_NO_CACHE_ASSOCIATIONS :: Don't cache association metadata when running the specs
 SEQUEL_NO_CHECK_SQLS :: Don't check for specific SQL syntax when running the specs
+SEQUEL_CHECK_PENDING :: Try running all specs (note, can cause lockups for some adapters), and raise errors for skipped specs that don't fail
 SEQUEL_NO_PENDING :: Don't skip any specs, try running all specs (note, can cause lockups for some adapters)
-SEQUEL_NO_SPLIT_SYMBOLS :: Turn off symbol splitting when running the specs
-SKIPPED_TEST_WARN :: Warn when skipping any tests because libraries aren't available
+SEQUEL_SPLIT_SYMBOLS :: Turn on symbol splitting when running the adapter and integration specs

data/doc/thread_safety.rdoc

@@ -1,10 +1,10 @@
 = Thread Safety
 
-Most Sequel usage (and all common Sequel usage) is thread safe by default.  Specifically, multiple threads can operate on Database instances, Dataset instances, and Model classes concurrently without problems.  In general, Database instance and Model classes are not modified after application startup, and modifying Dataset instances returns modified copies of the dataset instead of mutating it.
+Most Sequel usage (and all common Sequel usage) is thread safe by default.  Specifically, multiple threads can operate on Database instances, Dataset instances, and Model classes concurrently without problems.  In general, Database instance and Model classes are not modified after application startup, and Dataset instances are always frozen.
 
 == Connection Pool
 
-In order to allow multiple threads to operate on the same database at the same time, Sequel uses a connection pool.  The connection pool is designed so that a thread uses a connection for the minimum amount of time, returning the connection to the pool as soon as it is done using the connection.  If a thread requests a connection and the pool does not have an available connection, a new connection will be created.  If the maximum number of connections in the pool has already been reached, the thread will block until a connection is available or the connection pool timeout has elapsed (in which case a PoolTimeout error will be raised).
+In order to allow multiple threads to operate on the same database at the same time, Sequel uses a connection pool.  The connection pool is designed so that a thread uses a connection for the minimum amount of time, returning the connection to the pool as soon as it is done using the connection.  If a thread requests a connection and the pool does not have an available connection, a new connection will be created.  If the maximum number of connections in the pool has already been reached, the thread will block until a connection is available or the connection pool timeout has elapsed (in which case a Sequel::PoolTimeout error will be raised).
 
 == Exceptions
 
@@ -13,5 +13,3 @@ This is a small list of things that are specifically non thread-safe.  This is n
 1) Model instances: Model instances are not thread-safe unless they are frozen first.  Multiple threads should not operate on an unfrozen model instance concurrently.
 
 2) Model class modifications: Model class modifications, such as adding associations and loading plugins, are not designed to be thread safe.  You should not modify a class in one thread if any other thread can concurrently access it.  Model subclassing is designed to be thread-safe, so you create a model subclass in a thread and modify it safely.
-
-3) Dataset mutation methods: Dataset mutation methods are not thread safe, you should not call them on datasets that could be accessed by other threads.  It is safe to clone the dataset first inside a thread and call mutation methods on the cloned dataset.

data/doc/transactions.rdoc

@@ -3,6 +3,7 @@
 Sequel uses autocommit mode by default for all of its database adapters, so in general in Sequel if you want to use database transactions, you need to be explicit about it.  There are a few cases where transactions are used implicitly by default:
 
 * Dataset#import to insert many records at once
+* Dataset#paged_each to iterate over large datasets in batches
 * Model#save
 * Model#destroy
 * Migrations if the database supports transactional schema
@@ -35,16 +36,16 @@ If any other exception is raised, the transaction is rolled back, and the except
   end # ROLLBACK
   # ArgumentError raised
 
-If you want Sequel::Rollback exceptions to be reraised, use the <tt>:rollback => :reraise</tt> option:
+If you want Sequel::Rollback exceptions to be reraised, use the <tt>rollback: :reraise</tt> option:
 
-  DB.transaction(:rollback => :reraise) do # BEGIN
+  DB.transaction(rollback: :reraise) do # BEGIN
     raise Sequel::Rollback
   end # ROLLBACK
   # Sequel::Rollback raised
 
-If you always want to rollback (useful for testing), use the <tt>:rollback => :always</tt> option:
+If you always want to rollback (useful for testing), use the <tt>rollback: :always</tt> option:
 
-  DB.transaction(:rollback => :always) do # BEGIN
+  DB.transaction(rollback: :always) do # BEGIN
     DB[:foo].insert(1) # INSERT
   end # ROLLBACK
   # no exception raised
@@ -86,17 +87,17 @@ You can nest calls to transaction, which by default just reuses the existing tra
     end
   end # COMMIT
 
-You can use the <tt>:savepoint => true</tt> option in the inner transaction to explicitly use a savepoint (if the database supports it):
+You can use the <tt>savepoint: true</tt> option in the inner transaction to explicitly use a savepoint (if the database supports it):
 
   DB.transaction do # BEGIN
-    DB.transaction(:savepoint => true) do # SAVEPOINT
+    DB.transaction(savepoint: true) do # SAVEPOINT
       DB[:foo].insert(1) # INSERT
     end # RELEASE SAVEPOINT
   end # COMMIT
 
-You can use the <tt>:auto_savepoint => true</tt> option in the outer transaction to explicitly use a savepoint in the inner transaction (if the database supports it):
+You can use the <tt>auto_savepoint: true</tt> option in the outer transaction to explicitly use a savepoint in the inner transaction (if the database supports it):
 
-  DB.transaction(:auto_savepoint => true) do # BEGIN
+  DB.transaction(auto_savepoint: true) do # BEGIN
     DB.transaction do # SAVEPOINT
       DB[:foo].insert(1) # INSERT
     end # RELEASE SAVEPOINT
@@ -105,7 +106,7 @@ You can use the <tt>:auto_savepoint => true</tt> option in the outer transaction
 If a Sequel::Rollback exception is raised inside the savepoint block, it will only rollback to the savepoint:
 
   DB.transaction do # BEGIN
-    DB.transaction(:savepoint => true) do # SAVEPOINT
+    DB.transaction(savepoint: true) do # SAVEPOINT
       raise Sequel::Rollback
     end # ROLLBACK TO SAVEPOINT
     # no exception raised
@@ -114,7 +115,7 @@ If a Sequel::Rollback exception is raised inside the savepoint block, it will on
 Other exceptions, unless rescued inside the outer transaction block, will rollback the savepoint and the outer transactions, since they are reraised by the transaction code:
 
   DB.transaction do # BEGIN
-    DB.transaction(:savepoint => true) do # SAVEPOINT
+    DB.transaction(savepoint: true) do # SAVEPOINT
       raise ArgumentError
     end # ROLLBACK TO SAVEPOINT
   end # ROLLBACK
@@ -126,7 +127,7 @@ Sequel supports database prepared transactions on PostgreSQL, MySQL, and H2.  Wi
 
 To use prepared transactions in Sequel, you provide a string as the value of the :prepare option:
 
-  DB.transaction(:prepare => 'foo') do # BEGIN
+  DB.transaction(prepare: 'foo') do # BEGIN
     DB[:foo].insert(1) # INSERT
   end # PREPARE TRANSACTION 'foo'
    
@@ -140,9 +141,9 @@ or roll the prepared transaction back:
 
 == Transaction Isolation Levels
 
-The SQL standard supports 4 isolation levels: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, and SERIALIZABLE.  Not all databases implement the levels as specified in the standard (or implement the levels at all), but on most databases, you can specify which transaction isolation level you want to use via the :isolation option to <tt>Database#transaction</tt>.  The isolation level is specified as one of the following symbols: :uncommitted, :committed, :repeatable, and :serializable.  Using this option make Sequel use the correct transaction isolation syntax for your database:
+The SQL standard supports 4 isolation levels: READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, and SERIALIZABLE.  Not all databases implement the levels as specified in the standard (or implement the levels at all), but on most databases, you can specify which transaction isolation level you want to use via the :isolation option to <tt>Database#transaction</tt>.  The isolation level is specified as one of the following symbols: :uncommitted, :committed, :repeatable, and :serializable.  Using this option makes Sequel use the correct transaction isolation syntax for your database:
 
-  DB.transaction(:isolation => :serializable) do # BEGIN
+  DB.transaction(isolation: :serializable) do # BEGIN
     # SET TRANSACTION ISOLATION LEVEL SERIALIZABLE
     DB[:foo].insert(1) # INSERT
   end # COMMIT
@@ -151,8 +152,8 @@ The SQL standard supports 4 isolation levels: READ UNCOMMITTED, READ COMMITTED,
 
 Sequel offers the ability to automatically restart transactions if specific types of errors are detected.  For example, if you want to automatically restart a transaction if a serialization failure is detected:
 
-  DB.transaction(:isolation => :serializable, :retry_on=>[Sequel::SerializationFailure]) do
-    ModelClass.find_or_create(:name=>'Foo')
+  DB.transaction(isolation: :serializable, retry_on: [Sequel::SerializationFailure]) do
+    ModelClass.find_or_create(name: 'Foo')
   end
 
 At the serializable transaction isolation level, find_or_create may raises a Sequel::SerializationFailure exception if multiple threads simultaneously run that code.  With the :retry_on option set, the transaction will be automatically retried until it succeeds.
@@ -161,9 +162,9 @@ Note that automatic retrying should not be used unless the entire transaction
 block is idempotent, as otherwise it can cause non-idempotent
 behavior to execute multiple times.  For example, with the following code:
 
-  DB.transaction(:isolation => :serializable, :retry_on=>[Sequel::SerializationFailure]) do
+  DB.transaction(isolation: :serializable, retry_on: [Sequel::SerializationFailure]) do
     logger.info 'Ensuring existence of ModelClass with name Foo'
-    ModelClass.find_or_create(:name=>'Foo')
+    ModelClass.find_or_create(name: 'Foo')
   end
 
 The logger.info method will be called multiple times if there is a serialization failure.

data/doc/validations.rdoc

@@ -13,7 +13,7 @@ types of validations to your models.
 
 Validations are primarily useful for associating error messages to display to the user
 with specific attributes on the model.  It is also possible to use them to enforce
-data integrity for model instances, but that's not a recommended use unless
+data integrity for model instances, but that's not recommended unless
 the only way to modify the database is through model instances, or you have
 complex data integrity requirements that aren't possible to specify via
 database-level constraints.
@@ -30,19 +30,17 @@ be setting the size of the varchar column to 255, and using a CHECK constraint
 to ensure that all values have at least two characters.
 
 Unfortunately, sometimes there are situations where that is not possible.  For
-example, if you are using MySQL and don't have control over the database configuration,
-it's possible that if you attempt to insert a string with 300 characters into a
-varchar(255) field, then MySQL may just silently truncate it for you, instead of
-raising an error.  In that case, it may be necessary to use a model validation
+example, if you don't have control over the schema and cannot add constraints,
+or you are using MySQL (which doesn't support CHECK constraints), it may be necessary to use a model validation
 to enforce the database integrity.
 
-Also, in some cases you may have data integrity requirements that are difficult to
+In some cases you may have data integrity requirements that are difficult to
 enforce via database constraints, especially if you are targetting multiple
 database types.
 
-Finally, validations are generally easier to write than database constraints,
+Validations are generally easier to write than database constraints,
 so if data integrity isn't of great importance, using validations to provide minimal
-data integrity is probably fine.
+data integrity may be acceptable.
 
 == Usage
 
@@ -71,11 +69,12 @@ saving of model objects passes through the +save+ method.  This means that all
 saving of model objects goes through the validation process.
 
 The only way to skip validations when saving a model object is to pass the
-<tt>:validate => false</tt> option to +save+. If you use that option, +save+ will
+<tt>validate: false</tt> option to +save+. If you use that option, +save+ will
 not attempt to validate the object before saving it.  
 
 Note that it's always possible to update the instance's database row without using
-+save+, by using a dataset to update it.  Validations will only be run if you call
++save+, by using a Sequel dataset to update it, or updating it via another program.
+Validations will only be run if you call
 +save+ on the model object, or another model method that calls +save+.  For example,
 the +create+ class method instantiates a new instance of the model, and then calls
 +save+, so it validates the object.  However, the +insert+ class method is a dataset
@@ -96,8 +95,8 @@ model instance is valid.  This method should not be overridden.  Instead, the
   end
 
   Album.new.valid? # false
-  Album.new(:name=>'').valid? # false
-  Album.new(:name=>'RF').valid? # true
+  Album.new(name: '').valid? # false
+  Album.new(name: 'RF').valid? # true
   
 If the <tt>valid?</tt> method returns false, you can call the +errors+ method to
 get an instance of <tt>Sequel::Model::Errors</tt> describing the errors on the model:
@@ -135,7 +134,7 @@ specifying validations like this:
     def validate
       super
       errors.add(:name, 'cannot be empty') if !name || name.empty?
-      errors.add(:name, 'is already taken') if name && new? && Album[:name=>name]
+      errors.add(:name, 'is already taken') if name && new? && Album[{name: name}]
       errors.add(:website, 'cannot be empty') if !website || website.empty?
       errors.add(:website, 'is not a valid URL') unless website =~ /\Ahttps?:\/\//
     end
@@ -149,7 +148,7 @@ You can call simple methods such as:
       super
       validates_presence [:name, :website]
       validates_unique :name
-      validates_format /\Ahttps?:\/\//, :website, :message=>'is not a valid URL'
+      validates_format /\Ahttps?:\/\//, :website, message: 'is not a valid URL'
     end
   end
 
@@ -168,7 +167,7 @@ The following methods are provided by +validation_helpers+:
 
 === +validates_presence+
 
-This is probably the most commonly used helper method, which checks if the specified attributes are not blank.  In general, if an object responds to <tt>blank?</tt>, it calls the method to determine if the object is blank.  Otherwise, nil is considered blank, empty strings or strings that just contain whitespace are blank, and objects that respond to <tt>empty?</tt> and return true are considered blank.  All other objects are considered non-blank for the purposes of +validates_presence+.  This means that +validates_presence+ is safe to use on boolean columns where you want to ensure that either true or false is used, but not NULL.
+This method checks that the specified attributes are not blank.  In general, if an object responds to <tt>blank?</tt>, it calls the method to determine if the object is blank.  Otherwise, nil is considered blank, empty strings or strings that just contain whitespace are blank, and objects that respond to <tt>empty?</tt> and return true are considered blank.  All other objects are considered non-blank for the purposes of +validates_presence+.  This means that +validates_presence+ is safe to use on boolean columns where you want to ensure that either true or false is used, but not NULL.
 
   class Album < Sequel::Model
     def validate
@@ -195,7 +194,7 @@ This is similar to +validates_presence+, but only checks for NULL/nil values, al
 
 === +validates_exact_length+, +validates_min_length+, +validates_max_length+, +validates_length_range+
 
-These methods all deal with ensuring that the length of the specified attribute matches the criteria specified by the first argument to the method.  +validates_exact_length+ is for checking that the length of the attribute is equal to that value, +validates_min_length+ is for checking that the length of the attribute is greater than or equal to that value, +validates_max_length+ is for checking that the length of the attribute is less than or equal to that value, and +validates_length_range+ is for checking that the length of the attribute falls in the value, which should be a range or another object that responds to <tt>include?</tt>.
+These methods all deal with ensuring that the length of the specified attribute matches the criteria specified by the first argument to the method.  +validates_exact_length+ is for checking that the length of the attribute is equal to that value, +validates_min_length+ is for checking that the length of the attribute is greater than or equal to that value, +validates_max_length+ is for checking that the length of the attribute is less than or equal to that value, and +validates_length_range+ is for checking that the length of the attribute falls in the value, which should be a range or an object that responds to <tt>include?</tt>.
  
 
   class Album < Sequel::Model
@@ -257,17 +256,17 @@ These methods check that the specified attributes can be valid integers or valid
 
 === +validates_schema_types+
 
-+validates_schema_types+ uses the database metadata for the model's table to determine which ruby type(s) should be used for the given database type, and calls +validates_type+ with that ruby type.  It's designed to be used with the <tt>raise_on_typecast_failure = false</tt> setting (the default starting in Sequel 4).  <tt>raise_on_typecast_failure = false</tt>, Sequel attempts to typecast values, but silently ignores any errors raised:
++validates_schema_types+ uses the database metadata for the model's table to determine which ruby type(s) should be used for the given database type, and calls +validates_type+ with that ruby type.  It's designed to be used with the default <tt>raise_on_typecast_failure = false</tt> setting, where Sequel will attempt to typecast values, but silently ignore any errors raised:
 
-  Album.raise_on_typecast_failure = false
   album = Album.new
+  album.copies_sold = '1'
+  album.copies_sold # => 1
   album.copies_sold = 'banana'
   album.copies_sold # => 'banana'
 
-When <tt>raise_on_typecast_failure = false</tt>, you can call +validates_schema_types+ with all columns.  If any of those columns has a value that doesn't match the type that Sequel expects, it's probably because the column was set and Sequel was not able to typecast it correctly, which means it probably isn't valid.  For example, let's say that you want to check that a couple of columns contain valid dates:
+In general, you can call +validates_schema_types+ with all columns.  If any of those columns has a value that doesn't match the type that Sequel expects, it's probably because the column was set and Sequel was not able to typecast it correctly, which means it probably isn't valid.  For example, let's say that you want to check that a couple of columns contain valid dates:
 
   class Album < Sequel::Model
-    self.raise_on_typecast_failure = false
     def validate
       super
       validates_schema_types [:release_date, :record_date]
@@ -282,7 +281,7 @@ When <tt>raise_on_typecast_failure = false</tt>, you can call +validates_schema_
   album.valid? # => false
   album.errors # => {:release_date=>["is not a valid date"]}
 
-For web applications, you usually want the <tt>raise_on_typecast_failure = false</tt> setting, so that you can accept all of the input without raising an error, and then present the user with all error messages.  Without the setting, if the user submits any invalid data, Sequel will immediately raise an error.  +validates_schema_types+ is helpful because it allows you to check for typecasting errors on columns, and provides a good default error message stating that the attribute is not of the expected type.
+For web applications, you usually want the default setting, so that you can accept all of the input without raising an error, and then present the user with all error messages.  If <tt>raise_on_typecast_failure = true</tt> is set and the user submits any invalid data, Sequel will immediately raise an error.  +validates_schema_types+ is helpful because it allows you to check for typecasting errors on columns, and provides a good default error message stating that the attribute is not of the expected type.
 
 === +validates_unique+
 
@@ -310,7 +309,7 @@ You can also include an options hash as the last argument.  Unlike the other val
 
 :dataset :: The base dataset to use for the unique query, defaults to the model's dataset
 :message :: The message to use
-:only_if_modified :: Only check the uniqueness if the object is new or one of the columns has been modified.
+:only_if_modified :: Only check the uniqueness if the object is new or one of the columns has been modified (true by default).
 :where :: A callable object where call takes three arguments, a dataset,
           the current object, and an array of columns, and should return
           a modified dataset that is filtered to include only rows with
@@ -323,17 +322,17 @@ You can also include an options hash as the last argument.  Unlike the other val
 
 == +validation_helpers+ Options
 
-All +validation_helpers+ methods except +validates_unique+ accept the following options:
+All other +validation_helpers+ methods accept the following options:
 
 === <tt>:message</tt>
 
-The most commonly used option, used to override the default validation message.  Can be either a string or a proc.  If a string, it is used directly.  If a proc, the proc is called and should return a string.  If the validation method takes an argument before the array of attributes, that argument is passed as an argument to the proc. The exception is the +validates_not_string+ method, which doesn't take an argument, but passes the schema type symbol as the argument to the proc.
+The <tt>:message</tt> option overrides the default validation error message.  Can be either a string or a proc.  If a string, it is used directly.  If a proc, the proc is called and should return a string.  If the validation method takes an argument before the array of attributes, that argument is passed as an argument to the proc.
 
   class Album < Sequel::Model
     def validate
       super
-      validates_presence :copies_sold, :message=>'was not given'
-      validates_min_length 3, :name, :message=>proc{|s| "should be more than #{s} characters"}
+      validates_presence :copies_sold, message: 'was not given'
+      validates_min_length 3, :name, message: lambda{|s| "should be more than #{s} characters"}
     end
   end
 
@@ -345,7 +344,7 @@ The <tt>:allow_nil</tt> option skips the validation if the attribute value is ni
     def validate
       super
       validates_presence :copies_sold
-      validates_integer :copies_sold, :allow_nil=>true
+      validates_integer :copies_sold, allow_nil: true
     end
   end
 
@@ -358,17 +357,13 @@ The <tt>:allow_blank</tt> is similar to the <tt>:allow_nil</tt> option, but inst
   class Album < Sequel::Model
     def validate
       super
-      validates_format /\Ahttps?:\/\//, :website, :allow_blank=>true
+      validates_format /\Ahttps?:\/\//, :website, allow_blank: true
     end
   end
   a = Album.new
   a.website = ''
   a.valid? # true
 
-If you are going to use <tt>:allow_blank</tt> you should make sure that all objects respond to the blank? method. Sequel ships with an extension that will do this for you:
-
-  Sequel.extension :blank
-
 === <tt>:allow_missing</tt>
 
 The <tt>:allow_missing</tt> option is different from the <tt>:allow_nil</tt> option, in that instead of checking if the attribute value is nil, it checks if the attribute is present in the model instance's values hash.   <tt>:allow_nil</tt> will skip the validation when the attribute is in the values hash and has a nil value and when the attribute is not in the values hash.  <tt>:allow_missing</tt> will only skip the validation when the attribute is not in the values hash.  If the attribute is in the values hash but has a nil value, <tt>:allow_missing</tt> will not skip it.
@@ -428,17 +423,26 @@ These are the default error messages for all of the helper methods in +validatio
 
 == Modifying the Default Options
 
-It's easy to modify the default options used by +validation_helpers+.  All of the default options are stored in the <tt>Sequel::Plugins::ValidationHelpers::DEFAULT_OPTIONS</tt> hash.  So you just need to modify that hash to change the default options.  One way to do that is to use <tt>merge!</tt> to update the hash:
-
-  Sequel::Plugins::ValidationHelpers::DEFAULT_OPTIONS.merge!(
-   :presence=>{:message=>'cannot be empty'},
-   :includes=>{:message=>'invalid option', :allow_nil=>true},
-   :max_length=>{:message=>lambda{|i| "cannot be more than #{i} characters"}, :allow_nil=>true},
-   :format=>{:message=>'contains invalid characters', :allow_nil=>true})
-
-This updates the default messages that will be used for the presence, includes, max_length, and format validations, and sets the default value of the <tt>:allow_nil</tt> option to true for the includes, max_length, and format validations.
+You can override <tt>Sequel::Model#default_validation_helpers_options</tt> private method to override the default settings on a per validation type basis:
 
-You can also override <tt>Sequel::Model#default_validation_helpers_options</tt> private method to override these settings on a per-model or even per-instance basis.
+  class Sequel::Model
+    private
+
+    def default_validation_helpers_options(type)
+      case type
+      when :presence
+        {message: 'cannot be empty'}
+      when :includes
+        {message: 'invalid option', allow_nil: true}
+      when :max_length
+        {message: lambda{|i| "cannot be more than #{i} characters"}, allow_nil: true}
+      when :format
+        {message: 'contains invalid characters', allow_nil: true}
+      else
+        super
+      end
+    end
+  end
 
 == Custom Validations
 
@@ -480,7 +484,7 @@ Let's say you want to add some default validations that apply to all of your mod
       super
       validates_format(/\A[^\x00-\x08\x0e-\x1f\x7f\x81\x8d\x8f\x90\x9d]*\z/n,
        model.string_columns,
-       :message=>"contains invalid characters")
+       message: "contains invalid characters")
     end
   end
 
@@ -547,9 +551,8 @@ Sequel ships with a +constraint_validations+ plugin and extension, that allows y
 
 === +auto_validations+
 
-Autovalidations uses the not null and type information obtained from parsing the database schema, and the unique index information from parsing the database's index information, and automatically setting up not_null, schema_types, and unique validations.  If you don't require customizing validation messages on a per-column basis, it can DRY up a lot of validation code.
+auto_validations uses the not null and type information obtained from parsing the database schema, and the unique index information from parsing the database's index information, and automatically setting up not_null, string length, schema type, and unique validations.  If you don't require customizing validation messages on a per-column basis, it can DRY up a lot of validation code.
 
 === +validation_class_methods+
 
 Sequel ships with the +validation_class_methods+ plugin, which uses class methods instead of instance methods to define validations.  It exists mostly for legacy compatibility, but it is still supported.
-