sequel 4.31.0 → 4.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7388e21a31fdf29fda8d3687cdf96011514b32f3
-  data.tar.gz: ea540316de1e370e88ad2c15bc2b53860f34f353
+  metadata.gz: d56404078cfe75cf79b2fe4b804e205d8a2e48d3
+  data.tar.gz: 587618022698a1b6f7076571e01361b080f3ea77
 SHA512:
-  metadata.gz: a674f18f2fe56030b484cddbd66e10fa221256609a6314d3f95f606dcd3092d39b96b41368eff9943f95094c7ef8702e1094fcf4d059a7fd3fee2cda8e1eb0de
-  data.tar.gz: 2ba7e438b33bf0601ac63eceaaf1858a91437bf4c35f4c95bd16c9a04e7fe990f975ed395b49d1ec4a42b56fe8a90506e74964421027aa3973105cccc3aa32e6
+  metadata.gz: 97590c69f6bef7d22b856c9e331256357cdb4bc5804a65747242c14e3e9c40149f134503f303ce410941181e7574253205e73482f5fe5501ce2d6bebaa94c6cc
+  data.tar.gz: cb19067f82ec892008af6e1064bfb107edce01df096e377606adade354dbfa59dad90aa55dd2a33dc1d7ede4b9c42f16e5f5850c864979e85dfbb63adbfceca6

data/CHANGELOG

