sequel 3.47.0 → 3.48.0

data/doc/schema_modification.rdoc

@@ -5,14 +5,14 @@ Here's a brief description of the most common schema modification methods:
 == +create_table+
 
 +create_table+ is the most common schema modification method, and it's used for adding new tables
-to the schema.  You provide it with the name of the table as a symbol, as well a block:
+to the database.  You provide it with the name of the table as a symbol, as well a block:
 
   create_table(:artists) do
     primary_key :id
     String :name
   end
 
-Not that if you want a primary key for the table, you need to specify it, Sequel does not create one
+Note that if you want a primary key for the table, you need to specify it, Sequel does not create one
 by default.
 
 === Column types
@@ -521,11 +521,18 @@ ruby class, in which case it gets converted to an appropriate database type.
 
 === +set_column_allow_null+
 
-This changes the NULL or NOT NULL setting of a column:
+This allows you to set the column as allowing NULL values:
 
   alter_table(:albums) do
-    set_column_allow_null :artist_id, true    # NULL
-    set_column_allow_null :copies_sold, false # NOT NULL
+    set_column_allow_null :artist_id
+  end
+
+=== +set_column_not_null+
+
+This allows you to set the column as not allowing NULL values:
+
+  alter_table(:albums) do
+    set_column_not_null :artist_id
   end
 
 == Other +Database+ schema modification methods

data/doc/security.rdoc

@@ -32,7 +32,7 @@ vulnerable to code execution.
 == SQL Injection
 
 The primary security concern in SQL database libraries is SQL injection.
-Because Sequel mostly promotes using ruby objects for SQL concepts instead
+Because Sequel promotes using ruby objects for SQL concepts instead
 of raw SQL, it is less likely to be vulnerable to SQL injection.
 However, because Sequel still makes it easy to use raw SQL, misuse of the
 library can result in SQL injection in your application.
@@ -153,7 +153,7 @@ class methods also call down to the filter methods.
 
 ==== SQL Fragment passed to Dataset#update
 
-Similar to the filter methods, Sequel::Dataset#update (and alias Sequel::Dataset#set) also treat a
+Similar to the filter methods, Sequel::Dataset#update also treats a
 string argument as raw SQL:
 
   DB[:table].update("column = 1")

data/doc/sharding.rdoc

@@ -15,8 +15,7 @@ support is to use the empty hash:
 
   DB=Sequel.connect('postgres://master_server/database', :servers=>{})
 
-In most cases, you are probably not going to want to use an empty hash,
-so you'll want to have entries in the hash.  Keys in the server hash are
+In most cases, you are probably not going to want to use an empty hash.  Keys in the server hash are
 not restricted to type, but the general recommendation is to use a symbol
 unless you have special requirements. Values in the server hash should be
 either hashes or procs that return hashes. These hashes are merged into

data/doc/sql.rdoc

@@ -86,13 +86,13 @@ So you can use Sequel's DSL everywhere you find it helpful, and fallback to lite
 
 == Translating SQL Expressions into Sequel
 
-The rest of this guide assumes you want to use Sequel's DSL to represent your query, that you know how to write the query in SQL, but you aren't sure how to write it in Sequel.
+The rest of this guide assumes you want to use Sequel's DSL to represent your query, that you know how to write the query in SQL, but you aren't sure how to write it in Sequel's DSL.
 
 This section will describe how specific SQL expressions are handled in Sequel.  The next section will discuss how to create queries by using method chaining on datasets.
 
 === <tt>Database#literal</tt>
 
-Before we get started, I think it's important to get familiar with the <tt>Database#literal</tt> method, which will return the SQL that will be used for a given expression:
+It's important to get familiar with the <tt>Database#literal</tt> method, which will return the SQL that will be used for a given expression:
 
   DB.literal(1)
   # => "1"
@@ -101,7 +101,7 @@ Before we get started, I think it's important to get familiar with the <tt>Datab
   DB.literal('string')
   # => "'string'"
 
