viking-sequel 3.10.0

data/doc/release_notes/2.0.0.txt

@@ -0,0 +1,298 @@
+Blockless Filter Expressions
+----------------------------
+
+Before 2.0.0, in order to specify complex SQL expressions, you
+either had to resort to writing the SQL yourself in a string or
+using an expression inside a block that was parsed by ParseTree.
+Because ParseTree was required, only ruby 1.8.* was supported, and
+supporting other ruby versions (ruby 1.9, JRuby, Rubinius) would
+never be possible.
+
+With 2.0.0, you no longer need to use a block to write complex SQL
+expressions. The basics of the blockless filters are the usual
+arithmetic, inequality, and binary operators:
+
+  + = addition
+  - = subtraction
+  * = multiplication
+  / = division
+  > = greater than
+  < = less than
+  >= = greater than or equal to
+  <= = less than or equal to
+  ~ = negation
+  & = AND
+  | = OR
+
+You can use these operators on Symbols, LiteralStrings, and other
+Sequel::SQL::Expressions.  Note that there is no equal operator or
+not equal operator, to specify those, you use a Hash.
+
+Here are some examples:
+
+  # Ruby code => SQL WHERE clause
+  :active => active
+  ~:active => NOT active
+  ~~:active => active
+  ~~~:active => NOT active
+  :is_true[] => is_true()
+  ~:is_true[] => NOT is_true()
+  :x > 100 => (x > 100)
+  :x < 100.01 => (x < 100.01)
+  :x <= 0 => (x <= 0)
+  :x >= 1 => (x >= 1)
+  ~(:x > 100) => (x <= 100)
+  {:x => 100} => (x = 100)
+  {:x => 'a'} => (x = 'a')
+  {:x => nil} => (x IS NULL)
+  ~{:x => 100} => (x != 100)
+  ~{:x => 'a'} => (x != 'a')
+  ~{:x => nil} => (x IS NOT NULL)
+  {:x => /a/} => (x ~ 'blah') # Default, MySQL different
+  ~{:x => /a/} => (x !~ 'blah') # Default, MySQL different
+  :x.like('a') =>  (x LIKE 'a')
+  ~:x.like('a') =>  (x NOT LIKE 'a')
+  :x.like(/a/) => (x ~ 'a') # Default, MySQL different
+  ~:x.like('a', /b/) => ((x NOT LIKE 'a') AND (x !~ 'b')) # Default
+  ~{:x => 1..5} => ((x < 1) OR (x > 5))
+  ~{:x => DB[:items].select(:i)} => (x NOT IN (SELECT i FROM items))
+  ~{:x => [1,2,3]} => (x NOT IN (1, 2, 3))
+  :x + 1 > 100 => ((x + 1) > 100)
+  (:x * :y) < 100.01 => ((x * y) < 100.01)
+  (:x - :y/2) >= 100 => ((x - (y / 2)) >= 100)
+  (((:x - :y)/(:x + :y))*:z) <= 100 => ((((x - y) / (x + y)) * z) <=
+100)
+  ~((((:x - :y)/(:x + :y))*:z) <= 100) => ((((x - y) / (x + y)) * z) >
+100)
+  :x & :y => (x AND y)
+  :x & :y & :z => ((x AND y) AND z)
+  :x & {:y => :z} => (x AND (y = z))
+  {:y => :z} & :x => ((y = z) AND x)
+  {:x => :a} & {:y => :z} => ((x = a) AND (y = z))
+  (:x > 200) & (:y < 200) => ((x > 200) AND (y < 200))
+  :x | :y => (x OR y)
+  :x | :y | :z => ((x OR y) OR z)
+  :x | {:y => :z} => (x OR (y = z))
+  {:y => :z} | :x => ((y = z) OR x)
+  {:x => :a} | {:y => :z} => ((x = a) OR (y = z))
+  (:x > 200) | (:y < 200) => ((x > 200) OR (y < 200))
+  (:x | :y) & :z => ((x OR y) AND z)
+  :x | (:y & :z) => (x OR (y AND z))
+  (:x & :w) | (:y & :z) => ((x AND w) OR (y AND z))
+  ~((:x | :y) & :z) => ((NOT x AND NOT y) OR NOT z)
+  ~((:x & :w) | (:y & :z)) => ((NOT x OR NOT w) AND (NOT y OR NOT z))
+  ~((:x > 200) | (:y & :z)) => ((x <= 200) AND (NOT y OR NOT z))
+  ~('x'.lit + 1 > 100) => ((x + 1) <= 100)
+  'x'.lit.like(/a/) => (x ~ 'a') # (x ~ \'a\')
+
+None of these require blocks, you can use any directly in a call to
+filter:
+
+  DB[:items].filter((:price * :tax) - :discount > 100)
+  # => SELECT * FROM items WHERE (((price * tax) - discount) > 100)
+  DB[:items].filter(:active & ~:archived)
+  # => SELECT * FROM items WHERE (active AND NOT archived)
+
+SQL String Concatenation
+------------------------
+
+Sequel now has support for expressing SQL string concatenation in an
+easy way:
+
+  [:name, :title].sql_string_join(" - ")
+  # SQL:  name || ' - ' || title
+
+You can use this in selecting columns, creating filters, ordering
+datasets, and possibly elsewhere.
+
+Schema Reflection Support/Typecasting on Assignment
+---------------------------------------------------
+
+When used with PostgreSQL, MySQL, or SQLite, Sequel now has the
+ability to get information from the database's schema in regards
+to column types:
+
+  DB.schema(:artist)
+  => [[:id, {:type=>:integer, :db_type=>"integer", :max_chars=>0
+     :numeric_precision=>32, :allow_null=>false,
+     :default=>"nextval('artist_id_seq'::regclass)"}], [:name,
+     {:type=>:string, :default=>nil, :db_type=>"text",
+     :numeric_precision=>0, :allow_null=>true, :max_chars=>0}]]
+
+Models now use this information to typecast values on attribute
+assignment. For example, if you have an integer column named number
+and a text (e.g. varchar) column named title:
+
+  1.5.1:
+    model.number = '1'
+    model.number # => '1'
+    model.title = 1
+    model.title # => 1
+  2.0.0:
+    model.number = '1'
+    model.number # => 1
+    model.title = 1
+    model.title # => '1'
+
+Typecasting can be turned off on a global, per class, and per object
+basis:
+
+  Sequel::Model.typecast_on_assignment = false # Global
+  Album.typecast_on_assignment = false # Per Class
+  Album.new.typecast_on_assignment = false # Per Object
+
+Typecasting is somewhat strict, it does not allow obviously bogus
+data to be used:
+
+  model.number = 'a' # Raises error
+
+This is in contrast to how some other ORMs handle the situation:
+
+  model.number = 'a'
+  model.number # => 0
+
+If Sequel is being used with a web framework and you want to display
+friendly error messages to the user, you should probably turn
+typecasting off and set up the necessary validations in your models.
+
+Model Association Improvements
+------------------------------
+
+Associations can now be eagerly loaded even if they have a block,
+though the block should not rely on being evaluated in the context
+of an instance. This allows you filter on associations when eagerly
+loading:
+
+  Artist.one_to_many :albums_with_10_tracks, :class=>:Album do |ds|
+    ds.filter(:num_tracks => 10)
+  end
+  Artist.filter(:name.like('A%)).eager(:albums_with_10_tracks).all
+  # SELECT * FROM artists WHERE (name LIKE 'A%')
+  # SELECT albums.* FROM albums WHERE ((artist_id IN (...)) AND
+  #   (num_tracks = 10))
+
+Associations now have a remove_all_ method for removing all
+associated objects in a single query:
+
+  Artist.many_to_many :albums
+  Artist[1].remove_all_albums
+  # DELETE FROM albums_artists WHERE artist_id = 1
+
+  Artist.one_to_many :albums
+  Artist[1].remove_all_albums
+  # UPDATE albums SET artist_id = NULL WHERE artist_id = 1
+
+All associations can specify a :select option to change which columns
+are selected.  Previously only many to many associations suppported
+this.
+
+The SQL used when eagerly loading through eager_graph can be
+modified via the :graph_join_type, :graph_conditions, and
+:graph_join_conditions options.
+
+:graph_join_type changes the join type from the default of
+:left_outer.  This can be useful if you do not want any
+albums that don't have an artist in the result set:
+
+  Album.many_to_one :artist, :graph_join_type=>:inner
+  Album.eager_graph(:artist).sql
+  # SELECT ... FROM albums INNER JOIN artists ...
+
+:graph_conditions adds conditions on the join to the table you are
+joining, the eager_graph equivalent of an association block argument
+in eager. It takes either a hash or an array where all elements
+are arrays of length two, similar to join_table, where key symbols
+specify columns in the joined table and value symbols specify
+columns in the last joined or primary table:
+
+  Album.many_to_one :artist, :graph_conditions=>{:active=>true}
+  Album.eager_graph(:artist).sql
+  # SELECT ... FROM albums LEFT OUTER JOIN artists ON ((artists.id =
+  #   albums.artist_id) AND (artists.active = 't'))
+
+:graph_join_table_conditions exists for many to many associations only,
+and operates the same as :graph_conditions, except it specifies a
+condition on the many to many join table instead of the associated
+model's table. This is necessary if the join table is also model
+table with other columns on which you may want to filter:
+
+  Album.many_to_many :genres, :join_table=>:ag, \
+    :graph_join_table_conditions=>{:active=>true}
+  Album.eager_graph(:genres).sql
+  # SELECT ... FROM albums LEFT OUTER JOIN ag ON ((ag.album_id =
+      albums.id) AND (ag.active = 't')) LEFT OUTER JOIN genres ON
+      (genres.id = ag.genre_id)
+
+Other Small Improvements
+------------------------
+
+* Dataset#invert returns a dataset that matches all records not
+  matching the current filter.
+* Dataset#unfiltered returns a dataset that has any filters removed.
+* Dataset#last_page? and Dataset#first_page? for paginated datasets.
+* The sequel command line tool now support an -E or --echo argument
+  that logs all SQL to the standard output.  It also can take a path
+  to a yaml file with database connection options, in addition to a
+  database URL.
+* Databases can now have multiple SQL loggers, so you can log to the
+  standard output as well as a file.
+* SQL identifiers (columns and tables) are now quoted by default (you
+  can turn this off via Sequel.quote_identifiers = false if need be).
+* Sequel.connect now takes an optional block that will disconnect the
+  database when the block finishes.
+* AlterTableGenerator now has add_primary_key and add_foreign_key
+  methods.
+* Running the specs without ParseTree installed skips the specs that
+  require ParseTree.
+* You can use an array of arrays instead of a hash when specifying
+  conditions, which may be necessary in certain situations where
+  you would be using the same hash key more than once.
+* Almost all documentation for Sequel was updated for 2.0.0, so if you
+  found Sequel documentation lacking before, check out the new RDoc
+  pages.
+* There have been many minor refactoring improvements, the code
+  should now be easier to read and follow.
+* Sequel now has no external dependencies.
+* Sequel::Models now have before_validation and after_validation
+  hooks.
+* Sequel::Model hooks that return false cause the methods that call
+  them (such as save) to return false.
+* Sequel::Models can now load their schema on first instantiation,
+  instead of when they are created, via
+  Sequel::Model.lazy_load_schema=.  This is helpful for certain
+  web frameworks that reload all models on every request.
+* Hook methods that use blocks can now include an optional tag,
+  which allows them to work well with web frameworks that load source
+  files every time they are modified.
+
+The PostgreSQL adapter has been rewritten and now supports ruby-pg.
+There have also been improvements in the following adapters: DBI,
+MySQL, SQLite, Oracle, and MSSQL.
+
+All of the methods that have been deprecated in 1.5.0 have now been
+removed.  If you are want to upgrade to Sequel 2.0.0 from version 1.4.0
+or previous, upgrade to 1.5.1 first, fix all of the deprecation
+warnings that show up, and then upgrade to 2.0.0.
+
+There were some backwards incompatible changes made in 2.0.0 beyond the
+removal of deprecated methods.  These are:
+
+* Inflector is no longer used, the inflection methods were moved
+  directly into String (where they belong because inflections only
+  make sense for strings).  So to override singularization
+  or pluralization rules, use String.inflections instead of
+  Inflector.inflections.
+* MySQL tinyints are now returned as boolean values instead of
+  integers.  MySQL doesn't have a boolean type, and usually it
+  is recommended to use tinyint for a boolean column.
+* You can no longer pass an array to Dataset#order or Dataset#select,
+  you need to pass each argument separately (the * operator is your
+  friend).
+* You must use '?' instead of '(?)' when interpolating an array
+  argument into a string (e.g. filter('x IN ?', [1,2,3]))
+* You must pass an explicit table alias argument to join_table and
+  related methods, you can no longer include the table alias
+  inside the table argument.
+* sqlite:// URLs now operate the same as file:// URLs (2 slashes
+  for a relative path, 3 for an absolute path).
+

