sequel 3.21.0 → 3.36.0

data/doc/opening_databases.rdoc

@@ -46,6 +46,13 @@ unless the first argument is a hash. So the following statements are equivalent
   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, dbi, jdbc, odbc, and swift 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>). 
+
 == Passing a block to either method
 
 Both the Sequel.connect method and the specialized adapter methods take a block.  If you
@@ -59,24 +66,24 @@ For example:
 
 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
-* :default_schema - The database schema to use by default.
-* :host - The hostname of the database server to which to connect
-* :logger - An array of SQL loggers to log to
-* :loggers - An array of SQL loggers to log to
-* :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)
-* :user - The user account name to use logging in
+:adapter :: The adapter to use
+:database :: The name of the database to which to connect
+:default_schema :: The database schema to use in schema_modification and introspection.
+:host :: The hostname of the database server to which to connect
+:logger :: An array of SQL loggers to log to
+:loggers :: An array of SQL loggers to log to
+: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)
+:user :: The user account name to use logging in
 
 The following options can be specified and are passed to the the database's internal connection pool.
 
-* :after_connect - A proc called after a new connection is made, with the connection object (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)
+:after_connect :: A proc called after a new connection is made, with the connection object (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)
 
 == Adapter specific connection options
 
@@ -131,8 +138,8 @@ Amalgalite is an ruby extension that provides self contained access to SQLite,
 so you don't need to install SQLite separately.  As amalgalite is a file backed
 database, the :host, :user, and :password options are not used.
 
-* :database - The name of the database file
-* :timeout - The busy timeout period given in milliseconds
+:database :: The name of the database file
+:timeout :: The busy timeout period given in milliseconds
 
 Without a database argument, assumes a memory database, so you can do:
 
@@ -145,17 +152,15 @@ the sqlite section below for details.
 
 Requires: db2/db2cli
 
-I'm not even sure exactly how this works, or if it works at all (I've never heard from
-anyone who attempted to use it).  It uses the SQL_HANDLE_DBC constant to
-get a handle, and respects the :database, :user, and :password options.  It doesn't
-appear to respect the :host or :port options.
+This is the older DB2 adapter.  It's recommended you try the ibmdb adapter
+instead for new DB2 work, as it is better supported.
 
 === dbi 
 
 Allows access to a multitude of databases via ruby-dbi.  Additional options:
 
-* :db_type - Specifying 'mssql' allows Microsoft SQL Server specific syntax to
-  be used.  Otherwise has no effect.
+:db_type :: Specifying 'mssql' allows Microsoft SQL Server specific syntax to
+            be used.  Otherwise has no effect.
 
 DBI connection strings are a preprocessed a bit, and are specified with a dbi-
 in front of the protocol.  Examples:
@@ -201,6 +206,13 @@ Requires: fb (using code at http://github.com/wishdev/fb)
 
 Does not support the :port option.
 
+=== ibmdb
+
+requires 'ibm_db'
+
+This connects to DB2 using IBM_DB.  This is the recommended adapter if you are
+using a C-based ruby to connect to DB2.
+
 === informix 
 
 Does not support the :host or :port options.  Depending on the configuration of your server
@@ -221,7 +233,7 @@ Requires: java
 Houses Sequel's JDBC support when running on JRuby.
 Support for individual database types is done using sub adapters.
 There are currently subadapters for PostgreSQL, MySQL, SQLite, H2,
-Oracle, MSSQL, JTDS, and AS400.  All except Oracle, MSSQL, and AS400 can load the
+Oracle, MSSQL, JTDS, AS400, and DB2.  All except Oracle, MSSQL, AS400, and DB2 can load the
 jdbc-* gem, for those you need to have the .jar in your CLASSPATH
 or load the Java class manually before calling Sequel.connect.
 
@@ -246,37 +258,54 @@ Example connection strings:
   jdbc:postgresql://localhost/database?user=username
   jdbc:mysql://localhost/test?user=root&password=root
   jdbc:h2:mem:
+  jdbc:hsqldb:mem:mymemdb
+  jdbc:derby:memory:myDb;create=true
   jdbc:sqlserver://localhost;database=sequel_test;integratedSecurity=true
   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
+
 You can also use JNDI connection strings:
 
   jdbc:jndi:java:comp/env/jndi_resource_name
 
 The following additional options are supported:
 
-* :convert_types - If set to false, does not attempt to convert some Java types to ruby types.
-  Setting to false roughly doubles performance when selecting large numbers of rows.
-  Note that you can't provide this option inside the connection string (as that is passed
-  directly to JDBC), you have to pass it as a separate option.
+:convert_types :: If set to false, does not attempt to convert some Java types to ruby types.
+                  Setting to false roughly doubles performance when selecting large numbers of rows.
+                  Note that you can't provide this option inside the connection string (as that is passed
+                  directly to JDBC), you have to pass it as a separate option.
+:login_timeout :: Set the login timeout on the JDBC connection (in seconds).
 
 === mysql 
 
