sequel 4.26.0 → 5.37.0

data/doc/model_plugins.rdoc

@@ -33,7 +33,7 @@ Doing this, only Node and future subclasses of Node will have the tree plugin lo
 Some plugins require arguments and/or support options.  For example, the single_table_inheritance plugin requires an argument containing the column that specifies the class to use, and options:
 
   class Employee < Sequel::Model
-    plugin :single_table_inheritance, :type_id, :model_map=>{1=>:Staff, 2=>:Manager}
+    plugin :single_table_inheritance, :type_id, model_map: {1=>:Staff, 2=>:Manager}
   end
 
 You should read the documentation for the plugin to determine if it requires arguments and what if any options are supported.
@@ -120,7 +120,7 @@ This allows a plugin user to do:
 
 == Calling super to get Previous Behavior
 
-No matter if you are dealing with class, instance, or dataset methods, you can call super inside the method to get the previous behavior.  This makes it easy to hook into the method, add your own behavior, but still (optionally?) get the previous behavior:
+No matter if you are dealing with class, instance, or dataset methods, you can call super inside the method to get the previous behavior.  This makes it easy to hook into the method, add your own behavior, but still get the previous behavior:
 
   module Sequel::Plugins::Foo
     module InstanceMethods
@@ -135,14 +135,14 @@ No matter if you are dealing with class, instance, or dataset methods, you can c
       private
 
       def allow_saving?
-        `pom` =~ /Waxing/
+        moon =~ /Waxing/
       end
     end
   end
 
 == Running Code When the Plugin is Loaded
 
-Some plugins require more than just adding methods.  Any plugin that requires state is going to have to initialize that state and store it somewhere.  If you want to run code when a plugin is loaded (usually to initialize state, but possibly for other reasons), there are two methods you can define to do so.  The first method is apply, and it is called only the first time the plugin is loaded into the class, before it is loaded into the class.  This is generally only used if a plugin depends on another plugin or for initializing state.  You define this method as a singleton method of the plugin module:
+Some plugins require more than just adding methods.  Any plugin that requires state is going to have to initialize that state and store it somewhere (generally in the model class itself).  If you want to run code when a plugin is loaded (usually to initialize state, but possibly for other reasons), there are two methods you can define to do so.  The first method is apply, and it is called only the first time the plugin is loaded into the class, before it is loaded into the class.  This is generally only used if a plugin depends on another plugin or for initializing state.  You define this method as a singleton method of the plugin module:
 
   module Sequel::Plugins::Foo
     def self.apply(model)
@@ -158,7 +158,7 @@ The other method is called configure, and it is called everytime the plugin is l
   module Sequel::Plugins::Foo
     def self.configure(model)
       model.instance_eval do
-        @foo_state[:initial] = :baz
+        @foo_states[:initial] ||= :baz
       end
     end
   end
@@ -177,7 +177,7 @@ If you want your plugin to take arguments and/or support options, you handle tha
 
     def self.configure(model, opts={})
       model.instance_eval do
-        @foo_state[:initial] = opts[:initial_state] || :baz
+        @foo_states[:initial] = opts[:initial_state] || @foo_states[:initial] || :baz
       end
     end
   end
@@ -185,7 +185,7 @@ If you want your plugin to take arguments and/or support options, you handle tha
 This allows a user of the plugin to do either of the following
 
   Bar.plugin :foo
-  Bar.plugin :foo, :initial_state=>:quux
+  Bar.plugin :foo, initial_state: :quux
 
 If you want to require the initial state to be provided as an argument:
 
@@ -199,7 +199,7 @@ If you want to require the initial state to be provided as an argument:
 
     def self.configure(model, initial_state)
       model.instance_eval do
-        @foo_state[:initial] = initial_state
+        @foo_states[:initial] = initial_state
       end
     end
   end
@@ -212,11 +212,11 @@ In general you should only require plugin arguments if you absolutely must have
 
 == Handling Subclasses
 
-Sequel::Model uses a copy-on-subclassing approach to model state.  So instead of model subclasses asking their parent class for a value if they don't have it defined, the value is automatically copied from the parent class to the subclass when the subclass is created.  While you can do this by overriding the inherited class method, there is a available shortcut that handles most cases:
+Sequel::Model uses a copy-on-subclassing approach to model state.  So instead of having a model subclass ask its superclass for a value if the subclass don't have the value defined, the value should be copied from the parent class to the subclass when the subclass is created.  While this can be implemented by overriding the +inherited+ class method, there is an available shortcut that handles most cases:
 
   module Sequel::Plugins::Foo
     module ClassMethods
-      Sequel::Plugins.inherited_instance_variables(self, :@foo_state=>:dup)
+      Sequel::Plugins.inherited_instance_variables(self, :@foo_states => :dup)
     end
   end
 
@@ -238,12 +238,12 @@ In many plugins, if the model class changes the dataset, you need to change the
       private
 
       def set_foo_table
-        @foo_state[:table] = table_name
+        @foo_states[:table] = table_name
       end
     end
   end
 
