viking-sequel 3.10.0

data/doc/release_notes/2.10.0.txt

@@ -0,0 +1,328 @@
+New Supported Adapters and Databases
+------------------------------------
+
+* A DataObjects adapter was added that supports PostgreSQL,
+  MySQL, and SQLite.  DataObjects is the underlying database
+  library used by DataMapper, and has potential performance
+  advantages by doing all typecasting in C.
+
+* A Firebird Adapter was added, it requires the modified Ruby
+  Fb adapter found at http://github.com/wishdev/fb.
+
+* An H2 JDBC subadapter was added, based on the code used in JotBot.
+  H2 is an embeddable Java database, and may be preferable to using
+  SQLite on JDBC because SQLite requires native code.
+
+New Core Features
+-----------------
+
+* Sequel now has database independent migrations.  Before, column
+  types in migrations were not translated per database, so it was
+  difficult to set up a migration that worked on multiple databases.
+  Sequel now accepts ruby classes as database types, in addition to
+  symbols and strings.  If a ruby class is used, it is translated
+  to the most appropriate database type.  Here is an example using
+  all supported classes (with Sequel's default database type):
+
+    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
+
+  Type translations were tested on the PostgreSQL, MySQL, SQLite,
+  and H2 databases.  The default translations should work OK for
+  most databases, but there will probably be a type or two that
+  doesn't work.  Please send in a patch if Sequel uses a column type
+  that doesn't work on your database.
+
+  Note that existing migrations still work fine, in most cases.  If
+  you were using strings or symbols for types before, they should
+  still work.  See the Backwards Compatibility section below for
+  details.
+
+  Also note that this doesn't relate solely to migrations, as any
+  database schema modification method that accepts types will
+  accept one of the above classes.
+
+* A ton of internal work was done to better support databases that
+  fold unqouted identifiers to uppercase (which is the SQL standard).
+  Sequel now allows you to set a method to call on identifiers going
+  both into and out of the database.  The default is to downcase
+  identifiers coming out, and upcase identifiers going in, though
+  this is overridden by the PostgreSQL, MySQL, and SQLite adapters
+  to not do anything (since they fold to lowercase by default).
+
+  The settings are called identifier_input_method and
+  identifier_output_method, and like most Sequel settings, they can
+  be set globally, per database, or per dataset:
+
+    # Global (use uppercase in ruby and lowercase in the database)
+    Sequel.identifier_input_method = :downcase
+    Sequel.identifier_output_method = :upcase
+    # Per Database (use camelized names in the database, and
+    #               underscored names in ruby)
+    DB.identifier_input_method = :camelize
+    DB.identifier_output_method = :underscore
+    # Per Dataset (obfuscate your database columns!)
+    class String; def rot_13; tr('A-Za-z', 'N-ZA-Mn-za-m') end end
+    ds = DB[:table]
+    ds.identifier_input_method = :rot_13
+    ds.identifier_output_method = :rot_13
+
+* Schema parsing support was added to the JDBC adapter, using the
+  JDBC metadata methods.  This means that models that use the
+  JDBC adapter will typecast data in their column setters and
+  automatically select the correct primary key column(s).  This is
+  currently the only adapter that supports schema parsing when using
+  an MSSQL or Oracle database.
+
+* Database#create_table now takes options, which you can use to
+  specify a MySQL engine, charset, and/or collation.  You can also
+  set a default engine, charset, and collation for MySQL to use:
+
+    Sequel::MySQL.default_engine = 'InnoDB'
+    Sequel::MySQL.default_charset = 'utf8'
+    Sequel::MySQL.default_collate = 'utf8'
+
+  The defaults will be used if the options are not provided.  If a
+  default engine is set, you can specify :engine=>nil to not use it
+  (same goes for charset and collate).
+
+* The Sequel::DatabaseConnectionError exception class was added.  It
+  is raised by the connection pool if there is an error attempting
+  to instantiate a database connection.  Also, if the adapter returns
+  nil instead of raising an error for faulty connection parameters,
+  DatabaseConnectionError will be raised immediately, instead of the
+  connection pool busy waiting until if gives up with a
+  PoolTimeoutError.
+
+* Database#tables is now supported on the JDBC adapter, returning
+  an Array of table name symbols.
+
+* Sequel now converts the following Java types returned by the JDBC
+  adapter into ruby types: Java::JavaSQL::Timestamp,
+  Java::JavaSQL::Time, Java::JavaSQL::Date,
+  Java::JavaMath::BigDecimal, and Java::JavaIo::BufferedReader.
+
+* When using the PostgreSQL adapter with the postgres-pr driver,
+  Sequel will use a custom string escaping routine unless
+  force_standard_strings = false.  This means that using Sequel's
+  defaults, postgres-pr will correctly escape strings now.
+
+* The SQLite adapter now returns float, real, and double precision
+  columns as Floats.
+
+* The SQLite adapter logs beginning, committing, and rolling back
+  transactions.
+
+* Sequel now has an internal version (before, the only way to tell
+  the version was to look at the gem being used).  It is accessible
+  at Sequel.version.
+
+New Model Features
+------------------
+
+* A new validates_not_string validation was added for Sequel Models.
+  It is intended to be used with the raise_on_typecast_failure =
+  false setting.  In this case, for a non-string database column,
+  if there is a string value when the record is going to be
+  saved, it is due to the fact that Sequel was not able to typecast
+  the given data correctly (so it is almost certainly not valid).
+  This should make Sequel easier to use with web applications.
+
+* An :allow_missing validation option was added to all standard
+  validations.  This option skips the validation if the attribute
+  is not in the object's values.  It is different from :allow_nil,
+  which will skip the value if it is present but nil in the values.
+  The intended use case for this option is when the database provides
+  a good default.  If the attribute is not present in values, the
+  database will use its default.  If the attribute is present in
+  the values but equals nil, Sequel will attempt to insert it into
+  the database as a NULL value, instead of using the database's
+  default.  If you don't want Sequel to insert a NULL value in the
+  database, but you want the database to provide the default, this
+  is the option to use.
+
+* validates_each now accepts :allow_nil and :allow_blank options,
+  so it is easier to create custom validations with the same options
+  as the standard validations.
+
+* Before_* hooks now run in the reverse order that they were added.
+  The purpose of hooks is to wrap existing functionality, and making
+  later before_* hooks run before previous before_* hooks is the
+  correct behavior.
+
+* You can now add you own hook types, via Model.add_hook_type.  This
+  is intended for plugin use.  All of the standard hooks are now
+  implemented using this method.
+
+* The value of new? in a after_save hook now reflects the
+  previous state of the model (so true for a create and false for an
+  update), instead of always being false.  This makes it easier
+  to have a complex after_save hook that still needs to
+  differentiate between a newly created record and an updated record,
+  without having to add separate after_create and after_update
+  hooks.
+
+* The value of changed_columns in an after_update hook now reflects
+  the value before the update occurred, instead of usually being
+  empty.  Previously, to have this functionality, you generally had
+  to save the value to an instance variable in a before_update hook
+  so you could reference it in the after_update hook.
+
+Other Improvements
+------------------
+
+* Sequel now longer overwrites the following Symbol instance methods
+  when running on ruby 1.9: [], <, <=, >, and >=.  One of Sequel's
+  principals is that it does not override methods defined by ruby,
+  and now that ruby 1.9 defines the above methods on Symbol, Sequel
+  shouldn't be overwriting them.
+
+  Sequel already provides a way to work around this issue when
+  another library adds the same methods to Symbol that Sequel does.
+  For example, you need to change the following:
+
+    dataset.filter(:number > 1)
+    dataset.filter(:number >= 2)
+    dataset.filter(:name < 'M')
+    dataset.filter(:name <= 'I')
+    dataset.filter(:is_bool[:x])
+
+  To:
+
+    dataset.filter{|o| o.number > 1}
+    dataset.filter{|o| o.number >= 2}
+    dataset.filter{|o| o.name < 'M'}
+    dataset.filter{|o| o.name <= 'I'}
+    dataset.filter{|o| o.is_bool(:x)}
+
+  The argument provided to the block is a Sequel::SQL::VirtualRow.
+  This class uses method_missing so that any methods called on it
+  return Sequel::SQL::Identifiers (if no arguments are provided)
+  or Sequel::SQL::Function (if arguments are provided).
+
+  If you were using one of the above symbol methods outside of a
+  filter, you can to call sql_string, sql_number, or sql_function
+  on the symbol.  So the following would also work:
+
+    dataset.filter(:number.sql_number > 1)
+    dataset.filter(:number.sql_number >= 2)
+    dataset.filter(:name.sql_string < 'M')
+    dataset.filter(:name.sql_number <= 'I')
+    dataset.filter(:is_bool.sql_function(:x))
+
+  Using the block argument makes for a nicer API, though, so I
+  recommend using it when possible.
+
+  Note that if you are running ruby 1.8 or jruby without the --1.9
+  flag, you don't need to worry.  If you are running ruby 1.9 or
+  jruby --1.9, or you plan to at some point in the future, you
+  should inspect your code for existing uses of these methods.
+  Here are a couple command lines that should find most uses:
+
+    # Find :symbol[]
+    egrep -nr ':['\''"]?[a-zA-Z_0-9]*['\''"]?\[' *
+    # Find :symbol (<|>|<=|>=)
+    egrep -nr '[^:]:['\''"]?[a-zA-Z_0-9]*['\''"]? *[<>]=?' *
+
+* Database#quote_identifiers now affects future schema modifications
+  when using the database.  Previous, it only affected future
+  schema modifications if a schema modification method had not yet
+  been called.
+
+* Literalization of Times and DateTimes is now correct when using the
+  MySQL JDBC subadapter.
+
+* Literalization of Blobs is now correct when using the PostgreSQL
+  JDBC subadapter.
+
+* Index and table names are quoted when creating indices in the
+  PostgreSQL adapter.
+
+* Dataset#delete was changed in the SQLite adapter to add a
+  where clause that is always true, instead of doing an explicit
+  count first and the deleting.  This is simpler, though it
+  could potentially have performance implications.
+
+* The sequel command line tool now supports symbol keys and unnested
+  hashes in YAML files, so it should work with Merb's database.yml.
+  It also includes the error class in the case of an error.
+
+* The integration type tests were greatly expanded.  Generally,
+  running the integration tests is a good way to determine how well
+  your database is supported.
+
+* Dataset#quote_identifier now returns LiteralStrings as-is, instead
+  of treating them as regular strings.
+
+* Sequel no longer modifies the MySQL::Result class when using the
+  MySQL adapter.
+
+Backwards Compatibilty
+----------------------
+
+* If you were previously using a database that returned uppercase
+  identifiers, it will probably return lowercase identifiers by
+  default now.  To get back the old behavior:
+
+    DB.identifier_output_method = nil
+
+* The module hierarchy under Sequel::SQL has changed.  Now,
+  modules do not include other modules, and the following modules
+  were removed since they would have been empty after removing
+  the modules they included: Sequel::SQL::SpecificExpressionMethods
+  and Sequel::SQL::GenericExpressionMethods.
+
+* Sequel no longer assumes the public schema by default when
+  connecting to PostgreSQL.  You can still set the default
+  schema to use (even to public).
+
+* The ability to load schema information for all tables at once
+  was removed from the PostgreSQL adapter.  While it worked, it had
+  some issues, and it was difficult to keep it working when some
+  new features were used.  This ability wasn't exposed to the user,
+  and was purely an optimization.  If you have any code like:
+
+    DB.schema
+
+  by itself after the Database object was instantiated, you should
+  remove it.
+
+* The Database#primary_key API changed in the PostgreSQL shared
+  adapter, it now accepts an options hash with :server and :conn keys
+  instead of a server symbol.  Also, quite a few private Database
+  instance methods changed, as well as some constants in the
+  AdapterMethods.
+
+* It is possible that some migrations will break, though it is
+  unlikely.  If you were using any of the classes mentioned above
+  as a method inside a migration, it might be broken.  However,
+  since String, Float, and Integer wouldn't have worked as methods
+  before, it is unlikely that anyone used this.
+
+* The meaning of #String, #Integer, and #Float inside
+  Sequel::SQL::Generator (i.e. inside a Database#create_table
+  block) has changed.  Before, these used to call private Kernel
+  methods, now, they set up columns with the appropriate database
+  type.
+
+* The Database#lowercase method in the DBI adapter was removed,
+  as its use case is now met by the identifier_output_method support.
+
+* Database#uri is now aliased explicitly via a real method, to
+  allow for easier subclassing.
+
+* You can no longer pass nil as the second argument to
+  Database#create_table.

