sequel 3.40.0 → 3.41.0

data/CHANGELOG

@@ -1,3 +1,43 @@
+=== 3.41.0 (2012-11-01)
+
+* Add bin/sequel usage guide (jeremyevans)
+
+* Make Dataset#reverse and #reverse_order accept virtual row blocks (jeremyevans)
+
+* Add Sequel.delay for generic delayed evaluation (jeremyevans)
+
+* Make uniqueness validations correctly handle nil values (jeremyevans)
+
+* Support :unlogged option for create_table on PostgreSQL (JonathanTron) (#575)
+
+* Add ConnectionPool#pool_type to get the type of connection pool in use (jeremyevans)
+
+* Explicitly mark primary keys as NOT NULL on SQLite (jeremyevans)
+
+* Add support for renaming primary key columns on MySQL (jeremyevans)
+
+* Add connection_validator extension for automatically checking connections and transparently handling disconnects (jeremyevans)
+
+* Add Database#valid_connection? for checking whether a given connection is valid (jeremyevans)
+
+* Make dataset.limit(nil, nil) reset offset as well as limit (jeremyevans) (#571)
+
+* Support IMMEDIATE/EXCLUSIVE/DEFERRED transaction modes on SQLite (Eric Wong)
+
+* Major change in the Database <-> ConnectionPool interface (jeremyevans)
+
+* Make touch plugin handle touching of many_*_many associations (jeremyevans)
+
+* Make single_table_inheritance plugin handle non-bijective mappings (hannesg) (#567)
+
+* Support foreign key parsing on MSSQL (munkyboy) (#564)
+
+* Include SQL::AliasMethods in most pg_* extension objects (treydempsey, jeremyevans) (#563)
+
+* Handle failure to create a prepared statement better in the postgres, mysql, and mysql2 adapters (jeremyevans) (#560)
+
+* Treat clob columns as strings instead of blobs (jeremyevans)
+
 === 3.40.0 (2012-09-26)
 
 * Add a cubrid adapter for accessing CUBRID databases via the cubrid gem (jeremyevans)

data/README.rdoc

@@ -71,7 +71,7 @@ Sequel includes an IRB console for quick access to databases (usually referred t
 
 You get an IRB session with the database object stored in DB.
 
-In addition to providing an IRB shell (the default behavior), bin/sequel also has support for migrating databases (-m and -M), dumping schema migrations (-d and -D), and copying databases (-C).
+In addition to providing an IRB shell (the default behavior), bin/sequel also has support for migrating databases, dumping schema migrations, and copying databases.  See the {bin/sequel guide}[link:files/doc/bin_sequel_rdoc.html] for more details.
 
 == An Introduction
 
@@ -242,7 +242,7 @@ After filtering, you can retrieve the matching records by using any of the retri
 
   my_posts.each{|row| p row}
   
-See the doc/dataset_filtering.rdoc file for more details.
+See the {Dataset Filtering}[link:files/doc/dataset_filtering_rdoc.html] file for more details.
 
 === Summarizing Records
 

data/doc/advanced_associations.rdoc

@@ -65,6 +65,18 @@ Remember, using +eager_graph+ is generally only necessary when you need to
 filter/order based on columns in an associated table, it is recommended to
 use +eager+ for eager loading if possible.
 
+One advantage of using +eager_graph+ is that you can easily filter/order
+on columns in an associated table on a per-query basis, using regular
+Sequel dataset methods.  For example, if you only want to retrieve artists
+who have albums that start with A, and eager load just those albums,
+ordered by the albums name, you can do:
+
+  albums = Artist.
+    eager_graph(:albums).
+    where(Sequel.like(:albums__name, 'A%')).
+    order(:albums__name).
+    all
+
 For lazy loading (e.g. Model[1].association), the <tt>:dataset</tt> option can be used
 to specify an arbitrary dataset (one that uses different keys, multiple keys,
 joins to other tables, etc.).

data/doc/bin_sequel.rdoc

@@ -0,0 +1,144 @@
+= bin/sequel
+
+bin/sequel is the name used to refer to the "sequel" command line tool that ships with the sequel gem.  By default, bin/sequel provides an IRB shell with the +DB+ constant set to a Sequel::Database object created using the database connection string provided on the command line.  For example, to connect to a new in-memory SQLite database using the sqlite adapter, you can use the following:
+
+  sequel sqlite:/
+
+This is very useful for quick testing of ideas, and does not affect the environment, since the in-memory SQLite database is destroyed when the program exits.
+
+== Running from a git checkout
+
+If you've installed the sequel gem, then just running "sequel" should load the program, since rubygems should place the sequel binary in your load path.  However, if you want to run bin/sequel from the root of a repository checkout, you should probably do:
+
+  ruby -I lib bin/sequel
+
+The -I lib makes sure that you are using the repository checkout's code.
+
+== Choosing the Database to Connect to
+
+=== Connection String
+
+In general, you probably want to provide a connection string argument to bin/sequel, indicating the adapter and database connection information you want to use.  For example:
+
+  sequel sqlite:/
+  sequel postgres://user:pass@host/database_name
+  sequel mysql2://user:pass@host/database_name
+
+See the {Connecting to a database guide}[link:files/doc/opening_databases_rdoc.html] for more details about and examples of connection strings.
+
+=== YAML Connection File
+
+Instead of specifying the database connection using a connection string, you can provide the path to a YAML configuration file containing the connection information.  This YAML file can contain a single options hash, or it can contain a nested hash, where the top-level hash uses environment keys with hash values for
+each environment.  Using the -e option with a yaml connection file, you can choose which environment to use if using a nested hash.
+
+  sequel -e production config/database.yml
+
+Note that bin/sequel does not directly support ActiveRecord YAML configuration files, as they use different names for some options.
+
+=== Mock Connection
+
+If you don't provide a connection string or YAML connection file, Sequel will start with a mock database.  The mock database allows you to play around with Sequel without any database at all, and can be useful if you just want to test things out and generate SQL without actually getting results from a database.
+
+  sequel
+
+Sequel also has the ability to use the mock adapter with database-specific syntax, allowing you to pretend you are connecting to a specific type of database without actually connecting to one.  To do that, you need to use a connection string:
+
+  sequel mock://postgres
+
+== Not Just an IRB shell
+
+bin/sequel is not just an IRB shell, it can also do far more.
+
+=== Execute Code
+
+bin/sequel can also be used to execute other ruby files with +DB+ preset to the database given on the command line:
+
+  sequel postgres://host/database_name path/to/some_file.rb
+
+On modern versions of Linux, this means that you can use bin/sequel in a shebang line:
+
+  #!/path/to/bin/sequel postgres://host/database_name
+
+If you want to quickly execute a small piece of ruby code, you can use the -c option:
+
+  sequel -c "p DB.tables" postgres://host/database_name
+
+Similarly, if data is piped into bin/sequel, it will be executed:
+
+  echo "p DB.tables" | sequel postgres://host/database_name
+
+=== Migrate Databases
+
+With -m option, Sequel will migrate the database given using the migration directory provided by -m:
+
+  sequel -m /path/to/migrations/dir postgres://host/database
+
+You can use the -M attribute to set the version to migrate to:
+
+  sequel -m /path/to/migrations/dir -M 3 postgres://host/database
+
+See the {migration guide}[link:files/doc/migration_rdoc.html] for more details about migrations.
+
+=== Dump Schemas
+
+Using the -d or -D options, Sequel will dump the database's schema in Sequel migration format to the standard output:
+
+  sequel -d postgres://host/database
+
+To save this information to a file, use a standard shell redirection:
+
+  sequel -d postgres://host/database > /path/to/migrations/dir/001_base_schema.rb
+
+The -d option dumps the migration in database-independent format, the -D option dumps it in database-specific format.
+
+The -S option dumps the schema cache for all tables in the database, which can speed up the usage of Sequel with models when using the schema_caching extension.  You should provide this option with the path to which to dump the schema:
+
+  sequel -S /path/to/schema_cache.db postgres://host/database
+
+=== Copy Databases
+
+Using the -C option, Sequel can copy the contents of one database to another, even between different database types.  Using this option, you provide two connection strings on the command line:
+
+  sequel -C mysql://host1/database postgres://host2/database2
+
+This copies the table structure, table data, indexes, and foreign keys from the MySQL database to the PostgreSQL database.
+
+== Other Options
+
+Other options not mentioned above are explained briefly here.
+
+=== -E
+
+-E logs all SQL queries to the standard output, so you can see all SQL that Sequel is sending the database.
+
+=== -I include_directory
+
+-I is similar to ruby -I, and specifies an additional $LOAD_PATH directory.
+
+=== -l log_file
+
+-l is similar to -E, but logs all SQL queries to the given file.
+
+=== -L load_directory
+
+-L loads all *.rb files under the given directory.  This is usually used to load Sequel::Model classes into bin/sequel.
+
+=== -N
+
+-N skips testing the connection when creating the Database object.  This is rarely needed.
+
+=== -r require_lib
+
+-r is similar to ruby -r, requiring the given library.
+
+=== -t
+
+-t tells bin/sequel to output full backtraces in the case of an error, which can aid in debugging.
+
+=== -h
+
+-h prints the usage information for bin/sequel.
+
+=== -v
+
+-v prints the Sequel version in use.

data/doc/migration.rdoc

@@ -524,7 +524,7 @@ with the database independent ruby class types, while <tt>-D</tt> will use
 the +column+ method with string types.
 
 Note that Sequel cannot dump constraints other than primary key and possibly
-foreign key constraints constraints.  If you are using database features such
+foreign key constraints.  If you are using database features such
 as constraints or triggers, you should use your database's dump and restore
 programs instead of Sequel's schema dumper.
 

data/doc/object_model.rdoc

@@ -395,6 +395,35 @@ These objects are usually used as values in queries:
 
   DB[:table].insert(:time=>Sequel::CURRENT_TIMESTAMP)
 
+=== Sequel::SQL::DelayedEvaluation
+
+Sequel::SQL::DelayedEvaluation objects represent an evaluation that is delayed
+until query literalization.
+
+  Sequel::SQL::DelayedEvaluation.new(proc{some_model.updated_at})
+
+The following shortcut exists for creating Sequel::SQL::DelayedEvaluation
+objects:
+
+  Sequel.delay{some_model.updated_at}
+
+Note how Sequel.delay requires a block, while Sequel::SQL::DelayedEvaluation.new
+accepts a generic callable object.
+
+Let's say you wanted a dataset for the number of objects greater than some
+attribute of another object:
+
+  ds = DB[:table].where{updated_at > some_model.updated_at}
+
+The problem with the above query is that it evaluates "some_model.updated_at"
+statically, so if you change some_model.updated_at later, it won't affect this
+dataset.  You can use Sequel.delay to fix this:
+
+  ds = DB[:table].where{updated_at > Sequel.delay{some_model.updated_at}}
+
+This will evaluate "some_model.updated_at" every time you literalize the
+dataset (usually every time it is executed).
+
 === Sequel::SQL::Function
 
 Sequel::SQL::Function objects represents database function calls, which take a function

data/doc/release_notes/3.41.0.txt

@@ -0,0 +1,155 @@
+= New Features
+
+* A connection_validator extension has been added, which
+  automatically determines if connections checked out from the pool
+  are still valid.  If they are not valid, the connection is
+  disconnected and another connection is used automatically,
+  transparent to user code.
+
+  Checking if connections are valid requires a query, so this
+  extension causes a performance hit.  For that reason, connections
+  are only checked by default if they have been inactive for more than
+  a configured amount of time (1 hour by default).  You can choose to
+  validate connections on every checkout via:
+
+    DB.pool.connection_validation_timeout = -1
+
+  However, this can cause a substantial performance hit unless you are
+  purposely using coarse connection checkouts via manual calls to
+  Database#synchronize (for example, in a Rack middleware).  Using
+  coarse checkouts can greatly reduce the amount of concurrency that
+  Sequel supports (for example, limiting the number of concurrent
+  requests to the number of database connections), so this method is
+  not without its tradeoffs.
+
+* Sequel.delay has been added for a generic form of delayed
+  evaluation.  This method takes a block and delays evaluating it
+  until query literalization.  By default, Sequel evaluates most
+  arguments immediately:
+
+    foo = 1
+    ds = DB[:bar].where(:baz=>foo)
+    # SELECT * FROM bar WHERE (baz = 1)
+    foo = 2
+    ds
+    # SELECT * FROM bar WHERE (baz = 1)
+
+  Using Sequel.delay, you can delay the evaluation:
+
+    foo = 1
+    ds = DB[:bar].where(:baz=>Sequel.delay{foo})
+    # SELECT * FROM bar WHERE (baz = 1)
+    foo = 2
+    ds
+    # SELECT * FROM bar WHERE (baz = 2)
+
+* Sequel now supports the :unlogged option when creating tables on
+  PostgreSQL, to create an UNLOGGED table.
+
+* On SQLite, Database#transaction now supports a :mode option for
+  setting up IMMEDIATE/EXCLUSIVE SQLite transactions.  Sequel also
+  supports a Database#transaction_mode accessor for setting the
+  default transaction mode on SQLite.
+
+* Most pg_* extension objects (e.g. PGArray) now support the #as
+  method for creating an SQL::AliasedExpression object.
+
+* The single_table_inheritance plugin now supports non-bijective
+  mappings.  In lay terms, this means that a one-to-one mapping
+  of column values to classes is no longer required.  You can now
+  have multiple column values that map to a single class in the
+  :model_map option, and specify a :key_chooser option to choose
+  which column value to use for the given model class.
+
+* The touch plugin now handles the touching of many_to_many
+  associations, and other associations that use joined datasets.
+
+* ConnectionPool#pool_type has been added. It returns a symbol
+  representing the type of connection pool in use (similar to
+  Database#database_type).
+
+* Database#valid_connection? has been added for checking if a given
+  connection is still valid.
+
+* Database#disconnect_connection is now part of the public API, and
+  can be used to disconnect a given connection.
+
+= Other Improvements
+
+* Uniqueness validation now correctly handles nil values.
+  Previously, it checked the underlying table for other rows where
+  the column IS NULL, but that is incorrect behavior.  Sequel's new
+  (correct) behavior is to skip the uniqueness check if the column
+  is nil.
+
+* Foreign key parsing is now supported on Microsoft SQL Server.
+
+* Dataset#reverse and #reverse_order now accept virtual row blocks.
+
+* Changing the name of the primary key column, and possibly other
+  schema changes on the primary key column, are now supported on
+  MySQL.
+
+* Primary key columns are now specifically marked as NOT NULL on
+  SQLite, as non-integer primary keys on SQLite are not considered
+  NOT NULL by default.
+
+* Failure to create a native prepared statement is now handled
+  better in the postgres, mysql, and mysql2 adapters.
+
+* Firebird now emulates selecting data without an underlying table
+  (e.g. DB.get(1)).
+
+* Finding the name of the constraint that sets column defaults on
+  Microsoft SQL Server now works correctly on JRuby 1.7.
+
+* An additional type of disconnect error is now recognized in the
+  jdbc/sqlserver adapter.
+
+* Many adapters have been fixed so that they don't raise an exception
+  if trying to disconnect an already disconnected connection.
+
+* Many adapters have been fixed so that
+  Database#log_connection_execute logs and executes the given SQL
+  on the connection.
+
+* Many adapters have been fixed so that
+  Database#database_error_classes returns an array of database
+  exception classes for that adapter.
+
+* Database#log_exception now handles a nil exception message.
+
+* Dataset#limit(nil, nil) now resets offset in addition to limit, but
+  you should still use Dataset#unlimited instead.
+
+* A bin/sequel usage quide has been added to the documentation.
+
+= Backwards Compatibility
+
+* Sequel now treats clob columns as strings instead of blobs
+  (except on DB2 when use_clob_as_blob = true).  This can make it
+  so the values are returned as strings instead of SQL::Blob values.
+  Since SQL::Blob is a String subclass, this generally will
+  not affect user code unless you are passing the values as input
+  to a separate blob column.
+
+* The Database <-> ConnectionPool interface was completely changed.
+  Sequel no longer supports custom connection procs or disconnection
+  procs in the connection pools.  The :disconnection_proc Database
+  option is no longer respected, and blocks passed to Database.new
+  are now ignored.
+
+  This change should not be user-visible, but if you had any code
+  that was monkeying with the connection pool internals, you may
+  need to modify it.
+
+* Code that was using the uniqueness check to also check for presence
+  should add a separate check for presence.  Such code was broken,
+  as it only worked if there was already a NULL column value in the
+  table. If you were relying on this broken behavior, you should
+  clean up the NULL data in the column and then mark the database
+  column as NOT NULL.
+
+* If you have code that specifically abuses the fact that non-integer
+  primary keys on SQLite allow NULL values by default, it will no
+  longer work.

data/lib/sequel/adapters/ado.rb

@@ -57,6 +57,10 @@ module Sequel
         handle
       end
       
+      def disconnect_connection(conn)
+        conn.Close
+      end
+
       # Just execute so it doesn't attempt to return the number of rows modified.
       def execute_ddl(sql, opts={})
         execute(sql, opts)
@@ -113,10 +117,6 @@ module Sequel
         [::WIN32OLERuntimeError]
       end
 
-      def disconnect_connection(conn)
-        conn.Close
-      end
-
       def disconnect_error?(e, opts)
         super || (e.is_a?(::WIN32OLERuntimeError) && e.message =~ DISCONNECT_ERROR_RE)
       end