+Requires: mysqlplus (or mysql if mysqlplus is not available)
+
 The MySQL adapter does not support the pure-ruby MySQL adapter that used to ship with
 ActiveRecord, it requires the native adapter.
 
 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_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.
-* :socket - Can be used to specify a Unix socket file to connect to instead of a TCP host and port.
-* :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.
+: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_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.
+:socket :: Can be used to specify a Unix socket file to connect to instead of a TCP host and port.
+:sql_mode :: Set the sql_mode(s) for a given connection.  Can be single symbol or string,
+             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.
+
+=== 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.
 
 === odbc 
 
@@ -287,8 +316,8 @@ The :database option given ODBC database should be the DSN (Descriptive Service
 
 The :host and :port options are not respected. The following additional options are supported:
 
-* :db_type - Can be specified as 'mssql' or 'progress' to use SQL syntax specific to those databases.
-* :driver - The name of the ODBC driver to utilize.
+:db_type :: Can be specified as 'mssql' or 'progress' to use SQL syntax specific to those databases.
+:driver :: The name of the ODBC driver to utilize.
 
 === openbase 
 
@@ -300,7 +329,11 @@ Requires: oci8
 
 The following additional options are supported:
 
-* :privilege - The Oracle privilege level.
+:autosequence :: Set to true to use Sequel's conventions to guess the sequence to use for datasets.  False
+                 by default.
+:prefetch_rows :: The number of rows to prefetch.  Defaults to 1, a larger number can be specified
+                  and will improve performance when retrieving a large number of rows.
+:privilege :: The Oracle privilege level.
 
 === postgres
 
@@ -308,14 +341,23 @@ Requires: pg (or postgres if pg is not available)
 
 The Sequel postgres adapter works with the pg, postgres, 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.
 
 The following additional options are supported:
 
-* :charset - Same as :encoding, :encoding takes precedence
-* :encoding - Set the client_encoding to the given string
+:charset :: Same as :encoding, :encoding takes precedence
+:encoding :: Set the client_encoding to the given string
+:connect_timeout :: Set the number of seconds to wait for a connection (default 20, only respected
+                    if using the pg library).
+:sslmode :: Set to 'disable', 'allow', 'prefer', 'require' to choose how to treat SSL (only
+            respected if using the pg library)
 
 === sqlite
 
+Requires: sqlite3
+
 As SQLite is a file-based database, the :host and :port options are ignored, and
 the :database option should be a path to the file.
 
@@ -337,7 +379,7 @@ Examples:
 
 The following additional options are supported:
 
-* :timeout - the busy timeout to use in milliseconds (default: 5000).
+:timeout :: the busy timeout to use in milliseconds (default: 5000).
 
 === swift
 
@@ -353,16 +395,21 @@ Examples:
 
 === tinytds
 
+Requires: tiny_tds
+
 Because the underscore is not a valid character in a URI schema, the adapter
 is named tinytds instead of tiny_tds.  The connection options are passed directly
-to tiny_tds, except that the tiny_tds :dataserver and :username options are set to
-the Sequel :host and :user options.  The :host option should be an entry in the
-freetds.conf file, it's not currently possible to a host not present in the
-freetds.conf file.  Some options that you may want to set are
-:login_timeout, :timeout, :appname, and :encoding, see the tiny_tds README for details.
+to tiny_tds, except that the tiny_tds :username option is set to
+the Sequel :user option.  If you want to use an entry in the freetds.conf file, you
+should specify the :dataserver option with that name as the value.  Some other
+options that you may want to set are :login_timeout, :timeout, :tds_version, :azure,
+:appname, and :encoding, see the tiny_tds README for details.
+
 For highest performance, you should disable any identifier output method when
 using the tinytds adapter, which probably means disabling any identifier input method
 as well.  The default for Microsoft SQL Server is to :downcase identifiers on output
 and :upcase them on input, so the highest performance will require changing the setting
 from the default.
 
+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).