data/doc/release_notes/2.11.0.txt

@@ -0,0 +1,215 @@
+Optimizations
+-------------
+
+* Model.[] was optimized to use static SQL in cases where doing so
+  should result in the same output.  This should result in a 30-40%
+  performance increase.  Since this can be the most significant or
+  only method call in a web application action, this has potential
+  to significantly enhance the performance of web application code.
+  
+  In order for this optimization to have an effect, you need to
+  make sure that you are calling set_dataset with a Symbol and
+  not a Dataset object:
+  
+    # Optimized:
+    class Foo < Sequel::Model; end
+    class Foo < Sequel::Model(:foos); end
+    class Foo < Sequel::Model
+      set_dataset :foos
+    end
+    
+    # Not Optimized, but otherwise equivalent:
+    class Foo < Sequel::Model(Model.db[:foos]); end
+    class Foo < Sequel::Model
+      set_dataset db[:foos]
+    end
+  
+* Dataset#literal was refactored for performance reasons to make
+  overriding it in subclasses unnecessary.  The changes made result
+  in a 20-25% performance increase.  Sequel can spend about 10% of
+  it's time in Dataset#literal, so this may be only a 2% overall
+  performance improvement.
+
+New Features
+------------
+
+* Association datasets now know about the model objects that created
+  them, as well as the related association reflection.  This makes
+  association extensions much more powerful.  For example, you can
+  now create generic association extensions such as:
+  
+    module FindOrCreate
+      def find_or_create(vals)
+        first(vals) || association_reflection.associated_class. \
+         create(vals.merge(association_reflection[:key]=> \
+           model_object.id))
+      end
+    end
+    
+  The above will work for any standard one_to_many association:
+  
+    Artist.one_to_many :albums, :extend=>FindOrCreate
+    # Create an album named Foo related to this artist,
+    # unless such an album already exists
+    Artist.first.albums_dataset.find_or_create(:name=>'Foo')
+    
+  Before, the only way to do the above was to use a closure inside
+  the :dataset option proc, which couldn't be done generically
+  for multiple associations.
+  
+* A :conditions association option was added, which allows simple
+  filters to be set up without defining :graph_conditions and
+  an association block:
+  
+    # 2.10.0
+    one_to_many(:japanese_verses, :class=>:Verse, \
+     :graph_conditions=>{:languageid=>3})do |ds|
+       ds.filter(:languageid=>3)
+    end
+    # 2.11.0
+    one_to_many(:japanese_verses, :class=>:Verse, \
+       :conditions=>{:languageid=>3})
+
+* A :clone association option was added, which allows you to clone
+  an existing association.  This is most useful when you are dealing
+  with a legacy schema and had to define the same options redundantly
+  for each type of association. You can now do:
+  
+    many_to_many :deputies, :class=>:Employee, \
+     :join_table=>:employeecurrentaudits, :left_key=>:currentauditid, \
+     :right_key=>:employeeid, :order=>[:firstname, :lastname] do |ds|
+      ds.filter(:active).filter(:capacity=>1)
+    end
+    many_to_many :project_managers, :clone=>:deputies do |ds|
+      ds.filter(:active).filter(:capacity=>2)
+    end
+    many_to_many :team_leaders, :clone=>:deputies do |ds|
+      ds.filter(:active).filter(:capacity=>3)
+    end
+    
+  All of the above would use the same :class, :join_table, :left_key,
+  :right_key, and :order options.  If you don't provide an
+  association block, but you are cloning an association that has one,
+  the cloned association's block is used.  You can use the
+  :block=>nil option to not use a block even if the cloned
+  association has a block.
+
+* Dataset#select, #select_more, #order, #order_more, and #get all
+  take a block that yields a Sequel::SQL::VirtualRow instance,
+  similar to the behavior of filter. This allows for the easier
+  use of SQL functions on Ruby 1.9:
+  
+    # 2.10.0
+    dataset.select(:prettify.sql_function(:name))
+    # 2.11.0
+    dataset.select{|o| o.prettify(:name)}
+
+* String#lit can now accept arguments and return an SQL literal
+  string.  This allows you to do things that were previously hard
+  or at least unnecessarily verbose.  For example, you can now
+  easily use the SQL standard SUBSTRING function:
+  
+    column = :user
+    pattern = params[:pattern]
+    dataset.select{|o| o.substring('? from ?'.lit(column, pattern))}
+    
+* A validates_inclusion_of validation method was added to Model. You
+  can provide a Range or an Array in the :in option to specify the
+  allowed values:
+  
+    validates_inclusion_of :value, :in=>1..5
+    validates_inclusion_of :weekday, :in=>%w'Monday Tuesday ...'
+
+* Dataset#with_sql was added, which returns a copy of the dataset
+  with static SQL.  This is useful if you want to keep the same
+  row_proc/graph/transform/etc., but want to use your own custom
+  SQL.
+
+Other Improvements
+------------------
+
+* You can now use Sequel's database independent types when casting:
+
+    dataset.select(:number.cast(String))
+  
+  Among other things, the default cast types for cast_string and
+  cast_numeric now work in the MySQL adapter.
+
+* Model#set_associated_object was added.  The many_to_one association
+  setter method calls it.  This allows you to easily override the
+  association setters for all many_to_one associations of a class
+  by modifying a single method. 
+  
+* Typecasting invalid date strings now raises a
+  Sequel::Error::InvalidValue instead of an argument error, which
+  means that you can use raise_on_typecast_failure = false and not
+  have an error raised when an invalid date format is used.
+  
+* String#to_sequel_blob was added and should now be used instead
+  of String#to_blob.  sqlite3-ruby defines String#to_blob
+  differently, which could cause problems.
+  
+* Blob columns are now fully supported in the SQLite adapter, with
+  the hex escape syntax being used for input, and returning columns
+  of type Sequel::SQL::Blob on output.
+  
+* The SQLite adapter drop_column support is now significantly more
+  robust.
+  
+* The SQLite adapter now supports rename_column.
+  
+* The MySQL adapter now supports stored procedures with multiple
+  arguments.
+  
+* The MySQL adapter can now not use a compressed connection to the
+  server via the :compress=>false option.
+  
+* The MySQL adapter now sets a default timeout of 30 days to the
+  database connection, you can change it via the :timeout option,
+  which accepts a number of seconds.
+  
+* The MySQL adapter now sets SQL_AUTO_IS_NULL to false by default,
+  you can use the :auto_is_null=>true option to not do this.
+  
+* The MySQL adapter now sets the encoding option on the database
+  connection itself, so it works across reconnects.
+
+* Sequel itself no longer uses String#lit or Symbol#* internally, so
+  it shouldn't break if another library defines them.
+
+* The default index name is now generated correctly if a non-String
+  or Symbol column is used.
+  
+* Some ruby -w warnings have been fixed.
+
+* INSERTs are now sent to the master database instead of the slave
+  database(s) if using a master/slave database configuration and
+  PostgreSQL 8.2+ or Firebird.
+  
+* DateTime literalization has been fixed in the Firebird adapter.
+  
+* Date literalization has been fixed in the H2 JDBC subadapter.
+  
+* Release notes for versions from 1.0 to the present are now included
+  in the Sequel repository and the RDoc documentation, see
+  http://sequel.rubyforge.org/rdoc/files/doc/release_notes/
+
+Backwards Compatibilty
+----------------------
+
+* The optimization of Model.[] may break if you modify the model's
+  dataset behind its back.  Always use Model.set_dataset if you
+  want to change a Model's dataset.
+  
+* Sequel::Dataset::UnsupportedExceptIntersect and
+  Sequel::Dataset::UnsupportedExceptIntersectAll will now only be
+  defined if you are using an adapter that requires them.
+  
+* The private Model#cache_delete_unless_new method has been removed.
+
+* Sequel::SQL::IrregularFunction was removed, as it was a bad hack
+  that is not used by Sequel anymore.  Unless you were instantiating
+  it directly or using a plugin/extension that did, this shouldn't
+  affect you.  Using a Sequel::SQL::Function with a 
+  Sequel::SQL::PlaceholderLiteralString is recommended instead, see
+  the substring example above.