sequel 4.26.0 → 5.37.0

data/doc/release_notes/2.0.0.txt

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

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