data/doc/prepared_statements.rdoc

@@ -3,15 +3,22 @@
 Sequel has support for prepared statements and bound variables.  No matter which
 database you are using, the Sequel prepared statement/bound variable API remains
 the same.  There is native support for prepared statements/bound variables on
-the following databases:
+the following adapters:
 
-* PostgreSQL (using the pg driver, requires type specifiers)
-* MySQL (prepared statements only, as the ruby mysql driver doesn't support
-  bound variables)
-* SQLite
-* JDBC
+* ibmdb (prepared statements only)
+* jdbc
+* mysql (prepared statements only)
+* mysql2 (prepared statements only)
+* oracle (requires type specifiers for nil/NULL values)
+* postgres (when using the pg driver, may require type specifiers)
+* sqlite
+* tinytds
 
-Support on other databases is emulated via string interpolation.
+Support on other adapters is emulated via string interpolation.
+
+You can use the prepared_statements model plugin to automatically use prepared
+statements for some common model actions such as saving or deleting a model
+instance, or looking up a model based on a primary key.
 
 == Placeholders
 
@@ -74,20 +81,19 @@ and update queries, the hash to insert/update is passed to +prepare+:
 
 If you are using the ruby-postgres or postgres-pr driver, PostgreSQL uses the
 default emulated support.  If you are using ruby-pg, there is native support,
-but it requires type specifiers most of the time.  This is easy if you have
-direct control over the SQL string, but since Sequel abstracts that, the types
-have to be specified another way.  This is done by adding a __* suffix to the
-placeholder symbol (e.g. :$name__text, which will be compiled to "$1::text"
-in the SQL).  Prepared statements are always server side.
+but it may require type specifiers on some old versions (generally not anymore).
+You can add a __* suffix to the placeholder symbol to specify a type, which
+casts to that type in the SQL (e.g.  :$name__text, which will be compiled to
+"$1::text" in the SQL).  Prepared statements are always server side.
 
 === SQLite
 
 SQLite supports both prepared statements and bound variables.  Prepared
 statements are cached per connection.
 
-=== MySQL
+=== MySQL/Mysql2
 
-The MySQL ruby driver does not support bound variables, so the the bound
+The MySQL/Mysql2 ruby drivers do not support bound variables, so the bound
 variable methods fall back to string interpolation.  It uses server side
 prepared statements.
 
@@ -99,6 +105,26 @@ over JDBC, you can add the prepareThreshold=N parameter to the connection
 string, which will use a server side prepared statement after N calls to
 the prepared statement.
 