data/doc/release_notes/2.1.0.txt

@@ -0,0 +1,271 @@
+Model Improvements
+------------------
+
+* one_to_many/many_to_many associations now support a :limit option,
+  adding a limit/offset to the records returned.  This was possible
+  before using a block, so it is just added for convenience.
+
+* Associations now support a :read_only option, which doesn't create
+  methods that modify the database.
+
+* Associations now support a :graph_select option, which allows
+  specifying the columns of associated models to include when using
+  eager_graph.
+
+* one_to_many associations now have a :one_to_one option.  When used
+  it creates a getter and setter method similar to many_to_one.  This
+  fills the same role as ActiveRecord's has_one, but it is
+  implemented as a couple of convenience methods over one_to_many, so
+  it still requires that you specify the association name as a
+  plural.
+
+* Model datasets now have to_hash augmented so that it can be called
+  without any arguments, in which case it yields an identity map (a
+  hash with keys being primary key values and values being model
+  instances).
+
+* The Model.set_sti_key method was added, for easily setting up
+  single table inheritance.  It should be called only in the parent
+  class.
+
+* Calls to def_dataset_method with a block are now cached and
+  reapplied to the new dataset if set_dataset is called afterward,
+  or in a subclass.
+
+* All validation methods can now be made conditional via an :if
+  option, which takes either a symbol (which specifies an instance
+  method) or a proc (which is instance_evaled).
+
+* Model#set and Model#update have been added back, they are now
+  aliases of #set_with_params and #update_with_params.
+
+* Models now have set_only/set_except/update_only/update_except
+  instance methods that take a hash (like you would provide to
+  set or update) and additional arguments specifying which columns
+  to allow or disallow.
+
+* Models now have a set_allowed_columns and set_restricted_columns
+  methods, which operate similarly to ActiveRecord's attr_accessible
+  and attr_protected.  It is recommend that you use the set_only or
+  update_only instead of these methods, though.  You can ignore the
+  allowed or restricted columns by using #set_all or #update_all.
+
+* The primary key column(s) is restricted by default. To allow it to
+  be set via new/set/update, use:
+
+    Sequel::Model.unrestrict_primary_key # Global
+    Artist.unrestrict_primary_key # Per Class
+
+* It is now easy to override the one_to_many/many_to_many association
+  methods that modify the database (add_/remove_/remove_all_), as
+  they have been broken into two methods, one that handles the
+  caching features and a private one (prepended with an _) that
+  handles the database changes (and which you can easily override
+  without worrying about the caching).
+
+Table Joining
+-------------
+
+Dataset#join_table got a nice overhaul.  You can now use any join
+type your database allows:
+
+  DB[:artist].join_table(:natural, :albums)
+  DB[:numbers].join_table(:cross, :numbers)
+
+You can now specify the conditions as
+
+* String: "a.b = c.d" # ON a.b = c.d
+* Expression :x < :y # ON x < y
+* Array of Symbols: [:x, :y, :z] # USING (x, y, z)
+* nil # no conditions, used for NATURAL or CROSS joins
+
+Dataset#join_table also takes a block that yields three arguments:
+
+* join_table_alias - The alias/name of the table currently being
+  joined
+* last_join_table_alias - The alias name of the last table joined
+  (if there was one) or the first FROM table (if not).
+* joins - An array of JoinClause objects for all previous joins in
+  the query.
+
+Using the block you can specify conditions for complex joins without
+needing to know in advance what table aliases will be used.
+
+Expanded SQL Syntax Support
+---------------------------
+
+SQL Case statements are now supported directly using hashes or
+arrays:
+
+  {:x > 1 => 1}.case(0)
+  # CASE WHEN x > 1 THEN 1 ELSE 0 END
+  [[{:x=>1}, 0], [:x < 1, 1], [:x > 1, 2]].case(-1)
+  # CASE WHEN x = 1 THEN 0 WHEN x < 1 THEN 1 WHEN x > 1 THEN 2
+    ELSE -1 END
+
+You should use an array instead of a hash for multiple conditions
+unless all conditions are orthogonal.
+
+The SQL extract function has special syntax:
+
+  EXTRACT(day FROM date)
+
+This syntax is now supported via the following ruby code:
+
+  :date.extract(:day)
+
+Other Notable Changes
+---------------------
+
+* The sequel command line tool can now run migrations.  The -m
+  option specifies the directory holding the migration files,
+  and the -M options specifies the version to which to migrate.
+
+* The PostgreSQL adapter supports nested transactions/savepoints.
+
+* The schema parser now understands decimal fields, and will
+  typecast to BigDecimal.
+
+* PostgreSQL's numeric type is now recognized and returned as
+  BigDecimal.
+
+* HAVING now comes before ORDER BY, which most databases seem to
+  prefer.  If your database wants HAVING after ORDER BY, please
+  let us know.
+
+* Symbol#qualify now exists, to specify the table name for a given
+  symbol, similar to the use of #as to specify an alias.  This is
+  mainly helpful in conjuction with the #join_table block, as that
+  provides the table aliases to use to qualify the columns inside
+  the block.
+
+* BitwiseMethods (&, |, ^, ~, <<, >>) have been added to the
+  NumericExpression class, so you can do the following:
+
+  (x + 1) ^ 10  # SQL: (x + 1) ^ 10
+  ~(x + 1) # SQL: ~(x + 1)
+
+  Usually, &, |, and ~ operate in a logical manner, but for
+  NumericExpressions, they take on their usual bitwise meaning,
+  since logical operations only make sense for booleans.
+
+* #cast_numeric and #cast_string exist for Symbols, Strings, and
+  other Sequel Expressions, which return the results casted and
+  wrapped in either NumericExpression or StringExpression, so you
+  can use the BitwiseMethods (&, |, ^, ~, <<, >>) or
+  StringConcatenationMethods (+) directly.
+
+# Dataset#to_hash can take only one argument, in which case it uses
+  that argument to specify the key, and uses the entire hash for the
+  value.
+
+# Dataset#graph can now take an array of columns to select from the
+  joined table via the :select option.
+
+# Dataset#filter and similar methods now combine the block and
+  regular argument conditions if both are given, instead of ignoring
+  the regular argument conditions.
+
+# Dataset#filter(false) can now be used to make sure that no records
+  are returned.  Dataset#filter(true) also works, but it's a no-op.
+  Before, these raised errors.
+
+# Dataset#count does a subquery for a dataset using DISTINCT, since
+  the otherwise it would yield a count for the query without
+  DISTINCT.
+
+ParseTree Support Officially Deprecated
+---------------------------------------
+
+The support for ParseTree-based block filters has officially been
+deprecated and will be removed in Sequel 2.2.  To use the
+expression filters (which don't require ParseTree) inside blocks,
+use:
+
+  SEQUEL_NO_PARSE_TREE = true
+  require 'sequel'
+  # OR
+  require 'sequel'
+  Sequel.use_parse_tree = false
+
+This is the default if ParseTree cannot be loaded.  If ParseTree
+can be loaded, it remains the default, in order not to immediately
+break existing code.
+
+With this set, you can use the expression filters inside of blocks:
+
+  dataset.filter{((:x + 1) & 10 < :y) & :z}
+
+That doesn't gain you all that much, but there are some methods
+that feed block arguments into filter, such as the following:
+
+  dataset.first(5){((:x + 1) & 10 < :y) & :z}
+
+Which will get you the first 5 records matching the condition.
+
+Backwards Incompatible Changes
+------------------------------
+
+* To change the datetime classe used from Time to DateTime, you
+  now use:
+
+    Sequel.datetime_class = DateTime # instead of Sequel.time_class
+
+* Models now raise errors if you try to access a missing or
+  restricted method via new/set/update, instead of just silently
+  skipping that parameter.  To get the old behavior:
+
+    Sequel::Model.strict_param_setting = false
+
+* The association_dataset method now takes into account the :eager
+  option and the block argument, where it didn't before. It also
+  takes into account the new :limit option.
+
+* Association methods now raise errors in most cases if the model
+  doesn't have a valid primary key.
+
+* Dataset#join_table used to allow a symbol as a conditions argument
+  as a shortcut for a hash:
+
+    DB[:artist].join(:albums, :artist_id)
+    # ON albums.artist_id = artists.id
+
+  With the changes to #join_table, this no longer works.  It would
+  now be interpreted as a boolean column:
+
+    DB[:artist].join(:albums, :artist_id)
+    # ON artists.id
+
+  Use the following slightly longer version for the old behavior:
+
+    DB[:artist].join(:albums, :artist_id=>:id)
+    # ON albums.artist_id = artists.id
+
+* MySQL users need to be careful when upgrading, the following code
+  will once again cause an error:
+
+    DB[:artists].each{|artist| DB[:albums].each{|album| ...}}
+
+  To fix it, change the code to:
+
+    DB[:artists].all{|artist| DB[:albums].each{|album| ...}}
+
+  The issue is the MySQL adapter doesn't release the database
+  connection while running each, and the second call to each gets the
+  same database connection (while the other query is still running),
+  because it is in the same thread.  Using #all for the outside query
+  ensures that the database connection is released before the block is
+  called.
+
+  The reason for this change was that the workaround provided for
+  MySQL could potentially cause issues with transactions for all
+  adapters.
+
+* String#asc and String#desc are no longer defined, as ordering on a
+  plain string column should be a no-op.  They are still defined
+  on LiteralStrings.
+
+* You can no longer abuse the SQL::Function syntax to use a table
+  alias with specified columns (e.g. :table[:col1, :col2, :col3])
+  or to cast to types (e.g. :x.cast_as(:varchar[20])).  Use a
+  LiteralString in both cases.