sequel 3.47.0 → 3.48.0

data/doc/prepared_statements.rdoc

@@ -87,16 +87,13 @@ to create prepared statements dynamically at runtime.
 === PostgreSQL
 
 If you are using the ruby-postgres or postgres-pr driver, PostgreSQL uses the
-default emulated support.  If you are using ruby-pg, there is native support,
-but it may require type specifiers on some old versions (generally not anymore).
-You can add a __* suffix to the placeholder symbol to specify a type, which
-casts to that type in the SQL (e.g.  :$name__text, which will be compiled to
-"$1::text" in the SQL).  Prepared statements are always server side.
+default emulated support.  If you are using ruby-pg, there is native support
+for both prepared statements and bound variables.  Prepared statements are
+always server side.
 
 === SQLite
 
-SQLite supports both prepared statements and bound variables.  Prepared
-statements are cached per connection.
+SQLite supports both prepared statements and bound variables.
 
 === MySQL/Mysql2
 
@@ -119,8 +116,7 @@ Microsoft SQL Server doesn't support true prepared statements.
 
 === IBM_DB
 
-DB2 supports both prepared statements and bound variables.  Prepared
-statement objects are cached per connection.
+DB2 supports both prepared statements and bound variables.
 
 === Oracle
 

data/doc/querying.rdoc

@@ -42,7 +42,10 @@ by its primary key value:
   # SELECT * FROM artists WHERE id = 1
   => #<Artist @values={:name=>"YJM", :id=>1}>
 
-If there is no record with the given primary key, nil will be returned.
+If there is no record with the given primary key, nil will be returned. If you want
+to raise an exception if no record is found, you can use <tt>Sequel::Model.with_pk!</tt>:
+
+  artist = Artist.with_pk!(1)
 
 ==== Using +first+
 
@@ -63,6 +66,9 @@ Any options you pass to +first+ will be used as a filter:
   # SELECT * FROM artists WHERE (name LIKE 'Y%') LIMIT 1
   => #<Artist @values={:name=>"YJM", :id=>1}>
   
+If there is no matching row, +first+ will return nil.  If you want to
+raise an exception instead, use <tt>first!</tt>.
+
 <tt>Sequel::Dataset#[]</tt> is basically an alias for +first+, except it
 requires an argument:
 
@@ -77,16 +83,17 @@ Dataset#[] does not (unless it is a model dataset).
 
 If you want the last record in the dataset,
 <tt>Sequel::Dataset#last</tt> is an obvious method to use.  Note
-that last requires that the dataset be ordered.  Without an order, any
-object can be considered the first as well as the last.
+that last requires that the dataset be ordered, unless the
+dataset is a model dataset.  For a model dataset, +last+ will do a
+reverse order by the primary key field:
 
-  artist = Artist.order(:name).last
-  # SELECT * FROM artists ORDER BY name DESC LIMIT 1
+  artist = Artist.last
+  # SELECT * FROM artists ORDER BY id DESC LIMIT 1
   => #<Artist @values={:name=>"YJM", :id=>1}>
 
-Note that all +last+ does is reverse the order of the dataset and then
+Note that what +last+ does is reverse the order of the dataset and then
 call +first+.  This is why +last+ raises a Sequel::Error if there is no
-order on the dataset, because otherwise it would provide the same record
+order on a plain dataset, because otherwise it would provide the same record
 as +first+, and most users would find that confusing.
 
 Note that +last+ is not necessarily going to give you the last record
@@ -302,8 +309,7 @@ any part of the query at any time.
 
 Filtering is probably the most common dataset modifying action done in Sequel.
 Both the +where+ and +filter+ methods filter the dataset by modifying the
-dataset's WHERE clause.  While not quite aliases of each other, they operate
-the same in most cases.  Both accept a wide variety of input formats, discussed
+dataset's WHERE clause.  Both accept a wide variety of input formats, discussed
 below.
 
 === Hashes
@@ -454,7 +460,7 @@ sure of what you are doing.
 
   Artist.where("id = #{params[:id]}") # Don't do this!
   Artist.where("id = ?", params[:id]) # Do this instead
-  Artist.where(:id=>params[:id]) # Even better
+  Artist.where(:id=>params[:id].to_i) # Even better
 
 === Inverting
 