+=== TinyTDS
+
+Uses the sp_executesql stored procedure with bound variables, since
+Microsoft SQL Server doesn't support true prepared statements.
+
+=== IBM_DB
+
+DB2 supports both prepared statements and bound variables.  Prepared
+statement objects are cached per connection.
+
+=== Oracle
+
+Oracle supports both prepared statements and bound variables.  Prepared
+statements (OCI8::Cursor objects) are cached per connection.  If you
+ever plan to use a nil/NULL value as a bound variable/prepared statement
+value, you must specify the type in the placeholder using a __* suffix.
+You can use any of the schema types that Sequel supports, such as
+:$name__string or :$num__integer.  Using blobs as bound variables is
+not currently supported.
+
 === All Others
 
 Support is emulated using interpolation.

data/doc/querying.rdoc

@@ -167,17 +167,26 @@ It's also common to want to order such a map, so Sequel provides a
 Sequel makes it easy to take an SQL query and return it as a ruby hash,
 using the +to_hash+ method:
 
-  artist_names = Artist.to_hash(:name, :id)
+  artist_names = Artist.to_hash(:id, :name)
   # SELECT * FROM artists
-  => {"YJM"=>1, "AS"=>2}
+  => {1=>"YJM", 2=>"AS"}
 
 As you can see, the +to_hash+ method uses the first symbol as the key
 and the second symbol as the value.  So if you swap the two arguments the hash
 will have its keys and values transposed:
 
-  artist_names = Artist.to_hash(:id, :name)
+  artist_names = Artist.to_hash(:name, :id)
   # SELECT * FROM artists
-  => {1=>"YJM", 2=>"AS"}
+  => {"YJM"=>1, "AS"=>2}
+
+Now what if you have multiple values for the same key?  By default, +to_hash+
+will just have the last matching value.  If you care about all matching values,
+use +to_hash_groups+, which makes the values of the array an array of matching
+values, in the order they were received:
+
+  artist_names = Artist.to_hash_groups(:name, :id)
+  # SELECT * FROM artists
+  => {"YJM"=>[1, 10, ...], "AS"=>[2, 20, ...]}
 
 If you only provide one argument to +to_hash+, it uses the entire hash
 or model object as the value:
@@ -186,6 +195,12 @@ or model object as the value:
   # SELECT * FROM artists
   => {"YJM"=>{:id=>1, :name=>"YJM"}, "AS"=>{:id=>2, :name=>"AS"}}
 
+and +to_hash_groups+ works similarly:
+
+  artist_names = DB[:artists].to_hash_groups(:name)
+  # SELECT * FROM artists
+  => {"YJM"=>[{:id=>1, :name=>"YJM"}, {:id=>10, :name=>"YJM"}], ...}
+
 Model datasets have a +to_hash+ method that can be called without any
 arguments, in which case it will use the primary key as the key and
 the model object as the value.  This can be used to easily create an