-I encourage you to just play around to see how different objects get literalized into SQL
+Try playing around to see how different objects get literalized into SQL
 
 === Database Loggers
 
@@ -346,18 +346,15 @@ Sequel defines the & and | methods on most Sequel-specific expression objects to
   Sequel.expr(: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:
+Note the use of parentheses in the last statement.  If you omit them, you won't get what you expect.
+Because & has higher precedence than >
 
-  Sequel.function(:func) > 1 & :column3 # (func() > 1)
+  Sequel.function(:func) > 1 & :column3
 
-This is because & has higher precedence than >, so it is parsed as:
+is parsed as:
 
   Sequel.function(:func) > (1 & :column3)
 
-In this case, <tt>:column3.to_int</tt> returns an odd integer, so:
-
-  1 & :column3 # => 1
-
 You and also use the <tt>Sequel.&</tt> and <tt>Sequel.|</tt> methods:
 
   Sequel.&(:column1, :column2) # ("column1" AND "column2")
@@ -505,7 +502,7 @@ 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)
 
-If you provide a 2nd argument to CASE, it goes between CASE and WHEN:
+If you provide a 3rd argument to <tt>Sequel.case</tt>, it goes between CASE and WHEN:
 
   Sequel.case({2=>1, 3=>5}, 0, :column) # (CASE column WHEN 2 THEN 1 WHEN 3 THEN 5 ELSE 0 END)
 
@@ -538,9 +535,9 @@ If you want to select from multiple FROM tables, use multiple arguments:
 
   DB[:albums, :artists] # SELECT * FROM albums, artists
 
-If you don't want to select from any FROM tables, use no arguments:
+If you don't want to select from any FROM tables, just call dataset:
 
-  DB[] # SELECT *
+  DB.dataset # SELECT *
 
 === Chaining Methods
 

data/doc/testing.rdoc

@@ -6,8 +6,6 @@ Whether or not you use Sequel in your application, you are usually going to want
 
 These run each test in its own transaction, the recommended way to test.
 
-Make sure you are using Sequel 3.29.0 or above when using these examples, as older versions don't support the <tt>:rollback=>:always</tt> option.
-
 === RSpec 1
 
   class Spec::Example::ExampleGroup
@@ -103,7 +101,7 @@ Use Sequel.transaction with an array of databases:
 
 In some cases, it is not possible to use transactions.  For example, if you are testing a web application that is running in a separate process, you don't have access to that process's database connections, so you can't run your examples in transactions.  In that case, the best way to handle things is to cleanup after each test by deleting or truncating the database tables used in the test.
 
-The order in which you delete/truncate the tables is important if you are using referential integrity in your database (which you probably should be doing).  If you are using referential integrity, you need to make sure to delete in tables referencing other tables before the tables that are being referenced.  For example, if you have an +albums+ table with an +artist_id+ field referencing the +artists+ table, you want to delete/truncate the +albums+ table before the +artists+ table.  Note that if you have cyclic references in your database, you will probably need to write your own custom cleaning code.
+The order in which you delete/truncate the tables is important if you are using referential integrity in your database (which you should be doing).  If you are using referential integrity, you need to make sure to delete in tables referencing other tables before the tables that are being referenced.  For example, if you have an +albums+ table with an +artist_id+ field referencing the +artists+ table, you want to delete/truncate the +albums+ table before the +artists+ table.  Note that if you have cyclic references in your database, you will probably need to write your own custom cleaning code.
 
 === RSpec
 
@@ -138,16 +136,22 @@ The +spec+ rake task (which is also the default rake task) runs Sequel's core an
 
 The +spec_plugin+ rake task runs the specs for the plugins and extensions that ship with Sequel.  These also use a mocked database connection, and operate very similarly to the general Sequel core and model specs.
 