@@ -650,7 +656,7 @@ A common use of grouping is to count based on the number of grouped rows,
 and Sequel provides a +group_and_count+ method to make this easier:
 
   Album.group_and_count(:artist_id)
-  # SELECT artist_id, COUNT(*) AS count FROM albums GROUP BY artist_id
+  # SELECT artist_id, count(*) AS count FROM albums GROUP BY artist_id
 
 This will return the number of albums for each artist_id.
 
@@ -673,26 +679,14 @@ before.  One possible use is if you only wanted to return artists
 who had at least 10 albums:
 
   Album.group_and_count(:artist_id).having{count >= 10}
-  # SELECT artist_id, COUNT(*) AS count FROM albums
+  # SELECT artist_id, count(*) AS count FROM albums
   # GROUP BY artist_id HAVING count >= 10
 
-If you have an existing HAVING clause on your dataset, then +filter+
-will add to the HAVING clause instead of the WHERE clause:
-
-  Album.group_and_count(:artist_id).
-   having{count >= 10}.filter{count < 15}
-  # SELECT artist_id, COUNT(*) AS count FROM albums
-  # GROUP BY artist_id HAVING count >= 10 AND count < 15
-
-This can be confusing, so it is recommended that you always use
-either +having+ or +where+ instead of +filter+, indicating which
-clause that would want affected.
-
 Both the WHERE clause and the HAVING clause are removed by +unfiltered+:
 
   Album.group_and_count(:artist_id).having{count >= 10}.
    where(:name.like('A%')).unfiltered
-  # SELECT artist_id, COUNT(*) AS count FROM albums GROUP BY artist_id
+  # SELECT artist_id, count(*) AS count FROM albums GROUP BY artist_id
 
 == Joins
 
@@ -806,7 +800,8 @@ a JOIN using case insensitive string comparison:
   # SELECT * FROM albums INNER JOIN artists
   #  ON (lower(artists.name) = lower(albums.artist_name))
 
-Note how the arguments to lower were qualified correctly in both cases.
+Note how the arguments to lower were qualified correctly in both cases. Starting in Sequel 4,
+the <tt>:qualify=>:deep</tt> option is going to become the default.
 
 ==== USING Joins
 
@@ -922,7 +917,7 @@ it and when the transaction ends.
 
 === Optimistic Locking
 
-One of Sequel's built-in model plugins is an optimistic locking plugin, which provides
+One of the model plugins that ships with Sequel is an optimistic locking plugin, which provides
 a database independent way to detect and raise an error if two different connections
 modify the same row.  It's useful for things like web forms where you cannot keep a
 transaction open while the user is looking at the form, because of the web's
@@ -994,7 +989,7 @@ for each of these aggregate functions.
 +count+ just returns the number of records in the dataset.
 
   Album.count
-  # SELECT COUNT(*) AS count FROM albums LIMIT 1
+  # SELECT count(*) AS count FROM albums LIMIT 1
   => 2
   
 The other methods take a column argument and call the aggregate function with

data/doc/reflection.rdoc

@@ -108,3 +108,14 @@ You can get an array of all association reflections via Model.all_association_re
 Finally, you can get a hash of association reflections via Model.association_reflections:
 
   Model.association_reflections # {:association1=>{:name=>:association1, :type=>:many_to_one, :model=>Model, ...}, ...}
+
+== Validations Defined
+
+When using the validation_class_methods plugin, you can use the validation_reflections class method to get a hash with validation reflection information.  This returns a hash keyed on the column name symbol:
+
+  Model.validation_reflections[:column] # => [[:presence, {}], [:length, {:maximum=>255, :message=>'is just too long'}]]
+
+Similarly, when using the constraint_validations plugin, you can use the constraint_validation_reflections class method:
+
+  Model.constraint_validation_reflections[:column] # => [[:presence, {}], [:max_length, {:argument=>255, :message=>'is just too long'}]]
+

data/doc/release_notes/3.48.0.txt