-With this code, any time the model's dataset changes, the state of the plugin will be updated to set the correct table name.
+With this code, any time the model's dataset changes, the state of the plugin will be updated to set the correct table name.  This is also called when creating a new model class with a dataset.
 
 == Making Dataset Methods Callable as Class Methods
 

data/doc/mssql_stored_procedures.rdoc

@@ -17,7 +17,7 @@ The following stored procedure is used as an example:
 
 Execute it as follows:
 
-  DB.call_mssql_sproc(:SequelTest, {:args => ['Input String', :output]})
+  DB.call_mssql_sproc(:SequelTest, {args: ['Input String', :output]})
 
 Use the +:output+ symbol to denote an output variable. The result will contain a
 hash of the output variables, as well as the result code and number of affected rows:
@@ -27,7 +27,7 @@ hash of the output variables, as well as the result code and number of affected
 Output variables will be strings by default. To specify their type, include the
 SQL type:
 
-  DB.call_mssql_sproc(:SequelTest, {:args => ['Input String', [:output, 'int']]})
+  DB.call_mssql_sproc(:SequelTest, {args: ['Input String', [:output, 'int']]})
 
 Result:
 
@@ -36,7 +36,7 @@ Result:
 Output variables will be named +var#{n}+ where n is their zero indexed position
 in the parameter list. To name the output variable, include their name:
 
-  DB.call_mssql_sproc(:SequelTest, {:args => ['Input String', [:output, nil, 'Output']]})
+  DB.call_mssql_sproc(:SequelTest, {args: ['Input String', [:output, nil, 'Output']]})
 
 Result:
 

data/doc/object_model.rdoc

@@ -6,13 +6,12 @@ Sequel objects by calling #new on the object's class (other than Sequel::Model
 instances).  However, just as almost everything in ruby is an object, all 
 the methods you call in Sequel deal with objects behind the scenes.
 
-There are five main types of Sequel-specific objects that you deal with in
-Sequel:
+In addition to the standard ruby types, there are four main types of
+Sequel-specific objects that you deal when programming with Sequel:
 
 * Sequel::Database
 * Sequel::Dataset
 * Sequel::Model
-* Standard Ruby Types
 * Sequel::SQL::Expression (and subclasses)
 
 == Sequel::Database
@@ -47,27 +46,27 @@ and literalize the object to an SQL string fragment:
 
 == Sequel::Dataset
 
-Sequel::Dataset objects represent SQL queries, or more generally, they represent
-abstract collections of rows in the database.  They are usually created from
+Sequel::Dataset objects represent SQL queries.  They are created from
 a Sequel::Database object:
 
   dataset = DB[:table]         # SELECT * FROM "table"
   dataset = DB.from(table)     # SELECT * FROM "table"
   dataset = DB.select(:column) # SELECT "column"
 
-Most Sequel::Dataset methods return modified copies of the receiver, and the
-general way to build queries in Sequel is via a method chain:
+Most Sequel::Dataset methods that do not execute queries return modified
+copies of the receiver, and the general way to build queries in Sequel is
+via a method chain:
 
   dataset = DB[:test].
               select(:column1, :column2).
-              where(:column3 => 4).
+              where(column3: 4).
               order(:column5)
 
 Such a method chain is a more direct way of doing:
 
   dataset = DB[:test]
   dataset = dataset.select(:column1, :column2)
-  dataset = dataset.where(:column3 => 4)
+  dataset = dataset.where(column3: 4)
   dataset = dataset.order(:column5)
 
 When you are ready to execute your query, you call one of the Sequel::Dataset
@@ -79,8 +78,8 @@ action methods.  For returning rows, you can do:
 
 For inserting, updating, or deleting rows, you can do:
 
-  dataset.insert(:column=>value)
-  dataset.update(:column=>value)
+  dataset.insert(column: value)
+  dataset.update(column: value)
   dataset.delete
 
 All datasets are related to their database object, which you can access via
@@ -90,7 +89,7 @@ the Sequel::Dataset#db method:
 
 == Sequel::Model
 
