sequel 3.21.0 → 3.39.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, jdbc, 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:
@@ -187,7 +192,7 @@ 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.
+directly to DataObjects, it does no processing of it (other than removing the do: prefix).
 
 Connection string 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
@@ -220,9 +232,9 @@ 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
-jdbc-* gem, for those you need to have the .jar in your CLASSPATH
+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, Derby,
+and JTDS, this 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
@@ -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
 
@@ -345,6 +387,12 @@ swift is a ruby 1.9 only 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
@@ -353,16 +401,29 @@ 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.
+
+Other Sequel specific options:
+
+:textsize :: Override the default TEXTSIZE setting for this connection.  The FreeTDS
+             default is small (around 64000 bytes), but can be set up to around 2GB.
+             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.
+
 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)
+* 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
 
@@ -22,7 +29,7 @@ significantly for placeholders (e.g. :name, $1, ?).  Sequel abstracts all of
 that and allows you to specify placeholders by using the :$name format for
 placeholders, e.g.:
 
-  ds = DB[:items].filter(:name=>:$n)
+  ds = DB[:items].where(:name=>:$n)
 
 == Bound Variables
 
@@ -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.