colincasey-sequel 2.10.0 → 2.10.1

data/doc/release_notes/2.6.0.txt

@@ -0,0 +1,157 @@
+New Features
+------------
+
+* Schema parsing was refactored, resulting in a huge speedup when
+  using MySQL.  MySQL now uses the DESCRIBE statement instead of the
+  INFORMATION_SCHEMA.  PostgreSQL now uses the pg_* system catalogs
+  instead of the INFORMATION schema.
+
+* The schema information now includes the :primary_key field.  Models
+  now use this field to automatically determine the primary key for
+  a table, so it no longer needs to be specified explicitly.  Models
+  even handle the composite primary key case.
+
+* The raise_on_typecast_failure switch was added, with it being true
+  by default (so no change in behavior).  This allows the user to
+  silently ignore errors when typecasting fails, at the global, class,
+  and instance levels.
+
+    Sequel::Model.raise_on_typecast_failure = false # Global
+    Artist.raise_on_typecast_failure = true # Class
+    artist = Artist.new
+    artist.raise_on_typecast_failure = false # Instance
+
+    Album.raise_on_typecast_failure = true
+    Album.new(:numtracks=>'a') # => raises Sequel::Error::InvalidValue
+    Album.raise_on_typecast_failure = false
+    Album.new(:numtracks=>'a') # => #<Album @values={:numtracks=>"a"}>
+
+* Associations' orders are now respected when eager loading via
+  eager_graph.  Sequel will qualify the columns in the order with
+  the alias being used, so you can have overlapping columns when
+  eager loading multiple associations.
+
+    Artist.one_to_many :albums, :order=>:name
+    Album.one_to_many :tracks, :order=>:number
+    Artist.order(:artists__name).eager_graph(:albums=>:tracks).sql
+    # => ... ORDER BY artists.name, albums.name, tracks.number
+
+* The support for CASE expressions has been enhanced by allowing the
+  use of an optional expression:
+
+    {1=>2}.case(0, :x)
+    # => CASE x WHEN 1 THEN 2 ELSE 0 END
+    [[:a, 1], [:b, 2], [:c, 3]].case(4, :y)
+    # => CASE y WHEN a THEN 1 WHEN b THEN 2 WHEN c THEN 3 ELSE 4 END
+
+  Previously, to get something equivalent to this, you had to do:
+
+    {{:x=>1}=>2}.case(0)
+    # => CASE WHEN (x = 1) THEN 2 ELSE 0 END
+    [[{:y=>:a}, 1], [{:y=>:b}, 2], [{:y=>:c}, 3]].case(4)
+    # => CASE WHEN (y = a) THEN 1 WHEN (y = b) THEN 2 WHEN (y = c)
+         THEN 3 ELSE 4 END
+
+* You can now change the NULL/NOT NULL value of an existing column
+  using the set_column_allow_null method.
+
+    # Set NOT NULL
+    DB.alter_table(:artists){set_column_allow_null :name, false}
+    # Set NULL
+    DB.alter_table(:artists){set_column_allow_null :name, true}
+
+* You can now get the schema information for a table in a non-public
+  schema in PostgreSQL using the implicit :schema__table syntax.
+  Before, the :schema option had to be given explicitly to
+  Database#schema.  This allows models to get schema information for
+  tables outside the public schema.
+
+* Transactions are now supported on MSSQL.
+
+* Dataset#tables now returns all tables in the database for MySQL
+  databases accessed via JDBC.
+
+* Database#drop_view can now drop multiple views at once.
+
+Other Improvements
+------------------
+
+* The SQLite adapter now respects the Sequel.datetime_class option
+  for timestamp and datetime columns.
+
+* Adding a unique constraint no longer explicity creates a unique
+  index.  If you want a unique index, use index :unique=>true.
+
+* If no language is specified when creating a full text index on
+  PostgreSQL, the simple language is assumed.
+
+* Errors when typecasting fails are now Sequel::Error::InvalidValue
+  instead of the more generic Sequel::Error.
+
+* Specifying constraints now works correctly for all types of
+  arguments.  Previously, it did not work unless a block or
+  interpolated string were used.
+
+* Loading an association with the same name as a table in the FROM
+  clause no longer causes an error.
+
+* When eagerly loading many_to_one associations where no objects have
+  an associated object, the negative lookup is now cached.
+
+* String keys can now be used with Dataset#multi_insert, just like
+  they can be used for Dataset#insert.
+
+* Dataset#join_table now generates the correct SQL when doing the
+  first join to a dataset where the first source is a dataset, when
+  an unqualified column is used in the conditions.
+
+* Cascading associations after *_to_many associations can now be
+  eagerly loaded via eager_graph.
+
+* Eagerly loading *_to_many associations that are cascaded behind a
+  many_to_one association now have their duplicates removed if a
+  cartesian product join is done.
+
+* The SQLite adapter now uses string literals in all of the AS
+  clauses.  While the SQL standard specifies that identifiers should
+  be used, SQLite documentation explicitly states that string
+  literals are expected (though it generally works with identifiers
+  by converting them implicitly).
+
+* Database methods that modify the schema now remove the cached
+  schema entry.
+
+* The hash keys that Database#schema returns when no table is
+  requested are now always supposed to be symbols.
+
+* The generation of SQL for composite foreign keys on MySQL has been
+  fixed.
+
+* A schema.rdoc file was added to the documentation explaining the
+  various parts of Sequel related to schema generation and
+  modification and how they interact
+  (http://sequel.rubyforge.org/rdoc/files/doc/schema_rdoc.html).
+
+* The RDoc template for the website was changed from the default
+  template to the hanna template.
+
+Backwards Compatibility
+-----------------------
+
+* The :numeric_precision and :max_chars schema entries have been
+  removed.  Use the :db_type entry to determine this information,
+  if available.
+
+* The SQLite adapter used to always return Time instances for
+  timestamp types, even if Sequel.datetime_class was DateTime.  For
+  datetime types it always returned a DateTime instance.  It
+  now returns an instance of Sequel.datetime_class in both cases.
+
+* It's possible that the including of associations' orders when eager
+  loading via eager_graph could cause problems.  You can use the
+  :order_eager_graph=>false option to not use the :order option when
+  eager loading via :eager_graph.
+
+* There were small changes in SQL creation where the AS keyword is
+  now used explicitly.  These should have no effect, but could break
+  tests for explicit SQL.

data/doc/release_notes/2.7.0.txt

@@ -0,0 +1,166 @@
+Performance Optimizations
+-------------------------
+
+* Fetching a large number of records with the PostgreSQL adapter is
+  significantly faster (up to 3-4 times faster than before).
+
+* Instantiating model objects has been made much faster, as many
+  options (such as raise_on_save_failure) are now lazily loaded, and
+  hook methods are now much faster if no hooks have been defined for
+  that type of hook.
+
+New Association Options
+-----------------------
+
+* The :eager_grapher option has been added allowing you to supply
+  your own block to implement eager loading via eager_graph.
+
+* many_to_one and one_to_many associations now have a :primary_key
+  option, specifying the name of the column that the :key option
+  references.
+
+* many_to_many associations now have :left_primary_key and
+  :right_primary_key options, specifying the columns that :left_key
+  and :right_key reference, respectively.
+
+* many_to_many associations now have a :uniq option, that adds an
+  :after_load callback that makes the returned array of objects
+  unique.
+
+Other New Features
+------------------
+
+* Dataset#set_graph_aliases now allows you to supply a third argument
+  for each column you want graph into the dataset, allowing you to use
+  arbitrary SQL expressions that are graphed into the correct table:
+
+    ds.set_graph_aliases!(:a=>[:b, :c], :d=>[:e, :f, 42])
+    # SELECT b.c AS a, 42 AS d FROM ...
+    ds.first # => {:b=>{:c=>?}, :e=>{:f=>42}}
+
+* Dataset#add_graph_aliases was added, that adds additional graph
+  aliases instead of replacing the existing ones (as
+  #set_graph_aliases does).  It's basically the equivalent of
+  select_more for graphs.
+
+* Dataset#join_table changed it's final argument from a symbol
+  specifying a table name to an option hash (with backwards
+  compatibility kept), and adds support for a :implicit_qualifier
+  option, which it uses instead of the last joined table to
+  qualify columns.
+
+* Association's :after_load callbacks are now called when eager
+  loading via eager (but not when eager loading via eager_graph).
+
+* Any expression can now be used as the argument to Symbol#like,
+  which means that you can pattern match columns to other columns.
+  Before, it always transformed the argument to a string.
+
+    :a.like(:b)
+    # 2.6.0: a LIKE 'b'
+    # 2.7.0: a LIKE b
+
+* Array#sql_array was added, allowing you to specify that an array
+  in ruby be treated like an array in SQL.  This is true anyway,
+  except for arrays of all two pairs, which are treated like hashes,
+  for specifying multiple conditions with the same key:
+
+   DB[:foo].filter([:a,:b] => [[1,2],[3,4]].sql_array)
+   # => SELECT * FROM foo WHERE ((a, b) IN ((1, 2), (3, 4)))
+
+* ComplexExpression#== and #sql? were added, allowing for easier
+  testing.
+
+* Full text searching on PostgreSQL now joins multiple columns with
+  a space, to prevent joining border words, and it works when there
+  is a match in one column but the other column is NULL.
+
+Other Improvements
+------------------
+
+* Instance methods added by creating associations are added to an
+  anonymous module included by the class, so they can be overridden
+  in the class while still allowing the use of super to get the
+  default behavior (this is similar to column accessor methods).
+
+* Many improvements were added to support using multiple schemas in
+  PostgreSQL.
+
+* Model::Validation::Errors objects are now more compatible with
+  Rails, by adding a #count method and making #on return nil if there
+  are no error messages for that attribute.
+
+* Serialized columns in models are no longer typecast.
+
+* Associations are now inherited when a model class is subclassed.
+
+* Many improvements were made that should make adding custom
+  association types easier.
+
+* A corner case in eager_graph where the wrong table name would be
+  used to qualify a column name has been fixed.
+
+* Dataset's cached column information is no longer modified if #each
+  is called with an option that modifies the columns.
+
+* You should now be able to connect to Oracle via the JDBC adapter,
+  and with the same support it has when using the oracle adapter.
+
+* Model.association_reflections is now a public methods, so you can
+  grab a hash of all association reflections at once (keyed by
+  association name symbol).
+
+* The :encoding/:charset option now works in the PostgreSQL adapter
+  if the postgres-pr driver is used.
+
+* The numeric(x,y) type is now interpreted as decimal.
+
+Backwards Compatibilty
+----------------------
+
+* The first argument to Model#initialize must be a hash, you can no
+  longer use nil.  For example, the following code will break if
+  :album is not in params:
+
+    Album.new(params[:album])
+
+  Additionally, Model#initialize does not call the block if the
+  second argument is true.
+
+* The Sequel::Model.lazy_load_schema setting was removed.  It should
+  no longer be necessary now that schema loading is relatively speedy,
+  and schemas can be loaded at startup and cached.
+
+* The PostgreSQL adapter will default to using a unix socket in /tmp
+  if no host is specified.  Before, a TCP/IP socket to localhost was
+  used if no host was specified.  This change makes Sequel operate
+  similarly to the PostgreSQL command line tools.
+
+* The ASSOCIATION_TYPES constant has changed from an array to a hash
+  and it has been moved.  The RECIPROCAL_ASSOCIATIONS constant has
+  been removed.  This is unlikely to matter unless you were using
+  custom association types.
+
+* The PostgreSQL adapter now sets the PostgreSQL DateStyle, in order
+  to implement an optimization.  To turn this off, set
+  Sequel::Postgres.use_iso_date_format = false.
+
+* When using the PostgreSQL adapter, in many places the schema is
+  specified explicitly.  If you do not specify a schema, a default
+  one is used (public by default).  If you use a schema other than
+  public for your work, use Database#default_schema= to set it.  For
+  any table outside of the default schema, you should specify the
+  schema explicitly, even if it is in the PostgreSQL search_path.
+
+* Model::Validation::Errors#on now returns nil instead of [] if there
+  are no errors for an attribute.
+
+* Hooks added to a superclass after a subclass has been created no
+  longer have an effect on the subclass.
+
+* The Postgres.string_to_bool method has been removed.
+
+* PostgreSQL full text searching now always defaults to using the
+  simple dictionary.  If you want to use another dictionary, it must
+  be specified explicitly, both when searching and when creating a
+  full text index.

data/doc/release_notes/2.8.0.txt

@@ -0,0 +1,171 @@
+New Features
+------------
+
+* Sequel now supports database stored procedures similar to its
+  support for prepared statements.  The API is as follows:
+
+    DB[:table].call_sproc(:select, :mysp, 'param1', 'param2')
+    # or
+    sp = DB[:table].prepare_sproc(:select, :mysp)
+    sp.call('param1', 'param2')
+    sp.call('param3', 'param4')
+
+  This works with Model datasets as well, allowing them to return
+  model objects:
+
+    Album.call_sproc(:select, :new_albums)
+    #=> [#<Album ...>, #<Album ...>]
+
+  You can call a stored procedure directly on the Database object
+  if you want to, but the results and API are adapter dependent,
+  and you definitely shouldn't do it if the stored procedure returns
+  rows:
+
+    DB.call_sproc(:mysp, :args=>['param1', 'param2'])
+
+  Currently, the MySQL and JDBC adapters support stored procedures.
+  Other adapters may support them in a future version.
+
+* The connection pool code can now remove connections if the
+  adapter raises a Sequel::DatabaseDisconnectError indicating that
+  the connection has been lost.  When a query is attempted and
+  the adapter raises this error, the connection pool removes the
+  connection from the pool, and reraises the error.  The Oracle and
+  PostgreSQL adapters currently support this, and other adapters may
+  support it in a future version.
+
+* Whether to upcase or quote identifiers can now be set separately.
+  Previously, upcasing was done when quoting except when using SQLite,
+  PostgreSQL, or MySQL.  Now, you can turn upcasing off while still
+  quoting.  This may be necessary if you are using a MSSQL database
+  that has lower case table names that conflict with reserved words.
+  It also allows you to uppercase identifiers when using SQLite,
+  PostgreSQL, or MySQL, which may be beneficial in certain cases.
+
+  To turn upcasing on or off:
+
+    # Global
+    Sequel.upcase_identifiers = true
+    # Database
+    DB = Sequel.connect("postgres://...", :upcase_identifiers=>true)
+    DB.upcase_identifiers = false
+    # Dataset
+    ds = DB[:items]
+    ds.upcase_identifiers = true
+
+* Options are now supported when altering a columns type:
+
+    DB.alter_table(:items) do
+      set_column_type :score, :integer, :unsigned=>true
+      set_column_type :score, :varchar, :size=>30
+      set_column_type :score, :enum, :elements=>['a', 'b']
+    end
+
+* Standard conforming strings are now turned on by default in the
+  PostgreSQL adapter.  This makes PostgreSQL not interpret backslash
+  escapes.  This is the PostgreSQL recommended setting, which will be
+  the default setting in a future version of PostgreSQL.  If you
+  don't want for force the use of standard strings, use:
+
+    Sequel::Postgres.force_standard_strings = false
+
+  You need to do that after you call Sequel.connect but before you
+  use the database for anything, since that setting is set on
+  initial connection.
+
+* Sequel now raises an error if you attempt to use EXCEPT [ALL] or
+  INTERSECT [ALL] on a database that doesn't support it.
+
+* Sequel now raises an error if you attempt to use DISTINCT ON with
+  MySQL or Oracle, which don't support it.
+
+* A subadapter for the Progress RDBMS was added to the ODBC adapter.
+  To connect to a Progress database, use the :db_type=>'progress'
+  option.  This adapter targets Progress 9.
+
+* The ODBC adapter now supports transactions.
+
+* The MSSQL shared adapter now supports multi_insert (for inserting
+  multiple rows at once), and unicode string literals.
+
+Other Improvements
+------------------
+
+* There were many improvements related to using schemas in databases.
+  Using schema-qualified tables should work in most if not all cases
+  now.  Model associations, getting the schema, joins, and many other
+  parts of Sequel were modified to allow the use of schema-qualifed
+  tables.
+
+* You can now use literal strings with placeholders as well as
+  subselects when using prepared statements.  For example, the
+  following all work now:
+
+    DB[:items].filter("id = ?", :$i).call(:select, :i=>1)
+    DB[:items].filter(:id=>DB[:items].select(:id)\
+      .filter(:id=>:$i)).call(:select, :i=>1)
+    DB["SELECT * FROM items WHERE id = ?", :$i].call(:select, :i=>1)
+
+* Model#initialize received a few more micro-optimizations.
+
+* Model#refresh now clears the changed columns as well as the
+  associations.
+
+* You can now drop columns inside a transaction when using SQLite.
+
+* You can now submit multiple SQL queries at once in the MySQL
+  adapter:
+
+    DB['SELECT 1; SELECT 2'].all
+    #=> [{:"1"=>1, :"2"=>2}]
+
+  This may fix issues if you've seen a MySQL "commands out of sync"
+  message.  Note that this doesn't work if you are connecting to
+  MySQL via JDBC.
+
+* You can now use AliasedExpressions directly in table names given
+  to join_table:
+
+    DB.from(:i.as(:j)).join(:k.as(:l), :a=>:b)
+    #=> ... FROM i AS j INNER JOIN k AS l ON (l.a = j.b)
+
+* Database#rename_table once again works on PostgreSQL.  It was
+  broken in 2.7.0.
+
+* The interval type is now treated as it's own type. It was
+  previously treated as an integer type.
+
+* Subselects are now aliased correctly when using Oracle.
+
+* UNION, INTERSECT, and EXCEPT statements now appear before ORDER
+  and LIMIT on most databases.  If you use these constructs, please
+  test and make sure that they work correctly with your database.
+
+* SQL EXCEPT clause now works on Oracle, which uses MINUS instead.
+
+* Dataset#exists now returns a LiteralString, to make it easier to
+  use.
+
+* The Sequel.odbc_mssql method was removed, as the odbc_mssql adapter
+  was removed in a previous version.  Instead, use:
+
+    Sequel.odbc(..., :db_type=>'mssql')
+
+Backwards Compatibilty
+----------------------
+
+* The hash returned by Database#schema when no table name is provided
+  uses quoted strings instead of symbols as keys.  The hash has a
+  default proc, so using the symbol will return the same value as
+  before, but if you use each to iterate through the hash, the keys
+  will be different.  This was necessary to handle schema-qualified
+  tables.
+
+* Database#table_exists? no longer checks the output of
+  Database#tables.  If the table exists in the schema, it returns
+  true, otherwise, it does a query.  This was necessary because
+  table_exists? accepts multiple formats for table names and
+  Database#tables is an array of symbols.
+
+* When getting the schema on PostgreSQL, the default schema is now
+  used even if the :schema=>nil option is used.

data/doc/release_notes/2.9.0.txt

@@ -0,0 +1,97 @@
+New Features
+------------
+
+* Compound SQL statement (i.e. UNION, EXCEPT, and INTERSECT) support
+  is much improved.  Chaining compound statement calls now longer
+  wipes out previous compound statements calls of the same type.
+  Also, the ordering of the compound statements is no longer fixed
+  per adapter, it now reflects the order they were called on the
+  object.  For example, the following now work as expected:
+
+    ds1.union(ds2).union(ds3)
+    ds1.except(ds2).except(ds3)
+    ds1.intersect(ds2).intersect(ds3)
+    ds1.union(ds2).except(ds3)
+    ds1.except(ds2).intersect(ds3)
+    ds1.intersect(ds2).union(ds3)
+
+* Exception classes ValidationFailure and BeforeHookFailure were
+  added so it is eaiser to catch a failed validation.  These are
+  both subclasses of Sequel::Error, so there shouldn't be any
+  backwards compatibility issues.  Error messages are also improved,
+  as the ValidationFailure message is a string containing all
+  validation failures and the BeforeHookFailure message contains
+  which hook type caused the failure (i.e. before_save,
+  before_create, or before_validate).
+
+* The sequel command line tool now has a -L option to load
+  all files in the given directory.  This is mainly useful for
+  loading a directory of model files. The files are loaded
+  after the database connection is set up.
+
+* Methods to create and drop database functions, triggers, and
+  procedural languages were added to the PostgreSQL adapter.
+
+Other Improvements
+------------------
+
+* Database#schema now raises an error if you pass a table that
+  doesn't exist.  Before, some adapters would return an empty schema.
+  The bigger problem with this is that it made table_exists? return
+  the wrong value, since it looks at the Database's schema.
+  Generally, this bug would show up in the following code:
+
+    class Blah < Sequel::Model
+    end
+    Blah.table_exists? # True even if blahs is not a table
+
+* AlterTableGenerator#add_foreign_key now works for MySQL.
+
+* Error messages in model association methods that add/remove an
+  associated object are now more descriptive.
+
+* Dataset#destroy for model datasets now works with databases that
+  can't handle nested queries.  However, it now loads all model
+  objects being destroyed before attempting to destroy any of them.
+
+* Dataset#count now works correctly for compound SQL statements
+  (i.e. UNION, EXCEPT, and INTERSECT).
+
+* BigDecimal NaN and (+/-)Infinity values are now literalized
+  correctly.  Database support for this is hit or miss.  Sqlite will
+  work correctly, PostgreSQL raises an error if you try to store an
+  infinite value in a numeric column (though it works for float
+  columns), and MySQL converts all three to 0.
+
+* The SQLite adapter no longer loses primary key information when
+  dropping columns.
+
+* The SQLite adapter now supports dropping indicies.
+
+* A bug in the MSSQL adapter's literalization of LiteralStrings has
+  been fixed.
+
+* The literalization of blobs on PostgreSQL (bytea columns) has been
+  fixed.
+
+* Sequel now raises an error if you attempt to subclass Sequel::Model
+  before setting up a database connection.
+
+* The native postgresql adapter has been changed to only log client
+  messages of level WARNING by default.  You can modify this via:
+
+    Sequel::Postgres.client_min_messages = nil # Use Server Default
+    Sequel::Postgres.client_min_messages = :notice # Use NOTICE level
+
+* Model#inspect now calls Model#inspect_values for easier
+  overloading.
+
+Backwards Compatibilty
+----------------------
+
+* The API to Model#save_failure (a private method) was changed to
+  remove the second argument.
+
+* SQLite columns with type numeric, decimal, or money are now
+  returned as BigDecimal values.  Before, they were probably returned
+  as strings.

data/doc/schema.rdoc

@@ -0,0 +1,29 @@
+= Schema Modifications with Sequel
+
+In addition to its support for getting data from databases, Sequel has good support for modifying the schema of databases.  Unfortunately, the documentation from this is spread out in various places in the Sequel RDoc.
+
+The recommended way to set up schema modifications in Sequel is through migrations. Migrations are modifications to the schema that handle modifying the schema in two directions, up and down, with down reversing the changes made by up. Migrations are stored in sequentially numbered files inside a directory (see the Sequel::Migrator documentation for file naming format details).  The migrations can be run on the database using the sequel command line tool (the -m and -M switches).
+
+The format of the individual migration files themselves is explained in the Sequel::Migration documentation.  Each migration file contains a single migration class.  The migration class acts a proxy for the related database (given on the command line if the sequel command line tool is used, or by the db argument to Sequel::Migration#apply if the API is used). The methods that can be used inside Sequel::Migration#up or Sequel::Migration#down are just Sequel::Database instance methods, such as create_table, drop_table, and alter_table.  Most database methods that alter the schema take regular arguments, but create_table and alter_table take a block.  The methods you can use inside the create_table block are documented in Sequel::Schema::Generator, and the methods you can use inside the alter_table block are documented in Sequel::Schema::AlterTableGenerator.
+
+Migrations are not required, you can just call the schema modification methods directly on the database object.  This is often done in test code and examples.  However, it is recommended that you use the migration framework unless the database schema will not be changing in the future, as it provides a way to easily handle modifications to existing database schema.
+
+Also, new in Sequel 2.10 is the ability to have database independent migrations using ruby classes as types.  When you use a ruby class as a type, Sequel translates it to the most comparable type in the database you are using.  Here's an example using all supported types:
+
+    DB.create_table(:cats) do
+      primary_key :id, :type=>Integer # integer
+      String :a                       # varchar(255)
+      column :b, File                 # blob
+      Fixnum :c                       # integer
+      foreign_key :d, :other_table, :type=>Bignum # bigint
+      Float :e                        # double precision
+      BigDecimal :f                   # numeric
+      Date :g                         # date
+      DateTime :h                     # timestamp
+      Time :i                         # timestamp
+      Numeric :j                      # numeric
+      TrueClass :k                    # boolean
+      FalseClass :l                   # boolean
+    end
+
+Basically, if you use one of the ruby classes above, it will translate into a database specific type.  If you use a lowercase method, symbol, or string to specify the type, Sequel won't attempt to translate it.