-Sequel::Model objects are wrappers around a particular Sequel::Dataset object that
+Sequel::Model classes are wrappers around a particular Sequel::Dataset object that
 add custom behavior, both custom behavior for the entire set of rows in the dataset
 (the model's class methods), custom behavior for a subset of rows in the dataset
 (the model's dataset methods), and custom behavior for single rows in the dataset
@@ -103,6 +102,13 @@ generally created by the user using standard ruby syntax:
   end
   album = Album.new
 
+Model classes that use a non-default Database instance or table name generally
+use the Sequel::Model method to create the superclass:
+
+  class Album < Sequel::Model(DB[:music_albums])
+  end
+  album = Album.new
+
 All model classes are related to their Sequel::Dataset object, which you
 can access via the Sequel::Model.dataset method:
 
@@ -121,26 +127,12 @@ if you pass the left side to Sequel::Database#literal.
 
 === Symbol
 
-For example, ruby symbols represent SQL identifiers (tables, columns, schemas):
+Ruby symbols represent SQL identifiers (tables, columns, schemas):
 
+  :schema # "schema"
   :table  # "table"
   :column # "column"
 
-However, they can also represent qualified identifiers by including a double
-underscore inside a symbol:
-
-  :table__column # "table"."column"
-
-They can also represent an aliased identifier by including a triple underscore
-inside a symbol:
-
-  :column___alias # "column" AS "alias"
-
-You can combine both qualification and aliasing by using a double underscore
-and a triple underscore:
-
-  :table__column___alias # "table"."column" AS "alias"
-
 === Integer, Float, BigDecimal, String, Date, Time, DateTime
 
 Ruby's Integer, Float, BigDecimal, String, Date, Time, and DateTime classes
@@ -158,31 +150,31 @@ represent similar types in SQL:
 
 Sequel generally uses hash objects to represent equality:
 
-  {:column => 1} # ("column" = 1)
+  {column: 1} # ("column" = 1)
 
-However, if you use in array as the hash value, it will usually be used to represent inclusion:
+However, if you use an array as the hash value, it represents inclusion in the value list:
 
-  {:column => [1, 2, 3]} # ("column" IN (1, 2, 3))
+  {column: [1, 2, 3]} # ("column" IN (1, 2, 3))
 
 You can also use a Sequel::Dataset instance as the hash value, which will be used to
 represent inclusion in the subselect:
 
-  {:column => DB[:table].select(:column)} # ("column" IN (SELECT "column" FROM "table"))
+  {column: DB[:table].select(:column)} # ("column" IN (SELECT "column" FROM "table"))
 
-If you pass true, false, or nil as the hash value, it will be used to represent identity:
+If you pass true, false, or nil as the hash value, it represents identity:
 
-  {:column => nil} # ("column" IS NULL)
+  {column: nil} # ("column" IS NULL)
 
 If you pass a Range object, it will be used as the bounds for a greater than and less than
 operation:
 
-  {:column => 1..2} # (("column" >= 1) AND ("column" <= 2))
-  {:column => 1...3} # (("column" >= 1) AND ("column" < 3))
+  {column: 1..2}  # (("column" >= 1) AND ("column" <= 2))
+  {column: 1...3} # (("column" >= 1) AND ("column" < 3))
 
 If you pass a Regexp object as the value, it will be used as a regular expression
-operation (only supported on PostgreSQL and MySQL currently):
+operation if the database supports it:
 
-  {:column => /a.*b/} # ("column" ~ 'a.*b')
+  {column: /a.*b/} # ("column" ~ 'a.*b')
 
 === Array
 
@@ -251,9 +243,8 @@ no additional behavior, so it can be instantiated like a normal array:
 
   Sequel::SQL::ValueList.new([[1, 2], [3, 4]]) # ((1, 2), (3, 4))
 
-In old versions of Sequel, these objects often needed to be created manually,
-but in newer versions of Sequel, they are created automatically in most cases
-where they are required.
+In general, you don't need to create Sequel::SQL::ValueList instances manually,
+they will be created automatically where they are required in most cases.
 
 The following shortcuts exist for creating Sequel::SQL::ValueList objects:
 
@@ -263,16 +254,16 @@ The following shortcuts exist for creating Sequel::SQL::ValueList objects:
 === Sequel::SQL::Identifier
 
 Sequel::SQL::Identifier objects represent single identifiers.  The main reason for
-their existance is that they are not checked for double or triple underscores, so no
-automatic qualification or aliasing happens for them:
+their existence is they support many additional Sequel specific methods that are
+not supported on plain symbols:
 
-  Sequel::SQL::Identifier.new(:col__umn) # "col__umn"
+  Sequel::SQL::Identifier.new(:colum) # "col"
 
 The following shortcuts exist for creating Sequel::SQL::Identifier objects:
 
-  Sequel.expr(:column)
-  Sequel.identifier(:col__umn)
-  :col__umn.identifier # core_extensions extension
+  Sequel[:column]
+  Sequel.identifier(:column)
+  :column.identifier # core_extensions extension
 
 === Sequel::SQL::QualifiedIdentifier
 
@@ -282,7 +273,7 @@ Sequel::SQL::QualifiedIdentifier objects represent qualified identifiers:
 
 The following shortcuts exist for creating Sequel::SQL::QualifiedIdentifier objects:
 
-  Sequel.expr(:table__column)
+  Sequel[:table][:column]
   Sequel.qualify(:table, :column)
   :column.qualify(:table) # core_extensions extension
 
@@ -294,15 +285,17 @@ is treated as an identifier, but the expression can be an arbitrary Sequel expre
   Sequel::SQL::AliasedExpression.new(:column, :alias)
   # "column" AS "alias"
 
+Derived column lists are also supported:
+
   Sequel::SQL::AliasedExpression.new(:table, :alias, [:column_alias1, :column_alias2])
   # "table" AS "alias"("column_alias1", "column_alias2")
 
 The following shortcuts exist for creating Sequel::SQL::AliasedExpression objects:
 
-  Sequel.expr(:column___alias)
+  Sequel[:column].as(:alias)
   Sequel.as(:column, :alias)
   Sequel.as(:column, :alias, [:column_alias1, :column_alias2])
-  :column.as(:alias) # core_extensions extension
+  :column.as(:alias) # core_extensions or symbol_as extension
   
 === Sequel::SQL::ComplexExpression
 
@@ -338,7 +331,7 @@ against:
 
 Or they can treat each condition separately:
  
-  Sequel::SQL::CaseExpression.new({{:a=>2}=>1}, 0) # CASE WHEN ("a" = 2) THEN 1 ELSE 0 END
+  Sequel::SQL::CaseExpression.new({{a: 2}=>1}, 0) # CASE WHEN ("a" = 2) THEN 1 ELSE 0 END
 
 In addition to providing a hash, you can also provide an array of two-element arrays:
 
@@ -347,10 +340,10 @@ In addition to providing a hash, you can also provide an array of two-element ar
 The following shortcuts exist for creating Sequel::SQL::CaseExpression objects:
 
   Sequel.case({2=>1}, 0, :a)
-  Sequel.case({{:a=>2}=>1}, 0)
+  Sequel.case({{a: 2}=>1}, 0)
 
   {2=>1}.case(0, :a) # core_extensions extension
-  {{:a=>2}=>1}.case(0) # core_extensions extension
+  {{a: 2}=>1}.case(0) # core_extensions extension
 
 === Sequel::SQL::Cast
 
@@ -375,21 +368,19 @@ The following shortcuts exist for creating Sequel::SQL::Cast objects:
 
 === Sequel::SQL::ColumnAll
 
-Sequel::SQL::ColumnAll objects represent the selection of all columns from a
-table.  They are pretty much only used as arguments to one of the Dataset select
-methods, and are not used much anymore since Dataset#select_all was expanded to
-take arguments.  Still, it's possible they are still useful in some code:
+Sequel::SQL::ColumnAll objects represent the selection of all columns from a table:
 
   Sequel::SQL::ColumnAll.new(:table) # "table".*
 
 The following shortcut exists for creating Sequel::SQL::ColumnAll objects:
 
-  Sequel.expr(:table).*
+  Sequel[:table].*
+  Sequel[:schema][:table].*
   :table.* # core_extensions extension
 
 === Sequel::SQL::Constant
 
-Sequel::SQL::Constant objects represent constants or psuedo-constants in SQL,
+Sequel::SQL::Constant objects represent constants or pseudo-constants in SQL,
 such as TRUE, NULL, and CURRENT_TIMESTAMP.  These are not designed to be created
 or used by the end user, but some existing values are predefined under the
 Sequel namespace:
@@ -398,7 +389,7 @@ Sequel namespace:
 
 These objects are usually used as values in queries:
 
-  DB[:table].insert(:time=>Sequel::CURRENT_TIMESTAMP)
+  DB[:table].insert(time: Sequel::CURRENT_TIMESTAMP)
 
 === Sequel::SQL::DelayedEvaluation
 
@@ -457,7 +448,7 @@ The first type uses question marks with multiple placeholder value objects:
 The second uses named placeholders with colons and a hash of placeholder
 value objects:
 
-  Sequel::SQL::PlaceholderLiteralString.new(':b = :v', [{:b=>:a, :v=>1}]) # "a" = 1
+  Sequel::SQL::PlaceholderLiteralString.new(':b = :v', [{b: :a, v: 1}]) # "a" = 1
 
 The third uses an array instead of a string, with multiple placeholder
 objects, each one going in between the members of the array:
@@ -473,7 +464,7 @@ The following shortcuts exist for creating Sequel::SQL::PlaceholderLiteralString
 objects:
 
   Sequel.lit('? = ?', :a, 1)
-  Sequel.lit(':b = :v', :b=>:a, :v=>1)
+  Sequel.lit(':b = :v', b: :a, v: 1)
   Sequel.lit(['', ' = '], :a, 1)
 
   '? = ?'.lit(:a, 1) # core_extensions extension
@@ -543,10 +534,10 @@ Sequel::SQL::Window objects represent the windows used by Sequel::SQL::Function.
 They use a hash-based API, supporting the :frame, :order, :partition, and :window
 options:
 
-  Sequel::SQL::Window.new(:order=>:a) # (ORDER BY "a")
-  Sequel::SQL::Window.new(:parition=>:a) # (PARTITION BY "a")
+  Sequel::SQL::Window.new(order: :a) # (ORDER BY "a")
+  Sequel::SQL::Window.new(partition: :a) # (PARTITION BY "a")
 
-  Sequel::SQL::Window.new(:parition=>:a, :frame=>:all)
+  Sequel::SQL::Window.new(partition: :a, frame: :all)
   # (PARTITION BY "a" ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING)
 
 === Sequel::SQL::Wrapper
@@ -555,7 +546,7 @@ Sequel::SQL::Wrapper objects wrap arbitrary objects so that they can be used
 in Sequel expressions:
 
   o = Object.new
-  def o.sql_literal(ds) "foo" end
+  def o.sql_literal_append(ds, sql) sql << "foo" end
   Sequel::SQL::Wrapper.new(o) # foo
 
 The advantage of wrapping the object is that you can the call Sequel methods
@@ -563,11 +554,10 @@ on the wrapper that would not be defined on the object itself:
 
   Sequel::SQL::Wrapper.new(o) + 1 # (foo + 1)
 
-You can use the Sequel.expr method to wrap any object:
+You can use the Sequel.[] method to wrap any object:
 
-  Sequel.expr(o)
+  Sequel[o]
 
 However, note that that does not necessarily return a Sequel::SQL::Wrapper
 object, it may return a different class of object, such as a
 Sequel::SQL::ComplexExpression subclass object.
-  

data/doc/opening_databases.rdoc

@@ -28,12 +28,12 @@ You can use URI query parameters to specify options:
 
 You can also pass an additional option hash with the connection string:
 
-  DB = Sequel.connect('postgres://localhost/blog', :user=>'user', :password=>'password')
+  DB = Sequel.connect('postgres://localhost/blog', user: 'user', password: 'password')
 
 You can also just use an options hash without a connection string.  If you do this, you must
 provide the adapter to use:
 
-  DB = Sequel.connect(:adapter=>'postgres', :host=>'localhost', :database=>'blog', :user=>'user', :password=>'password')
+  DB = Sequel.connect(adapter: 'postgres', host: 'localhost', database: 'blog', user: 'user', password: 'password')
 
 All of the above statements are equivalent.
 
@@ -43,12 +43,12 @@ The specialized adapter method is similar to Sequel.connect with an options hash
 automatically populates the :adapter option and assumes the first argument is the :database option,
 unless the first argument is a hash. So the following statements are equivalent to the previous statements.
 
-  DB = Sequel.postgres('blog', :host=>'localhost', :user=>'user', :password=>'password')
-  DB = Sequel.postgres(:host=>'localhost', :user=>'user', :password=>'password', :database=>'blog')
+  DB = Sequel.postgres('blog', host: 'localhost', user: 'user', password: 'password')
+  DB = Sequel.postgres(host: 'localhost', user: 'user', password: 'password', database: 'blog')
 
 Note that using an adapter method forces the use of the specified adapter, not a database type, even
 though some adapters have the same name as the database type.  So if you
-want to connect to SQLite, for example, you can do so using the sqlite, do, jdbc, and swift adapters.
+want to connect to SQLite, for example, you can do so using the sqlite, amalgalite, and jdbc adapters.
 If you want to connect to SQLite on JRuby using the jdbc adapter, you should not use <tt>Sequel.sqlite</tt>
 for example, as that uses the C-based sqlite3 gem. Instead, the <tt>Sequel.jdbc</tt> would be appropriate (though
 as mentioned below, using <tt>Sequel.connect</tt> is recommended instead of <tt>Sequel.jdbc</tt>). 
@@ -62,28 +62,49 @@ For example:
 
   Sequel.connect('sqlite://blog.db'){|db| puts db[:users].count}  
 
+Note that if you do not pass a block to Sequel.connect, Sequel will automatically retain a
+reference to the object in the <tt>Sequel::DATABASES</tt> array.  So calling +Sequel.connect+
+multiple times (say once per request), can result in a memory leak.  For any application where
+database access is needed for a long period of time, it's best to store the result of
+Sequel.connection in a constant, as recommended above.
+
+== Using the Sequel.connect method
 == General connection options
 
 These options are shared by all adapters unless otherwise noted.
 
 :adapter :: The adapter to use
 :database :: The name of the database to which to connect
+:extensions :: Extensions to load into this Database instance.  Can be a symbol, array of symbols,
+               or string with extensions separated by columns.  These extensions are loaded after
+               connections are made by the :preconnect option.
+:cache_schema :: Whether schema should be cached for this database (true by default)
+:default_string_column_size :: The default size for string columns (255 by default)
 :host :: The hostname of the database server to which to connect
+:keep_reference :: Whether to keep a reference to the database in Sequel::DATABASES (true by default)
+:logger :: A specific SQL logger to log to
 :loggers :: An array of SQL loggers to log to
+:log_connection_info :: Whether to include connection information in log messages (false by default)
+:log_warn_duration :: The amount of seconds after which the queries are logged at :warn level
 :password :: The password for the user account
-:servers :: A hash with symbol keys and hash or proc values, used with master/slave/partitioned database configurations
-:single_threaded :: Whether to use a single-threaded (non-thread safe) connection pool
-:test :: Whether to test that a valid database connection can be made (false by default)
+:preconnect :: Whether to automatically make the maximum number of connections when setting up the pool.
+               Can be set to "concurrently" to connect in parallel.
+:preconnect_extensions :: Similar to the :extensions option, but loads the extensions before the
+                          connections are made by the :preconnect option.
+:quote_identifiers :: Whether to quote identifiers.
+:servers :: A hash with symbol keys and hash or proc values, used with primary/replica and sharded database configurations
+:sql_log_level :: The level at which to issue queries to the loggers (:info by default)
+:test :: Whether to test that a valid database connection can be made (true by default)
 :user :: The user account name to use logging in
 
 The following options can be specified and are passed to the database's internal connection pool.
 
 :after_connect :: A callable object called after each new connection is made, with the
                   connection object (and server argument if the callable accepts 2 arguments),
-                  useful for customizations that you want to apply to all connections (default: nil).
-:max_connections :: The maximum size of the connection pool (default: 4 connections on most databases)
-:pool_sleep_time :: The number of seconds to sleep before trying to acquire a connection again (default: 0.001 seconds)
-:pool_timeout :: The number of seconds to wait if a connection cannot be acquired before raising an error (default: 5 seconds)
+                  useful for customizations that you want to apply to all connections (nil by default).
+:max_connections :: The maximum size of the connection pool (4 connections by default on most databases)
+:pool_timeout :: The number of seconds to wait if a connection cannot be acquired before raising an error (5 seconds by default)
+:single_threaded :: Whether to use a single-threaded (non-thread safe) connection pool
 
 == Adapter specific connection options
 
@@ -105,7 +126,6 @@ The following options are supported:
 :command_timeout :: Sets the time in seconds to wait while attempting
                     to execute a command before cancelling the attempt and generating
                     an error. Specifically, it sets the ADO CommandTimeout property.
-                    If this property is not set, the default of 30 seconds is used.
 :driver :: The driver to use in the ADO connection string.  If not provided, a default
            of "SQL Server" is used.
 :conn_string :: The full ADO connection string.  If this is provided,
@@ -116,9 +136,9 @@ The following options are supported:
              for every query, which breaks things such as transactions and temporary tables.
 
 Pay special attention to the :provider option, as without specifying a provider,
-many things will be broken.  The SQLNCLI10 provider appears to work well if you
-are connecting to Microsoft SQL Server, but it is not the default as that would
-break backwards compatability.
+many things will be broken.  The SQLNCLI10 and SQLNCLI11 providers work well if you
+are connecting to Microsoft SQL Server, but it is not the default as it depends on
+those providers being installed.
 
 Example connections:
 
@@ -126,11 +146,11 @@ Example connections:
   Sequel.connect('ado:///sequel_test?host=server%5cdb_instance')
   Sequel.connect('ado://user:password@server/database?host=server%5cdb_instance&provider=SQLNCLI10')
   # Access 2007
-  Sequel.ado(:conn_string=>'Provider=Microsoft.ACE.OLEDB.12.0;Data Source=drive:\\path\\filename.accdb')
+  Sequel.ado(conn_string: 'Provider=Microsoft.ACE.OLEDB.12.0;Data Source=drive:\\path\\filename.accdb')
   # Access 2000
-  Sequel.ado(:conn_string=>'Provider=Microsoft.Jet.OLEDB.4.0;Data Source=drive:\\path\\filename.mdb')
+  Sequel.ado(conn_string: 'Provider=Microsoft.Jet.OLEDB.4.0;Data Source=drive:\\path\\filename.mdb')
   # Excel 2000 (for table names, use a dollar after the sheet name, e.g. Sheet1$)
-  Sequel.ado(:conn_string=>'Provider=Microsoft.Jet.OLEDB.4.0;Data Source=drive:\\path\\filename.xls;Extended Properties=Excel 8.0;')
+  Sequel.ado(conn_string: 'Provider=Microsoft.Jet.OLEDB.4.0;Data Source=drive:\\path\\filename.xls;Extended Properties=Excel 8.0;')
 
 === amalgalite 
 
@@ -148,31 +168,6 @@ Without a database argument, assumes a memory database, so you can do:
 Handles paths in the connection string similar to the SQLite adapter, so see
 the sqlite section below for details.
 
-=== cubrid
-
-cubrid is a ruby extension for accessing a CUBRID database.  Currently,
-the ruby cubrid gem is in fairly rough state, with broken transaction
-support and some other issues, but most things work.
-
-=== do 
-
-Requires: data_objects
-
-The DataObjects adapter supports PostgreSQL, MySQL, and SQLite.  One possible
-advantage of using DataObjects is that it does the typecasting in C, which may
-be faster than the other adapters.
-
-Similar to the JDBC adapter, the DO adapter only cares about connection strings,
-which can either be the String argument given to Sequel.connect directly or contained
-in a :uri or :url option.  The DO adapter passes through the connection string
-directly to DataObjects, it does no processing of it (other than removing the do: prefix).
-
-Connection string examples:
-
-  do:sqlite3::memory:
-  do:postgres://user:password@host/database
-  do:mysql://user:password@host/database
-
 === ibmdb
 
 requires 'ibm_db'
@@ -186,20 +181,14 @@ Requires: java
 
 Houses Sequel's JDBC support when running on JRuby.
 Support for individual database types is done using subadapters.
-There are currently subadapters for PostgreSQL, MySQL, SQLite, H2, HSQLDB, Derby,
-Oracle, MSSQL, JTDS, AS400, Progress, Firebird, Informix, and DB2.
-For PostgreSQL, MySQL, SQLite, H2, HSQLDB, Derby, and JTDS,
-this can use the jdbc-* gem, for the others you need to have the .jar in your CLASSPATH
+There are currently subadapters for DB2, Derby, H2, HSQLDB, JTDS,
+MySQL, Oracle, PostgreSQL, SQLAnywhere, SQLite, and SQL Server.
+For Derby, H2, HSQLDB, JTDS, MySQL, Postgres, SQLite3
+the adapters can use the `jdbc-*` gem, for the others you need to have the `.jar` in your CLASSPATH
 or load the Java class manually before calling Sequel.connect.
 
-You just use the JDBC connection string directly, which can be specified
-via the string given to Sequel.connect or via the :uri, :url, or :database options.
-Sequel does no preprocessing of the string, it passes it directly to JDBC.
-So if you have problems getting a connection string to work, look up the JDBC
-documentation.
-
 Note that when using a JDBC adapter, the best way to use Sequel
-is via Sequel.connect, NOT Sequel.jdbc.  Use the JDBC connection
+is via Sequel.connect using a connection string, NOT Sequel.jdbc.  Use the JDBC connection
 string when connecting, which will be in a different format than
 the native connection string.  The connection string should start
 with 'jdbc:'.  For PostgreSQL, use 'jdbc:postgresql:', and for
@@ -207,6 +196,14 @@ SQLite you do not need 2 preceding slashes for the database name
 (use no preceding slashes for a relative path, and one preceding
 slash for an absolute path).
 
+Sequel does no preprocessing of JDBC connection strings, it passes them directly to JDBC.
+So if you have problems getting a connection string to work, look up the 
+documentation for the JDBC driver.
+
+The jdbc adapter does not handle common options such as +:host+,
++:user+, and +:port+.  If you must use a hash of options when connecting,
+provide the full JDBC connection string as the :uri option.
+
 Example connection strings:
 
   jdbc:sqlite::memory:
@@ -219,9 +216,6 @@ Example connection strings:
   jdbc:jtds:sqlserver://localhost/sequel_test;user=sequel_test;password=sequel_test
   jdbc:oracle:thin:user/password@localhost:1521:database
   jdbc:db2://localhost:3700/database:user=user;password=password;
-  jdbc:firebirdsql:localhost/3050:/path/to/database.fdb
-  jdbc:jdbcprogress:T:hostname:port:database
-  jdbc:cubrid:hostname:port:database:::
   jdbc:sqlanywhere://localhost?DBN=Test;UID=user;PWD=password
 
 You can also use JNDI connection strings:
@@ -239,20 +233,26 @@ The following additional options are supported:
            and only helps cases where <tt>java.sql.DriverManager.getConnection</tt> does not
            return a connection.
 :login_timeout :: Set the login timeout on the JDBC connection (in seconds).
+:jdbc_properties :: A hash for properties to set, skips the normal connection process of using
+                    java.sql.drivermanager.getconnection and tries the backup process of using
+                    driver.new.connect for the appropriate driver.
+
+There are a few issues with specific jdbc driver gems:
+
+jdbc-h2 :: jdbc-h2 versions greater than 1.3.175 have issues with ORDER BY not working correctly in some cases.
 
 === mysql 
 
-Requires: mysqlplus (or mysql if mysqlplus is not available)
+Requires: mysql
 
-The MySQL adapter does not support the pure-ruby MySQL adapter that used to ship with
-ActiveRecord, it requires the native adapter.
+The MySQL adapter does not support the pure-ruby mysql.rb driver, it requires the C-extension driver.
 
 The following additional options are supported:
 
 :auto_is_null :: If set to true, makes "WHERE primary_key IS NULL" select the last inserted id.
 :charset :: Same as :encoding, :encoding takes precedence.
 :compress :: Whether to compress data sent/received via the socket connection.
-:config_default_group :: The default group to read from the in the MySQL config file.
+:config_default_group :: The default group to read from the in the MySQL config file, defaults to "client")
 :config_local_infile :: If provided, sets the Mysql::OPT_LOCAL_INFILE option on the connection with the given value.
 :encoding :: Specify the encoding/character set to use for the connection.
 :fractional_seconds :: On MySQL 5.6.5+, this option is recognized and will include fractional seconds in
@@ -264,17 +264,17 @@ The following additional options are supported:
              or an array of symbols or strings (e.g. <tt>:sql_mode=>[:no_zero_date, :pipes_as_concat]</tt>).
 :timeout :: Sets the wait_timeout for the connection, defaults to 1 month.
 :read_timeout :: Set the timeout in seconds for reading back results to a query.
-:connect_timeout :: Set the timeout in seconds before a connection attempt is abandoned.
+:connect_timeout :: Set the timeout in seconds before a connection attempt is abandoned
+                    (may not be supported when using MariaDB 10.2+ client libraries).
+
+The :sslkey, :sslcert, :sslca, :sslcapath, and :sslca options (in that order) are passed to Mysql#ssl_set method
+if either the :sslca or :sslkey option is given.
 
 === mysql2
 
 This is a newer MySQL adapter that does typecasting in C, so it is often faster than the
-mysql adapter.  Supports the same additional options as the mysql adapter, except for :compress, and uses
-:timeout instead of :read_timeout and :connect_timeout.
-
-The following additional options are supported:
-
-:flags :: Override the flags to use for the connection (e.g. ::Mysql2::Client::MULTI_STATEMENTS)
+mysql adapter.  The options given are passed to Mysql2::Client.new, see the mysql2 documentation
+for details on what options are supported.
 
 === odbc 
 
@@ -303,13 +303,15 @@ The following additional options are supported:
 
 === postgres
 
-Requires: pg (or postgres if pg is not available)
+Requires: pg (or postgres-pr/postgres-compat if pg is not available)
 
-The Sequel postgres adapter works with the pg, postgres, and postgres-pr ruby libraries.
+The Sequel postgres adapter works with the pg and postgres-pr ruby libraries.
 The pg library is the best supported, as it supports real bound variables and prepared statements.
 If the pg library is being used, Sequel will also attempt to load the sequel_pg library, which is
 a C extension that optimizes performance when Sequel is used with pg.  All users of Sequel who
-use pg are encouraged to install sequel_pg.
+use pg are encouraged to install sequel_pg.  For users who want to use postgres-pr to avoid issues
+with C extensions, it is recommended to use jeremyevans-postgres-pr, which fixes many issues in
+the upstream postgres-pr gem, and is regularly tested with Sequel.
 
 The following additional options are supported:
 
@@ -318,14 +320,20 @@ The following additional options are supported:
                                 conversion is done, so an error is raised if you attempt to retrieve an infinite
                                 timestamp/date.  You can set this to :nil to convert to nil, :string to leave
                                 as a string, or :float to convert to an infinite float.
+:conn_str :: Use connection string (in form of `host=x port=y ...`). Ignores all other options, only supported with pg
+             library. See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING and 
+             https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS for format and list of supported
+             options.
 :connect_timeout :: Set the number of seconds to wait for a connection (default 20, only respected
                     if using the pg library).
+:driver_options :: A hash of options to pass to the underlying driver (only respected if using the pg library)
 :encoding :: Set the client_encoding to the given string
 :notice_receiver :: A proc that be called with the PGresult objects that have notice or warning messages.
                     The default notice receiver just prints the messages to stderr, but this can be used
                     to handle notice/warning messages differently.  Only respected if using the pg library).
