sequel 5.6.0 → 5.7.0

data/doc/release_notes/2.10.0.txt

@@ -1,328 +0,0 @@
-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

@@ -1,215 +0,0 @@
-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.