@@ -0,0 +1,477 @@
+= Deprecation Warnings
+
+The main change in Sequel 3.48.0 is the deprecation of Sequel
+features that will be modified, moved, or removed in Sequel 4.
+For the reasoning behind these changes, please review the
+commits logs at
+https://github.com/jeremyevans/sequel-4-plans/commits/master
+
+== Deprecation Logging
+
+If you use a deprecated method or feature, Sequel will by default
+print a deprecation message and 10 lines of backtrace to stderr
+to easily allow you to figure out which code needs to be
+updated.  You can change where the deprecation messages go and how
+many lines of backtrace are given using the following:
+
+  # Log deprecation information to a file
+  Sequel::Deprecation.output = File.open('deprecated.txt', 'wb')
+  
+  # Turn off all deprecation logging
+  Sequel::Deprecation.output = nil
+
+  # Use 5 lines of backtrace when logging deprecation messages
+  Sequel::Deprecation.backtrace_filter = 5
+  
+  # Use all backtrace lines when logging deprecation messages
+  Sequel::Deprecation.backtrace_filter = true
+  
+  # Don't include backtraces in the deprecation logging
+  Sequel::Deprecation.backtrace_filter = false
+
+  # Select which backtrace lines to output
+  Sequel::Deprecation.backtrace_filter = \
+    lambda{|line, line_no| line_no < 3 || line =~ /my_app/}
+
+== Major Change
+
+* The core extensions will no longer be loaded by default. You will
+  have to use `Sequel.extension :core_extensions` to load the core
+  extensions.
+
+* The Symbol#[] and Symbol#{<,>,<=,>=} methods will no longer be
+  provided by the core extensions on ruby 1.8. You will have to
+  use `Sequel.extension :ruby18_symbol_extensions` to use them.
+
+== Core Behavior Changes
+
+* Dataset#filter becomes an alias for #where, and #exclude
+  becomes an alias for #exclude_where. You will have to
+  use `DB.extension :filter_having` to get the previous behavior.
+  Dataset#and and #or will also only affect the WHERE clause.
+
+* Dataset#and, #or, and #invert will not raise errors for no existing
+  filter.
+
+* Dataset#select_more becomes an alias for #select_append.
+
+* Dataset#select and #from will not longer consider a hash argument as
+  an alias specification. You will have to use
+  `DB.extension :hash_aliases` to get the previous behavior.
+
+* Database#dataset and Dataset.new will not take an options hash.
+
+* Database#transaction :disconnect=>:retry option will be removed.
+
+* Calling Dataset#add_graph_aliases before #graph or #set_graph_aliases
+  will raise an Error.
+
+* Datasets will have a frozen options hash by default.
+
+* Dataset#set_overrides and #set_defaults will move to the
+  set_overrides extension.
+
+* Sequel.empty_array_handle_nulls will be removed.  To get the
+  empty_array_handle_nulls = false behavior, you will have to
+  use `DB.extension :empty_array_ignore_nulls`.
+
+* The second argument to Dataset #union, #intersect, and #except must
+  be an options hash if it is given.
+
+* The fourth argument to Dataset #join_table must be an options
+  hash if it is given.
+
+* Using a mismatched number of placeholders and arguments in a
+  placeholder literal string will raise an error.
+
+* Dataset#graph_each will move to the graph_each extension.
+
+* Database#default_schema will be removed.
+
+* Dataset#[]= will be moved to the sequel_3_dataset_methods
+  extension.
+
+* Dataset#insert_multiple will be moved to the
+  sequel_3_dataset_methods extension.
+
+* Dataset#set will be moved to the sequel_3_dataset_methods
+  extension.
+
+* Dataset#to_csv will be moved to the sequel_3_dataset_methods
+  extension.
+
+* Dataset#db= and #opts= setters will be moved to the
+  sequel_3_dataset_methods extension.
+
+* Dataset#qualify_to and #qualify_to_first_source will be moved to
+  the sequel_3_dataset_methods extension.
+
+* Remove default methods that raise Sequel::NotImplemented: 
+  Database#connect, #execute, #foreign_key_list, #indexes, #tables,
+  and #views, and Dataset#fetch_rows.
+
+* Sequel::SQL::Expression#to_s will be removed.
+
+* All Dataset methods in Dataset::PUBLIC_APPEND_METHODS except for
+  #literal, #quote_identifier, and #quote_schema_table will be
+  removed.
+
+* All Dataset methods in Dataset::PRIVATE_APPEND_METHODS will
+  be removed.
+
+* Sequel k_require, ts_require, tsk_require, and
+  check_requiring_thread will be removed.
+
+* Dataset.def_append_methods will be removed.
+
+* Dataset#table_ref_append will be removed.
+
+* Sequel.virtual_row_instance_eval accessor will be removed.
+
+* Database#reset_schema_utility_dataset will be removed.
+
+== Adapter Behavior Changes
+
+* The Database#do method will be removed from the ado, db2, dbi,
+  informix, odbc, openbase, and oracle adapters.
+
+* The jdbc adapter will raise an error when parsing the schema
+  for a table if it detects results for the same table name in
+  multiple schemas.
+
+* The Database#query method will be removed from the informix
+  adapter.
+
+* Dataset#lock on PostgreSQL will check the given lock mode.
+
+* Sequel will check the client_min_messages setting before
+  use on PostgreSQL.
+
+* Prepared statement placeholders on PostgreSQL will no longer
+  support implicit casting via :$x__type.
+
+== Extension Behavior Changes
+
+* The following extensions will no longer make global changes to
+  the Database and Dataset classes: null_dataset, pagination,
+  pretty_table, query, schema_caching, schema_dumper,
+  select_remove, and to_dot.  These will be changed to
+  Database/Dataset specific extensions.
+  
+* The pg_auto_parameterize and pg_statement_cache extensions will
+  be removed.
+
+* Sequel::Dataset.introspect_all_columns will be removed from the
+  columns_introspection extension.
+
+* PGRangeOp#starts_before and #ends_after will be removed from the
+  pg_range_ops extension.
+
+== Model Behavior Changes
+
+* Model#initialize will accept only one argument.
+
+* The after_initialize hook will be moved to a plugin.
+
+* Move blacklist-based security methods (#set_except, #update_except,
+  .set_restricted_columns) to a plugin.
+
+* The :eager_loader and :eager_grapher association option procs will
+  always be passed a hash.
+
+* Model string column setters will consider array and hash input to
+  be invalid.
+
+* Remove save taking multiple arguments for the columns to save.
+  Add Model#save :columns option for saving specific columns. 
+
+* Don't automatically choose a reciprocal association with a condition
+  or block.
+
+* Don't automatically set up reciprocal associations if multiple ones
+  match.
+
+* Model::Errors#[] will no longer modify the receiver.  If you want
+  autovivification, use the active_model plugin. 
+
+* Model.set_primary_key will not longer accept composite keys as
+  multiple arguments.
+
+* The correlated_subquery eager limit strategy will be removed.
+
+* The following Model class dataset methods will be removed: print,
+  each_page, paginate, set, add_graph_aliases, insert_multiple, query,
+  set_overrides, set_defaults, to_csv.
+
+* The Model.{destroy,delete,update} class dataset methods will be
+  moved to the scissors plugin.
+
+* Model#pk_or_nil will be removed.
+
+* Model#set_values will no longer be called directly by any Sequel
+  code, and overriding it is deprecated. It will be removed in Sequel
+  4.1.
+
+* Model.cache_anonymous_models accessor will move to Sequel module.
+
+* Model::InstanceMethods.class_attr_overridable and
+  .class_attr_reader will be removed.
+
+* The :one_to_one option check for one_to_many associations will
+  be removed.
+
+== Plugin Behavior Changes
+
+* Public dataset methods will no longer have class methods
+  automatically added.
+
+* The validates_not_string validation will be removed from the
+  validation_class_methods and validation_helpers plugin.
+
+* In the json_serializer plugin, the to_json :root=>true option
+  means :root=>:collection instead of :root=>:both.
+
+* In the json_serializer plugin, the to_json :naked option will
+  default to true, and there will not be way to add the JSON.create_id
+  automatically.
+
+* In the json_serializer plugin, from_json will no longer automatically
+  delete the JSON.create_id key from the input hash.
+
+* The #to_json and #to_xml :all_columns and :all_associations options
+  in the json_serializer and xml_serializer plugins will be removed.
+
+* The Model.json_create method will be removed from the
+  json_serializer plugin.
+
+* The validates_type validation will raise validation errors for nil
+  if :allow_nil=>true is not used.
+
+* auto_validate_presence_columns will be removed from the
+  auto_validations plugin 
+
+* The identity_map plugin will be removed.
+
+== Internal Changes
+
+* The sequel_core.rb and sequel_model.rb files will be removed.
+
+* Dataset#{quote_identifiers,identifier_output_method,
+  identifier_input_method} will assume Database implements the
+  methods.
+
+= Forwards Compatibility
+
+Not all changes planned in Sequel 4 have deprecation warnings.
+The following changes will be made in Sequel 4 but do not have
+deprecation warnings in 3.48.0:
+
+* The threaded connection pools will default to
+  :connection_handling=>:queue.  You can manually set
+  :connection_handling=>:stack to get the current behavior.
+
+* Dataset#join_table will default to :qualify=>:deep.  You can
+  manually set :qualify=>:symbol to get the current behavior.  This
+  can be set at a global level by overriding
+  Dataset#default_join_table_qualification.
+
+* Model.raise_on_typecast_failure will default to false.  Set this to
+  true to get the current behavior of raising typecast errors in the
+  setter methods.
+
+* Model#save will no longer call Model#_refresh or Model#set_values
+  internally after an insert.  Manually refreshes will be treated
+  differently than after creation refreshes in Sequel 4.
+
+* On SQLite, integer_booleans will be true by default.  Set this to
+  false to get the current behavior of 't' for true and 'f' for false.
+
+* On SQLite, use_timestamp_timezones will be false by default.  Set
+  this to true to get the current behavior with timezone information
+  in timestamps.
+
+* The default value for most option hash arguments will be an empty
+  frozen hash.  If you are overriding methods and modifying option
+  hashes, fix your code.
+
+* The defaults_setter plugin will work in a lazy manner instead of
+  an eager manner.  If you must have the values hash contain defaults
+  for new objects (instead of just getting defaults from getter
+  methods), you'll need to fork the current plugin.
+
+* Model#set_all will allow setting the primary key columns.
+
+* The many_to_one_pk_lookup plugin will be integrated into the
+  default associations support.
+
+* The association_autoreloading plugin will be integrated into the
+  default associations support.
+
+* Plugins will extend the class with ClassMethods before including
+  InstanceMethods in the class.
+
+* Dataset#get, #select_map, and #select_order_map will automatically
+  add aliases for unaliased expressions if given a single expression.
+
+* Database#tables and #views on PostgreSQL will check against
+  the current schemas in the search path.
+
+* Sequel::SQL::SQLArray alias for ValueList will be removed.
+
+* Sequel::SQL::NoBooleanInputMethods will be removed.
+
+* Sequel::NotImplemented will be removed.
+
+* Sequel::Model::EMPTY_INSTANCE_VARIABLES will be removed.
+
+* Sequel will no longer provide a default database for the adapter or
+  integration specs.
+
+= New Features
+
+* You can now choose which Errors class to use on a per model basis
+  by overriding Model#errors_class.
+
+* The following Database methods have been added to check for support:
+  supports_index_parsing?, supports_foreign_key_parsing?,
+  support_table_listing?, supports_view_listing?.
+
+* The pg_hstore_ops extension now integrates with the pg_array,
+  pg_hstore, and pg_array_ops extensions, allowing you to pass in
+  arrays and hashes to be treated as PGArrays and HStores, and
+  returning ArrayOps for PostgreSQL functions/operators that
+  return arrays.
+
+* Sequel.object_to_json and Sequel.json_parser_error_class
+  have been added and all internal json usage uses them, so you
+  can now override these methods if you want to use an alternative
+  json library with Sequel.
+
+* The association_proxies plugin now accepts a block allowing the
+  user control over which methods are proxied to the dataset or
+  the cached array of instances.  You can base the decision on
+  where to send the method using a variety of factors including
+  the method name, the method arguments, the state of the current
+  instance, or the related association.  Here's an example of a
+  simple case just depending on the name of the method; 
+
+    Model.plugin :association_proxies do |opts|
+     [:find, :where, :create].include?(opts[:method])
+    end
+
+  If the block returns true, the method is sent to the dataset,
+  otherwise it is sent to the array of associated objects.
+
+* The auto_validations plugin now accepts a :not_null=>:presence
+  option, for doing a presence validation instead of a not_null
+  validation.  This is useful for databases with NOT NULL
+  constraints where you also want to disallow empty strings.
+
+* The auto_validations plugin now validates against explicit nil
+  values in NOT NULL columns that have defaults.
+
+* The constraint_validations plugin now reflects validations, using
+  Model.constraint_validation_reflections.
+
+    Model.constraint_validation_reflections[:column]
+    # => [[:presence, {}],
+    #     [:max_length, {:argument=>255, :message=>'just too long'}]]
+
+* The constraint_validations plugin can now be set to pass specific
+  validations options to the validation_helpers plugin.  This can be
+  useful if using the auto_validations plugin with this plugin to
+  avoid duplicate error messages for nil values:
+
+    Model.plugin :constraint_validations,
+      :validates_options=>{:presence=>{:allow_nil=>true}}
+
+* The named_timezones extension can now be loaded as a database
+  extension, which allows for automatic conversions of string
+  timezones:
+
+    DB.extension :named_timezones
+    DB.timezone = 'America/Los_Angeles'
+
+* Offsets are now emulated by Microsoft Access using a combination
+  of reverse orders and total counts.  This is slow, especially on
+  large datasets, but probably better than having no support at all.
+  It is also possible to use the same code to support Microsoft
+  SQL Server 2000, but as Sequel does not support that (minimum
+  supported version is 2005), you have to do it manually:
+
+    Sequel.require 'adapters/utils/emulate_offset_with_reverse_and_count'
+    DB.extend_datasets Sequel::EmulateOffsetWithReverseAndCount
+
+= Other Improvements
+
+* Dataset#clone is now faster.
+
+* Database methods that create datasets (fetch, from, select, get)
+  are now faster.
+
+* Model.with_pk and .with_pk! are now faster.
+
+* Dataset#or now just clones if given an empty argument, similar
+  to Dataset#where.
+
+* Sequel now correctly frees statements after using them in the
+  ibmdb adapter.  Previously, they weren't freed until GC, which
+  could result in errors if all available handles are in use.
+
+* Dataset creation is now faster on Microsoft SQL Server.
+
+* The mediumint and mediumtext types are now recognized on MySQL.
+
+* The ado adapter now handles disconnecting an already disconnected
+  connection.
+
+* The auto_validations plugin now works on databases that don't
+  support index parsing.  However, it will not set up automatic
+  uniqueness validations on such databases.
+
+* The validation_helpers is more strict in some cases when checking
+  for nil values, using a specific nil check instead of general
+  falsely check.
+
+* The table inheritance plugins now correctly handle usage of
+  set_dataset in a subclass.
+
+* The bin/sequel command line tool now has specs.
+
+= Backwards Compatibility
+
+* Sequel now uses aliases for many internal Dataset#get calls, such
+  as those used by table_exists? and max. 
+
+* Sequel now no longer uses class variables internally.  Instead,
+  instance variables of the Sequel::Database class are used.
+
+* Sequel now sets up the identifier mangling methods on Database
+  initialization instead of on first use.
+
+* The private Database#adapter_initialize method has been added for
+  per adapter configuration.  All internal adapters have been switched
+  to use this method instead of overridding initialize, and all
+  external adapters should as well.  This makes sure that Database
+  instances are not added to Sequel::DATABASES until they have been
+  completely initialized.
+
+* Virtual row blocks no longer convert their return values to an array.
+  Among other things, this means that having a virtual row block return
+  a hash works as expected.
+
+* The private Dataset#hash_key_symbol method now only takes a single
+  argument.
+
+* Database#constraint_validations in the constraint_validations plugin
+  now returns raw hash rows, instead of arrays of validation method
+  call arguments.
+
+* Dataset#count now uses a lowercase count function in the SQL.
+
+* Passing a non-String or Hash as the first argument to an adapter
+  method (e.g. Sequel.postgres(1)) now raises an error.  Before, this used
+  to work on some adapters that implicitly converted the database
+  name to a string.
+
+* The stats and dcov rake tasks were removed.