@@ -1,3 +1,27 @@
+=== 4.32.0 (2016-03-01)
+
+* Use mutex for synchronizing access to association reflection cache on MRI (jeremyevans)
+
+* Add Dataset#delete_from on MySQL, allowing deletions from multiple tables in a single query (jeremyevans) (#1146)
+
+* Add no_auto_literal_strings extension, which makes SQL injection vulnerabilities less likely (jeremyevans)
+
+* Add Model.default_association_options, for setting option defaults for all future associations (jeremyevans)
+
+* Support :association_pks_nil association option in association_pks setter for determining how to handle nil (jeremyevans)
+
+* Make association_pks setter handle empty array correctly when :delay_pks is set (jeremyevans)
+
+* Add a setter method for one_through_one associations (jeremyevans)
+
+* Include :remarks entry in JDBC schema parsing output, containing comments on the column (olleolleolle) (#1143)
+
+* Support :eager_reload and :eager options to associations in tactical_eager_loading plugin (jeremyevans)
+
+* Make tactical_eager_loading not eager load if passing proc or block to association method (jeremyevans)
+
+* Make eager_each plugin handle eager loading for Dataset#first and similar methods (jeremyevans)
+
 === 4.31.0 (2016-02-01)
 
 * Convert types in association_pks setters before saving them, instead of just before running queries (jeremyevans)

data/Rakefile

@@ -93,7 +93,7 @@ run_spec = proc do |patterns|
   ENV['RUBYLIB'] = rubylib
 end
 
-spec_task = proc do |description, name, files|
+spec_task = proc do |description, name, files, coverage|
   desc description
   task name do
     run_spec.call(files)
@@ -106,11 +106,13 @@ spec_task = proc do |description, name, files|
     sh "#{rake} #{name} 2>&1 | egrep -v \"(: warning: instance variable @.* not initialized|: warning: method redefined; discarding old|: warning: previous definition of)\""
   end
 
-  desc "#{description} with coverage"
-  task :"#{name}_cov" do
-    ENV['COVERAGE'] = '1'
-    run_spec.call(files)
-    ENV.delete('COVERAGE')
+  if coverage
+    desc "#{description} with coverage"
+    task :"#{name}_cov" do
+      ENV['COVERAGE'] = '1'
+      run_spec.call(files)
+      ENV.delete('COVERAGE')
+    end
   end
 end
 
@@ -119,19 +121,19 @@ task :default => :spec
 desc "Run the core, model, and extension/plugin specs"
 task :spec => [:spec_core, :spec_model, :spec_plugin]
 
-spec_task.call("Run core and model specs together", :spec_core_model, './spec/core/*_spec.rb ./spec/model/*_spec.rb')
-spec_task.call("Run core specs", :spec_core, './spec/core/*_spec.rb')
-spec_task.call("Run model specs", :spec_model, './spec/model/*_spec.rb')
-spec_task.call("Run plugin/extension specs", :spec_plugin, './spec/extensions/*_spec.rb')
-spec_task.call("Run bin/sequel specs", :spec_bin, './spec/bin_spec.rb')
-spec_task.call("Run core extensions specs", :spec_core_ext, './spec/core_extensions_spec.rb')
-spec_task.call("Run integration tests", :spec_integration, './spec/integration/*_test.rb')
+spec_task.call("Run core and model specs together", :spec_core_model, './spec/core/*_spec.rb ./spec/model/*_spec.rb', true)
+spec_task.call("Run core specs", :spec_core, './spec/core/*_spec.rb', false)
+spec_task.call("Run model specs", :spec_model, './spec/model/*_spec.rb', false)
+spec_task.call("Run plugin/extension specs", :spec_plugin, './spec/extensions/*_spec.rb', true)
+spec_task.call("Run bin/sequel specs", :spec_bin, './spec/bin_spec.rb', false)
+spec_task.call("Run core extensions specs", :spec_core_ext, './spec/core_extensions_spec.rb', true)
+spec_task.call("Run integration tests", :spec_integration, './spec/integration/*_test.rb', true)
 
 %w'postgres sqlite mysql informix oracle firebird mssql db2 sqlanywhere'.each do |adapter|
-  spec_task.call("Run #{adapter} tests", :"spec_#{adapter}", "./spec/adapters/#{adapter}_spec.rb ./spec/integration/*_test.rb")
+  spec_task.call("Run #{adapter} tests", :"spec_#{adapter}", "./spec/adapters/#{adapter}_spec.rb ./spec/integration/*_test.rb", true)
 end
 
-spec_task.call("Run model specs without the associations code", :_spec_model_no_assoc, Dir["./spec/model/*_spec.rb"].delete_if{|f| f =~ /association|eager_loading/}.join(' '))
+spec_task.call("Run model specs without the associations code", :_spec_model_no_assoc, Dir["./spec/model/*_spec.rb"].delete_if{|f| f =~ /association|eager_loading/}.join(' '), false)
 desc "Run model specs without the associations code"
 task :spec_model_no_assoc do
   ENV['SEQUEL_NO_ASSOCIATIONS'] = '1'

data/doc/association_basics.rdoc

@@ -302,8 +302,6 @@ Examples:
   @artist.remove_album(@album)
   @artist.remove_all_albums
 
-one_through_one associations do not have any modification methods added.
-
 Note that the remove_all_* method does not call remove hooks defined on
 the association, it just issues a single query to the database.  If you
 want to remove all associated objects and call remove hooks, iterate
@@ -867,7 +865,13 @@ you also wanted to handle the Artist#remove_all_albums method:
 == Association Options
 
 Sequel's associations mostly share the same options.  For ease of understanding,
-they are grouped here by section
+they are grouped here by section.
+
+The defaults for any of these options can be set at the class level using
+<tt>Sequel::Model.default_association_options</tt>.  Many of these options
+are specific to particular associations and probably should not be set as
+defaults, but there certainly are options where a class level default makes
+sense.
 
 === Association Dataset Modification Options
 

data/doc/opening_databases.rdoc

@@ -62,6 +62,13 @@ For example:
 
   Sequel.connect('sqlite://blog.db'){|db| puts db[:users].count}  
 
+Note that if you do not pass a block to Sequel.connect, Sequel will automatically retain a
+reference to the object in the <tt>Sequel::DATABASES</tt> array.  So calling +Sequel.connect+
+multiple times (say once per request), can result in a memory leak.  For any application where
+database access is needed for a long period of time, it's best to store the result of
+Sequel.connection in a constant, as recommended above.
+
+== Using the Sequel.connect method
 == General connection options
 
 These options are shared by all adapters unless otherwise noted.

data/doc/release_notes/4.32.0.txt

@@ -0,0 +1,132 @@
+= New Features
+
+* A no_auto_string_literals plugin has been added, which removes the
+  automatic usage of strings in filter arguments as literal SQL code.
+  By default, if you do:
+
+    DB[:albums].where("name > 'N'")
+
+  By default Sequel will treat "name > 'N'" as SQL code.  However,
+  this makes it much easier to introduce SQL injection:
+
+    # SQL Injection vulnerability in default Sequel
+    DB[:albums].where("name > 'params[:letter]'")
+
+  Sequel does support using placeholders when using literal strings:
+
+    # Safe in default Sequel
+    DB[:albums].where("name > ?", params[:letter])
+
+  However, if you forget to use placeholders, you can end up with SQL
+  injection.  Accidental usage of filter strings derived from user
+  input as literal SQL code is probably the most common SQL injection
+  vector in applications using Sequel.
+
+  With the no_auto_string_literals extension, passing a plain string
+  as the first or only argument to a filter method raises an
+  exception.  If you want to use literal SQL code, you have to do so
+  explicitly:
+
+    DB[:albums].where(Sequel.lit("name > 'N'"))
+
+  You can also specify placeholders when using Sequel.lit:
+
+    DB[:albums].where(Sequel.lit("name > ?", params[:letter]))
+
+  Note that in many cases, you can avoid using literal SQL strings
+  completely:
+
+    DB[:albums].where{|v| v.name > params[:letter]}
+
+* one_through_one associations now support a setter method:
+
+    Foo.one_through_one :bar
+
+    foo = Foo[1]
+    foo.bar = Bar[2]
+    foo.bar = nil
+
+  This will check the current entry in the join table, and based on
+  the argument and the current entry, run a DELETE, INSERT, or UPDATE
+  query, or take no action if the join table is already in the
+  correct state.
+
+* Model.default_association_options has been added, which supports
+  default options for all future associations.  You can use this to
+  do:
+
+    Model.default_association_options = {:read_only=>true}
+
+  Which makes associations not create modification methods by default.
+  You could still create the modification methods by passing
+  :read_only=>true when creating association.
+
+* The tactical_eager_loading plugin now supports two additional
+  options when calling an association method: :eager and
+  :eager_reload. Example:
+
+    artist = Artist.all.first
+
+    # Loads all albums for all of the artists,
+    # and all tracks for all of those albums
+    artist.albums(:eager=>:tracks)
+
+    # Reload the artists association for all artists
+    artist.albums(:eager_reload=>true)
+
+  You can also use the :eager option for an eager loading callback:
+
+    # Eagerly load the albums with names starting with A-M
+    artist.albums(:eager=>proc{|ds| ds.where(:name > 'N')})
+
+* The association_pks plugin now supports an :association_pks_nil
+  association option in the association_pks setter, for determining
+  how nil values should be handled.
+
+  In Sequel <4.31.0, if you provided nil, it would either raise an
+  exception immediately if :delay_pks was not set, or on saving if
+  :delay_pks was set.
+
+  In Sequel 4.31.0, if :delay_pks was not set, it would remove all
+  associated rows.  If :delay_pks was set, it would do nothing.
+
+  You can now set :association_pks_nil=>:remove to remove all
+  associated values on nil, or :association_pks_nil=>:ignore to ignore
+  a nil value passed to the method.  Without :association_pks_nil set,
+  an exception will be raised.
+
+* Dataset#delete_from has been added on MySQL, allowing deletions from
+  multiple tables in a single query:
+
+    DB[:a].join(:b, :a_id=>:id).delete_from(:a, :b).delete
+    # DELETE a, b FROM a INNER JOIN b ON (b.a_id = a.id)
+
+* The JDBC schema parser now includes a :remarks entry for each
+  column, which contains comments on the column.
+
+= Other Improvements
+
+* The setter method added by the association_pks plugin now handles
+  the empty array correctly when :delay_pks is set.  Previously, if
+  the empty array was passed, Sequel made no modifications in this
+  case.  Sequel now correctly removes all associated values if an
+  empty array is passed.
+
+* The eager_each plugin now handles eager loading when using
+  Dataset#first and related methods.  Previously, the behavior was
+  unspecified. In Sequel <4.27.0 Dataset#first did eager loading
+  correctly in the eager case, but incorrectly in the eager_graph
+  case.  In Sequel 4.27.0-4.31.0, it did not do eager loading in
+  either case.
+
+* The tactical_eager_loading plugin will not automatically eager load
+  if passing a proc or block to an association method, since the proc
+  or block could be specific to the receiver.
+
+* Sequel now uses a mutex to synchronize access to the association
+  cache on MRI, as it does on other ruby implementations.
+
+= Backwards Compatibility
+
+* See above for changes in eager_each and association_pks plugin
+  behavior.

data/doc/schema_modification.rdoc

@@ -132,7 +132,7 @@ If provided with an array, +primary_key+ does not create a column, it just sets
 
 +foreign_key+ is used to create a foreign key column that references a column in another table (or the same table).
 It takes the column name as the first argument, the table it references as the second argument, and an options hash
-as it's third argument.  A simple example is:
+as its third argument.  A simple example is:
 
   create_table(:albums) do
     primary_key :id

data/doc/security.rdoc

@@ -44,34 +44,56 @@ There are basically two kinds of possible SQL injections in Sequel:
 
 ==== Full SQL Strings
 
-Some Sequel methods are designed to execute raw SQL, including:
+Some Sequel methods are designed to execute raw SQL strings, including:
 
 * Sequel::Database#execute
 * Sequel::Database#run
 * Sequel::Database#<<
-* Sequel::Database#[]
-* Sequel::Database#fetch
-* Sequel::Dataset#with_sql
+* Sequel::Dataset#fetch_rows
+* Sequel::Dataset#with_sql_all
+* Sequel::Dataset#with_sql_delete
+* Sequel::Dataset#with_sql_each
+* Sequel::Dataset#with_sql_first
+* Sequel::Dataset#with_sql_insert
+* Sequel::Dataset#with_sql_single_value
+* Sequel::Dataset#with_sql_update
 
 Here are some examples of use:
 
   DB.run 'SQL'
   DB << 'SQL'
   DB.execute 'SQL'
-  DB['SQL'].all
-  DB.fetch('SQL').all
-  DB.dataset.with_sql('SQL').all
+  DB.fetch_rows('SQL'){|row| }
+  DB.dataset.with_sql_all('SQL')
+  DB.dataset.with_sql_delete('SQL')
+  DB.dataset.with_sql_each('SQL'){|row| }
+  DB.dataset.with_sql_first('SQL')
+  DB.dataset.with_sql_insert('SQL')
+  DB.dataset.with_sql_single_value('SQL')
+  DB.dataset.with_sql_update('SQL')
 
 If you pass a string to these methods that is derived from user input, you open
-yourself up to SQL injection.  The Sequel::Database#run, Sequel::Database#<<, and
-Sequel::Database#execute methods are not designed to work at all with user input.
-If you must use them with user input, you should escape the user input manually
-via Sequel::Database#literal. Example:
+yourself up to SQL injection.  These methods are not designed to work at all
+with user input.  If you must call them with user input, you should escape the
+user input manually via Sequel::Database#literal. Example:
 
   DB.run "SOME SQL #{DB.literal(params[:user].to_s)}"
 
-With Sequel::Database#[], Sequel::Database#fetch and Sequel::Dataset#with_sql, you should use placeholders,
-in which case Sequel automatically literalizes the input:
+==== Full SQL Strings, With Possible Placeholders
+
+Other Sequel methods are designed to support execution of raw SQL strings that may contain placeholders:
+
+* Sequel::Database#[]
+* Sequel::Database#fetch
+* Sequel::Dataset#with_sql
+
+Here are some examples of use:
+
+  DB['SQL'].all
+  DB.fetch('SQL').all
+  DB.dataset.with_sql('SQL').all
+
+With these methods you should use placeholders, in which case Sequel automatically escapes the input:
 
   DB['SELECT * FROM foo WHERE bar = ?', params[:user].to_s]
 
@@ -144,11 +166,13 @@ following methods pass their arguments to a filter method:
 * Sequel::Dataset#first
 * Sequel::Dataset#last
 * Sequel::Dataset#[]
-* Sequel::Dataset#[]=
 
 The Model.find[rdoc-ref:Sequel::Model::ClassMethods#find] and Model.find_or_create[rdoc-ref:Sequel::Model::ClassMethods#find_or_create]
 class methods also call down to the filter methods.
 
+The no_auto_string_literals extension can be used to remove the default support 
+for plain strings as literal strings in filter methods.
+
 ==== SQL Fragment passed to Dataset#update
 
 Similar to the filter methods, Sequel::Dataset#update also treats a
@@ -164,6 +188,9 @@ Instead, you should do:
 
   DB[:table].update(:column => params[:value].to_s) # Safe
 
+The no_auto_string_literals extension can also be used to remove the default support
+for plain strings as literal strings in update methods.
+
 ==== SQL Fragment passed to Dataset#lock_style
 
 The Sequel::Dataset#lock_style method also treats an input string 
@@ -222,12 +249,12 @@ pass any of those values derived from user input, you are dealing with the same
 Note that the issues with SQL identifiers do not just apply to places where
 strings are used as identifiers, they also apply to all places where Sequel
 uses symbols as identifiers.  However, if you are creating symbols from user input,
-you at least have a denial of service vulnerability, and possibly a more serious
-vulnerability.
+you at least have a denial of service vulnerability in ruby <2.2, and possibly a
+more serious vulnerability.
 
 == Denial of Service
 
-Sequel converts some strings to symbols.  Because symbols in ruby are not
+Sequel converts some strings to symbols.  Because symbols in ruby <2.2 are not
 garbage collected, if the strings that are converted to symbols are
 derived from user input, you have a denial of service vulnerability due to
 memory exhaustion.
@@ -302,17 +329,34 @@ they also allow mass assignment:
   Album.new(params[:album]) # Mass Assignment
   Album.create(params[:album]) # Mass Assignment
 
-Instead of these methods, it is encouraged to either use the
-Model#set_only[rdoc-ref:Sequel::Model::InstanceMethods#set_only],
+When the argument is derived from user input, instead of these methods, it is encouraged to either use 
+Model#set_fields[rdoc-ref:Sequel::Model::InstanceMethods#set_fields] or
+Model#update_fields[rdoc-ref:Sequel::Model::InstanceMethods#update_fields],
+which allow you to specify which fields to allow on a per-call basis.  This
+pretty much eliminates the chance that the user will be able to set a column
+you did not intend to allow:
+
+  album.set_fields(params[:album], [:name, :copies_sold])
+  album.update_fields(params[:album], [:name, :copies_sold])
+
+These two methods iterate over the second argument (+:name+ and +:copies_sold+ in
+this example) instead of iterating over the entries in the first argument
+(<tt>params[:album]</tt> in this example).
+
+In addition to these two methods, you can also use 
+Model#set_only[rdoc-ref:Sequel::Model::InstanceMethods#set_only] or
 Model#update_only[rdoc-ref:Sequel::Model::InstanceMethods#update_only],
-Model#set_fields[rdoc-ref:Sequel::Model::InstanceMethods#set_fields], or
-Model#update_fields[rdoc-ref:Sequel::Model::InstanceMethods#update_fields]
-methods, which allow you to specify which fields
-to allow on a per-call basis.  This pretty much eliminates the chance that the
-user will be able to set a column you did not intend to allow:
+which are similar but iterate over the entries in the first argument, checking
+the second argument to see if setting the entries is allowed.
 
   album.set_only(params[:album], [:name, :copies_sold])
-  album.set_fields(params[:album], [:name, :copies_sold])
+  album.update_only(params[:album], [:name, :copies_sold])
+
+If you expect all entries in the second argument to be present in the first
+argument, use +set_fields+ or +update_fields+.  If you are not sure if all
+arguments in the second argument will be present in the first argument, but
+do not want to allow setting any column other than the ones listed in the
+second argument, use +set_only+ or +update_only+.
 
 You can override the columns to allow by default during mass assignment via
 the Model.set_allowed_columns[rdoc-ref:Sequel::Model::ClassMethods#set_allowed_columns] class method.  This is a good
@@ -331,7 +375,7 @@ their type.  For example:
 
   Album.where(:id=>params[:id])
 
-is probably a bad idea.  Assuming you are using a web framework, params\[:id\] could
+is probably a bad idea.  Assuming you are using a web framework, <tt>params[:id]</tt> could
 be a string, an array, a hash, or nil.
 
 Assuming that +id+ is an integer field, you probably want to do:

data/doc/testing.rdoc

@@ -155,6 +155,7 @@ The SEQUEL_INTEGRATION_URL environment variable specifies the Database connectio
 SEQUEL_COLUMNS_INTROSPECTION :: Use the columns_introspection extension when running the specs
 SEQUEL_CONNECTION_VALIDATOR :: Use the connection validator extension when running the specs
 SEQUEL_ERROR_SQL :: Use the error_sql extension when running the specs
+SEQUEL_NO_AUTO_LITERAL_STRINGS :: Use the no_auto_string_literals extension when running the specs
 SEQUEL_NO_CACHE_ASSOCIATIONS :: Don't cache association metadata when running the specs
 SEQUEL_NO_CHECK_SQLS :: Don't check for specific SQL syntax when running the specs
 SEQUEL_NO_PENDING :: Don't skip any specs, try running all specs (note, can cause lockups for some adapters)