+== rake spec_bin
+
+The +spec_bin+ rake task runs the specs for bin/sequel.  These use an SQLite3 database, and require either the sqlite3 (non-JRuby) or jdbc-sqlite3 (JRuby) gem.
+
 == rake spec_<i>adapter</i> (e.g. rake spec_postgres)
 
 The <tt>spec_<i>adapter</i></tt> specs run against a real database connection with nothing mocked, and test for correct results.  They are slower than the standard specs, but they will catch errors that are mocked out by the default specs, as well as show issues that only occur on a certain database, adapter, or a combination of the two.
 
-These specs are broken down into two parts.  For each database, there are specific specs that only apply to that database, and these are called the adapter specs.  There are also shared specs that apply to all (or almost all) databases, these are called the integration specs.
+These specs are broken down into two parts.  For each database, there are specific specs that only apply to that database, and these are called the adapter specs.  There are also shared specs that apply to all (or almost all) databases, these are called the integration specs. For database types that don't have specific adapter tests, you can use rake spec_integration to just run the shared integration tests.
 
 == Environment variables
 
 Sequel often uses environment variables when testing to specify either the database to be tested or specify how testing should be done.  You can also specify the databases to test by copying spec/spec_config.rb.example to spec/spec_config.rb and modifying it.  See that file for details.  It may be necessary to use spec_config.rb as opposed to an environment variable if your database connection cannot be specified by a connection string.
 
+Sequel does not create test databases automatically, except for file-based databases such as SQLite/H2/HSQLDB/Derby.  It's up to the user to create the test databases manually and give Sequel a valid connection string in an environment variable (or setup the connection object in spec_config.rb).
+
 === Connection Strings
 
 The following environment variables specify Database connection URL strings:

data/doc/transactions.rdoc

@@ -27,7 +27,6 @@ If the block raises a Sequel::Rollback exception, the transaction is rolled back
 
 If any other exception is raised, the transaction is rolled back, and the exception is raised outside the block:
 
-  # ArgumentError raised
   DB.transaction do # BEGIN
     raise ArgumentError
   end # ROLLBACK
@@ -45,6 +44,7 @@ If you always want to rollback (useful for testing), use the <tt>:rollback => :a
   DB.transaction(:rollback => :always) do # BEGIN
     DB[:foo].insert(1) # INSERT
   end # ROLLBACK
+  # no exception raised
 
 If you want to check whether you are currently in a transaction, use the Database#in_transaction? method:
 
@@ -129,7 +129,7 @@ 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 PostgreSQL, MySQL, and Microsoft SQL Server, 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 make Sequel use the correct transaction isolation syntax for your database:
 
   DB.transaction(:isolation => :serializable) do # BEGIN
     # SET TRANSACTION ISOLATION LEVEL SERIALIZABLE

data/doc/validations.rdoc

@@ -32,7 +32,7 @@ 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, that MySQL will just silently truncate it for you, instead of
+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
 to enforce the database integrity.
 
@@ -172,16 +172,22 @@ This is probably the most commonly used helper method, which checks if the speci
 
   class Album < Sequel::Model
     def validate
+      super
       validates_presence [:name, :website, :debut_album]
     end
   end
 
+=== +validates_not_null+
+
+This is similar to +validates_presence+, but only checks for NULL/nil values, allowing other blank objects such as empty strings or strings with just whitespace.
+
 === +validates_format+
 
 +validates_format+ is used to ensure that the string value of the specified attributes matches the specified regular expression.  It's useful for checking that fields such as email addresses, URLs, UPC codes, ISBN codes, and the like, are in a specific format.  It can also be used to validate that only certain characters are used in the string.
 
   class Album < Sequel::Model
     def validate