-:sslmode :: Set to 'disable', 'allow', 'prefer', 'require' to choose how to treat SSL (only
+:sslmode :: Set to 'disable', 'allow', 'prefer', 'require', 'verify-ca', or 'verify-full' to choose how to treat SSL (only
             respected if using the pg library)
+:sslrootcert :: Specify the path to the root SSL certificate to use.
 :search_path :: Set to the schema search_path.  This can either be a single string containing the schemas
                 separated by commas (for use via a URL: <tt>postgres:///?search_path=schema1,schema2</tt>), or it
                 can be an array of strings (for use via an option:
@@ -380,24 +388,6 @@ database is used.  Attempts to force the use of more than 1 connection
 can result in weird behavior, since the connections will be to separate
 memory databases.
 
-=== swift
-
-swift is a ruby 1.9+ library, so you'll need to be running ruby 1.9+.  It
-can connect to SQLite, MySQL, and PostgreSQL, and you must specify which
-database using the db_type option.
-
-You need to install one of the swift db adapters
-
-* swift-db-sqlite3
-* swift-db-mysql
-* swift-db-postgres
-
-Examples:
-
-  swift:///?database=:memory:&db_type=sqlite
-  swift://root:root@localhost/test?db_type=mysql
-  swift://root:root@localhost/test?db_type=postgres
-
 === tinytds
 
 Requires: tiny_tds
@@ -411,6 +401,9 @@ options that you may want to set are :login_timeout, :timeout, :tds_version, :az
 
 Other Sequel specific options:
 
+:ansi :: Set to true to enable the ANSI compatibility settings when connecting
+         (ANSI_NULLS, ANSI_PADDING, ANSI_WARNINGS, ANSI_NULL_DFLT_ON, QUOTED_IDENTIFIER,
+         CONCAT_NULL_YIELDS_NULL).
 :server_version :: Override the server version to use (9000000 = SQL Server 2005).
                    This also works on any other adapter that connects to Microsoft
                    SQL Server.
@@ -419,6 +412,3 @@ Other Sequel specific options:
              This should be specified as an integer.  If you plan on setting large
              text or blob values via tinytds, you should use this option or modify
              your freetds.conf file.
-
-The Sequel tinytds adapter requires tiny_tds >= 0.4.5, and if you are using FreeTDS
-0.91, you must at least be using 0.91rc2 (0.91rc1 does not work).