@@ -196,6 +211,9 @@ identity map:
   => {1=>#<Artist @values={:id=>1, :name=>"YGM"}>,
       2=>#<Artist @values={:id=>2, :name=>"AS"}>}
 
+There is no equivalent handling to +to_hash_groups+, since there would
+only be one matching record, as the primary key must be unique.
+
 Note that +to_hash+ never modifies the columns selected.  However, just
 like Sequel has a +select_map+ method to modify the columns selected and
 return an array, Sequel also has a +select_hash+ method to modify the
@@ -205,6 +223,12 @@ columns selected and return a hash:
   # SELECT name, id FROM artists
   => {"YJM"=>1, "AS"=>2}
 
+Likewise, +select_hash_groups+ also exists:
+
+  artist_names = Artist.select_hash_groups(:name, :id)
+  # SELECT name, id FROM artists
+  => {"YJM"=>[1, 10, ...], "AS"=>[2, 20, ...]}
+
 == Modifying datasets 
 
 Note that the retrieval methods discussed above just return

data/doc/reflection.rdoc

@@ -4,9 +4,9 @@ Sequel supports reflection information in multiple ways.
 
 == Adapter in Use
 
-You can get the adapter in use using Database.adapter_scheme.  As this is a class method, you generally need to do DB.class.adapter_scheme:
+You can get the adapter in use using Database#adapter_scheme:
 
-  DB.class.adapter_scheme # e.g. :postgres, :jdbc, :odbc
+  DB.adapter_scheme # e.g. :postgres, :jdbc, :odbc
 
 == Database Connected To
 
@@ -16,18 +16,44 @@ In some cases, the adapter scheme will be the same as the database to which you
 
 == Tables in the Database
 
-On many database types/adapters, Database#tables exists and gives an array of table name symbols:
+Database#tables gives an array of table name symbols:
 
   DB.tables # [:table1, :table2, :table3, ...]
 
+== Views in the Database
+
+Database#views and gives an array of view name symbols:
+
+  DB.views # [:view1, :view2, :view3, ...]
+
 == Indexes on a table
 
-On a few database types/adapters, Database#indexes takes a table name gives a hash of index information.  Keys are index names, values are subhashes with the keys :columns and :unique :
+Database#indexes takes a table name gives a hash of index information.  Keys are index names, values are subhashes with the keys :columns and :unique :
 
   DB.indexes(:table1) # {:index1=>{:columns=>[:column1], :unique=>false}, :index2=>{:columns=>[:column2, :column3], :unique=>true}}
 
 Index information generally does not include partial indexes, functional indexes, or indexes on the primary key of the table.
 
+== Foreign Key Information for a Table
+
+Database#foreign_key_list takes a table name and gives an array of hashes of foreign key information:
+
+  DB.foreign_key_list(:table1) # [{:columns=>[:column1], :table=>:referenced_table, :key=>[:referenced_column1]}]
+
+At least the following entries will be present in the hash:
+
+:columns :: An array of columns in the given table
+:table :: The table referenced by the columns
+:key :: An array of columns referenced (in the table specified by :table), but can be nil on certain adapters
+        if the primary key is referenced.
+
+The hash may also contain entries for:
+
+:deferrable :: Whether the constraint is deferrable
+:name :: The name of the constraint
+:on_delete :: The action to take ON DELETE
+:on_update :: The action to take ON UPDATE
+
 == Column Information for a Table
 
 Database#schema takes a table symbol and returns column information in an array with each element being an array with two elements.  The first elements of the subarray is a column symbol, and the second element is a hash of information about that column.  The hash should include the following keys:

data/doc/release_notes/3.22.0.txt

@@ -0,0 +1,39 @@
+= New Features
+
+* Support COLLATE in column definitions.  At least MySQL and Microsoft
+  SQL Server support them, and PostgreSQL 9.1 should as well.
+
+* When connecting to Microsoft SQL Server, you can use the
+  mssql_unicode_strings accessor to turn of the default usage
+  of unicode strings (N'') and use regular strings (''). This
+  can improve performance, but changes the behavior.  It's
+  set to true by default for backwards compatibility.  You can
+  change it at both the dataset and database level:
+
+    DB.mssql_unicode_strings = false # default for datasets
+    dataset.mssql_unicode_strings = false # just this dataset
+
+* In the oracle adapter, if Sequel.application_timezone is :utc, set
+  the timezone for the connection to use the 00:00 timezone.
+
+= Other Improvements
+
+* In the single_table_inheritance plugin, correctly handle a
+  multi-level class hierarchy so that loading instances from a
+  middle level of the hierarchy can return instances of subclasses.
+
+* Don't use a schema when creating a temporary table, even if
+  default_schema is set.
+
+* Fix the migrator when a default_schema is used.
+
+* In the ado adapter, assume a connection to SQL Server if the
+  :conn_string is given and doesn't indicate Access/Jet.
+
+* Fix fetching rows in the tinytds adapter when the
+  identifier_output_method is nil.
+
+* The tinytds adapter now checks for disconnect errors, but it might
+  not be reliable until the next release of tiny_tds.
+
+* The odbc adapter now handles ODBC::Time instances correctly.