+      super
       validates_format /\A\d\d\d-\d-\d{7}-\d-\d\z/, :isbn
       validates_format /\a[0-9a-zA-Z:' ]+\z/, :name
     end
@@ -194,6 +200,7 @@ These methods all deal with ensuring that the length of the specified attribute
 
   class Album < Sequel::Model
     def validate
+      super
       validates_exact_length 17, :isbn
       validates_min_length 3, :name
       validates_max_length 100, :name
@@ -207,6 +214,7 @@ These methods check that the specified attributes can be valid integers or valid
 
   class Album < Sequel::Model
     def validate
+      super
       validates_integer :copies_sold
       validates_numeric :replaygain
     end
@@ -224,35 +232,33 @@ These methods check that the specified attributes can be valid integers or valid
 
 === +validates_type+
 
-+validates_type+ checks that the specified attributes are instances of the class specified in the first argument.  The class can be specified as the class itself, or as a string or symbol with the class name:
++validates_type+ checks that the specified attributes are instances of the class specified in the first argument.  The class can be specified as the class itself, or as a string or symbol with the class name, or as a an array of classes.
 
   class Album < Sequel::Model
     def validate
+      super
       validates_type String, [:name, :website]
       validates_type :Artist, :artist
+      validates_type [String, Integer], :foo
     end
   end
 
-=== +validates_not_string+
-
-+validates_not_string+ is a special validation designed to be used with the <tt>raise_on_typecast_failure = false</tt> setting.  By default, Sequel raises errors when typecasting fails, immediately when you try to set the value on the object:
+=== +validates_schema_types+
 
-  album = Album.new
-  album.copies_sold = 'banana' # raises Sequel::InvalidValue
-
-The <tt>raise_on_typecast_failure = false</tt> setting tells Sequel to attempt to typecast values, but to silently ignore 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 <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:
 
   Album.raise_on_typecast_failure = false
   album = Album.new
   album.copies_sold = 'banana'
   album.copies_sold # => 'banana'
 
-+validates_not_string+ is designed to be used in web applications where all user input comes in as strings.  When the <tt>raise_on_typecast_failure = false</tt> setting is used in such an application, you can call +validates_not_string+ with all non-string columns.  If any of those columns has a string value, it's 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:
+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:
 
   class Album < Sequel::Model
     self.raise_on_typecast_failure = false
     def validate
-      validates_not_string [:release_date, :record_date]
+      super
+      validates_schema_types [:release_date, :record_date]
     end
   end
 
@@ -264,7 +270,7 @@ The <tt>raise_on_typecast_failure = false</tt> setting tells Sequel to attempt t
   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_not_string+ is helpful because it allows you to check for typecasting errors on non-string 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 <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.
 
 === +validates_unique+
 
@@ -301,10 +307,11 @@ All +validation_helpers+ methods except +validates_unique+ accept the following
 
 === <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 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.
 
   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"}
     end
@@ -316,6 +323,7 @@ The <tt>:allow_nil</tt> option skips the validation if the attribute value is ni
 
   class Album < Sequel::Model
     def validate
+      super
       validates_presence :copies_sold
       validates_integer :copies_sold, :allow_nil=>true
     end
@@ -329,6 +337,7 @@ 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
     end
   end
@@ -386,8 +395,9 @@ These are the default error messages for all of the helper methods in +validatio
 :length_range :: is too short or too long
 :max_length :: is longer than #{arg} characters
 :min_length :: is shorter than #{arg} characters
-:not_string :: is not a valid #{schema_type}
+:not_null :: is not present
 :numeric :: is not a number
+:schema_types :: is not a valid #{schema_type}
 :type :: is not a #{arg}
 :presence :: is not present
 :unique :: is already taken
@@ -404,6 +414,8 @@ It's easy to modify the default options used by +validation_helpers+.  All of th
 
 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 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.
+
 == Custom Validations
 
 Just as the first validation example showed, you aren't limited to the validation methods defined by +validation_helpers+.  Inside the +validate+ method, you can add your own validations by adding to the instance's errors using <tt>errors.add</tt> whenever an attribute is not valid:
@@ -442,7 +454,7 @@ Let's say you want to add some default validations that apply to all of your mod
 
     def validate
       super
-      validates_format(/\A[^\x00-\x08\x0e-\x1f\x7f\x81\x8d\x8f\x90\x9d]*\z/,
+      validates_format(/\A[^\x00-\x08\x0e-\x1f\x7f\x81\x8d\x8f\x90\x9d]*\z/n,
        model.string_columns,
        :message=>"contains invalid characters")
     end
@@ -496,6 +508,17 @@ Here, you don't care about validating the release date if there were validation
 
   album.errors.count # => 1
 
-== +validation_class_methods+
+== Other Validation Plugins
+
+=== +constraint_validations+
+
+Sequel ships with a +constraint_validations+ plugin and extension, that allows you to setup constraints when creating your database tables, and have Model validations automatically created that mirror those constraints.
+
+=== +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.
+
+=== +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.
 
-Sequel actually ships with two validation plugins.  The recommended one that this guide focused on is the +validation_helpers+ plugin.  However, Sequel also 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.

data/doc/virtual_rows.rdoc

@@ -9,7 +9,7 @@ many Sequel::Dataset methods that take virtual row blocks.
 
 Virtual Rows were created to work around the issue that some parts of
 Sequel's standard DSL could not be used on ruby 1.9.  For example, the
-following Sequel code works on ruby 1.8, but not ruby 1.9:
+following Sequel code historically worked on ruby 1.8, but not ruby 1.9:
 
   dataset.where(:a > :b[:c])
   # WHERE a > b(c)
@@ -243,7 +243,7 @@ doesn't look as nice:
 == Returning multiple values
 
 It's common when using select and order virtual row blocks to want to
-return multiple values.  If you want to do that, you just need to return a single
+return multiple values.  If you want to do that, you just need to return an 
 array:
 
   ds.select{|o| [o.column1, o.sum(o.column2).as(o.sum)]}

data/lib/sequel/adapters/ado.rb

@@ -8,25 +8,6 @@ module Sequel
 
       set_adapter_scheme :ado
 
-      def initialize(opts)
-        super
-        case @opts[:conn_string]
-        when /Microsoft\.(Jet|ACE)\.OLEDB/io
-          Sequel.ts_require 'adapters/ado/access'
-          extend Sequel::ADO::Access::DatabaseMethods
-          @dataset_class = ADO::Access::Dataset
-        else
-          @opts[:driver] ||= 'SQL Server'
-          case @opts[:driver]
-          when 'SQL Server'
-            Sequel.ts_require 'adapters/ado/mssql'
-            extend Sequel::ADO::MSSQL::DatabaseMethods
-            @dataset_class = ADO::MSSQL::Dataset
-            set_mssql_unicode_strings
-          end
-        end
-      end
-
       # In addition to the usual database options,
       # the following options have an effect:
       #
@@ -59,6 +40,8 @@ module Sequel
       
       def disconnect_connection(conn)
         conn.Close
+      rescue WIN32OLERuntimeError
+        nil
       end
 
       # Just execute so it doesn't attempt to return the number of rows modified.
@@ -98,10 +81,32 @@ module Sequel
         end
         nil
       end
-      alias do execute
+      def do(*a, &block)
+        Sequel::Deprecation.deprecate('Database#do', 'Please use Database#execute')
+        execute(*a, &block)
+      end
 
       private
       
+      def adapter_initialize
+        case @opts[:conn_string]
+        when /Microsoft\.(Jet|ACE)\.OLEDB/io
+          Sequel.require 'adapters/ado/access'
+          extend Sequel::ADO::Access::DatabaseMethods
+          self.dataset_class = ADO::Access::Dataset
+        else
+          @opts[:driver] ||= 'SQL Server'
+          case @opts[:driver]
+          when 'SQL Server'
+            Sequel.require 'adapters/ado/mssql'
+            extend Sequel::ADO::MSSQL::DatabaseMethods
+            self.dataset_class = ADO::MSSQL::Dataset
+            set_mssql_unicode_strings
+          end
+        end
+        super
+      end
+
       # The ADO adapter's default provider doesn't support transactions, since it 
       # creates a new native connection for each query.  So Sequel only attempts
       # to use transactions if an explicit :provider is given.