sequel 5.8.0 → 5.38.0

data/doc/postgresql.rdoc

@@ -63,6 +63,14 @@ into the Database instance:
   DB.extension :pg_array
   Sequel.extension :pg_array_ops
 
+With regard to common database types, please note that the generic String type
+is +text+ on PostgreSQL and not <tt>varchar(255)</tt> as it is on some other
+databases.  +text+ is PostgreSQL's recommended type for storage of text data,
+and is more similar to Ruby's String type as it allows for unlimited length.
+If you want to set a maximum size for a text column, you must specify a
+<tt>:size</tt> option.  This will use a <tt>varchar($size)</tt> type and
+impose a maximum size for the column.
+
 == PostgreSQL-specific DDL Support
 
 === Exclusion Constraints
@@ -131,6 +139,77 @@ conversion via a USING clause, and Sequel supports this using the <tt>:using</tt
   # ALTER TABLE "table" ALTER COLUMN "unix_time" TYPE timestamp
   #   USING (CAST('epoch' AS timestamp) + (CAST('1 second' AS interval) * "unix_time"))
 
+=== Creating Partitioned Tables
+
+PostgreSQL allows marking tables as partitioned tables, and adding partitions to such tables. Sequel
+offers support for this.  You can create a partitioned table using the +:partition_by+ option and
++:partition_type+ options (the default partition type is range partitioning):
+
+  DB.create_table(:table1, partition_by: :column, partition_type: :range) do
+    Integer :id
+    Date :column
+  end
+
+  DB.create_table(:table2, partition_by: :column, partition_type: :list) do
+    Integer :id
+    String :column
+  end
+
+  DB.create_table(:table3, partition_by: :column, partition_type: :hash) do
+    Integer :id
+    Integer :column
+  end
+
+To add partitions of other tables, you use the +:partition_of+ option.  This option will use
+a custom DSL specific to partitioning other tables. For range partitioning, you can use the
++from+ and +to+ methods to specify the inclusive beginning and exclusive ending of the
+range of the partition.  You can call the +minvalue+ and +maxvalue+ methods to get the minimum
+and maximum values for the column(s) in the range, useful as arguments to +from+ and +to+:
+
+  DB.create_table(:table1a, partition_of: :table1) do
+    from minvalue
+    to 0
+  end
+  DB.create_table(:table1b, partition_of: :table1) do
+    from 0
+    to 100
+  end
+  DB.create_table(:table1c, partition_of: :table1) do
+    from 100
+    to maxvalue
+  end
+
+For list partitioning, you use the +values_in+ method.  You can also use the +default+ method
+to mark a partition as the default partition:
+
+  DB.create_table(:table2a, partition_of: :table2) do
+    values_in 1, 2, 3
+  end
+  DB.create_table(:table2b, partition_of: :table2) do
+    values_in 4, 5, 6
+  end
+  DB.create_table(:table2c, partition_of: :table2) do
+    default
+  end
+
+For hash partitioning, you use the +modulus+ and +remainder+ methods:
+
+  DB.create_table(:table3a, partition_of: :table3) do
+    modulus 3
+    remainder 0
+  end
+  DB.create_table(:table3b, partition_of: :table3) do
+    modulus 3
+    remainder 1
+  end
+  DB.create_table(:table3c, partition_of: :table3) do
+    modulus 3
+    remainder 2
+  end
+
+There is currently no support for using custom column or table constraints in partitions of
+other tables.  Support may be added in the future.
+
 === Creating Unlogged Tables
 
 PostgreSQL allows users to create unlogged tables, which are faster but not crash safe.  Sequel
@@ -301,6 +380,18 @@ can pass an +:update+ option with a hash of values to update.  You must pass eit
   DB[:table].insert_conflict(target: :a, update: {b: Sequel[:excluded][:b]}).insert(a: 1, b: 2)
   # INSERT INTO TABLE (a, b) VALUES (1, 2)
   # ON CONFLICT (a) DO UPDATE SET b = excluded.b
+
+If you want to update existing rows but using the current value of the column, you can build
+the desired calculation using <tt>Sequel[]</tt>
+
+  DB[:table]
+    .insert_conflict(
+      target: :a,
+      update: {b: Sequel[:excluded][:b] + Sequel[:table][:a]}
+    )
+    .import([:a, :b], [ [1, 2] ])
+  # INSERT INTO TABLE (a, b) VALUES (1, 2)
+  # ON CONFLICT (a) DO UPDATE SET b = (excluded.b + table.a)
  
 Additionally, if you only want to do the update in certain cases, you can specify an
 +:update_where+ option, which will be used as a filter.  If the row doesn't match the
@@ -321,12 +412,12 @@ Dataset#overriding_system_value and Dataset#overriding_user_value to use this ne
 syntax:
 
   DB.create_table(:table){primary_key :id}
-  # Ignore the given value for id, using the identity's sequence value
+  # Ignore the given value for id, using the identity's sequence value.
   DB[:table].overriding_user_value.insert(:id=>1)
 
   DB.create_table(:table){primary_key :id, :identity=>:always}
   # Force the use of the given value for id, because otherwise the insert will
-  # raise an error, since GENERATED ALWAYS was using when creating the column.
+  # raise an error, since GENERATED ALWAYS was used when creating the column.
   DB[:table].overriding_system_value.insert(:id=>1)
 
 === Distinct On Specific Columns
@@ -337,6 +428,20 @@ rows that are distinct on just those columns:
   DB[:table].distinct(:id).all
   # SELECT DISTINCT ON ("id") * FROM "table"
 
+=== Calling PostgreSQL 11+ Procedures <tt>postgres only</tt>
+
+PostgreSQL 11+ added support for procedures, which are different from the user defined
+functions that PostgreSQL has historically supported.  These procedures are
+called via a special +CALL+ syntax, and Sequel supports them via
+<tt>Database#call_procedure</tt>:
+
+  DB.call_procedure(:foo, 1, "bar")
+  # CALL foo(1, 'bar')
+
+<tt>Database#call_procedure</tt> will return a hash of return values if
+the procedure returns a result, or +nil+ if the procedure does not return
+a result.
+
 === Using a Cursor to Process Large Datasets <tt>postgres only</tt>
 
 The postgres adapter offers a <tt>Dataset#use_cursor</tt> method to process large result sets

data/doc/release_notes/5.10.0.txt

@@ -0,0 +1,84 @@
+= New Features
+
+* Ruby 2.6+ endless ranges are now supported as condition specifier
+  values, using a >= operator for them:
+
+    DB[:t].where(c: 1...)
+    # SELECT * FROM t WHERE (c >= 1)
+
+* Ruby 2.6+ endless ranges are now supported in the pg_range
+  extension:
+
+    DB[:t].where(id: 1).update(r: 1...)
+    # UPDATE t SET r = '[1,)' WHERE (id = 1)
+
+* The :include option when creating indexes is now supported on
+  PostgreSQL 11, specifying additional columns to include in the index
+  without indexing them.  This is useful to allow index only scans in
+  additional cases.
+
+* The :tablespace option is now supported when creating tables,
+  indexes, and materialized views on PostgreSQL.
+
+* The list plugin now supports a :top option, which can be used to
+  specify the top of the list.  The default value for the top of the
+  list is 1, but using this option you can make the top of the list be
+  0.
+
+= Other Improvements
+
+* In the pg_array_associations plugin, filtering by associations for
+  many_to_pg_array associations now works correctly on PostgreSQL 11.
+  Previously it did not work on PostgreSQL 11 due to new restrictions
+  on using set returning functions in the the SELECT list.
+
+* When setting the value of a column to the same value the column
+  already has, for a new model object that has not yet been persisted,
+  where the column is used as the foreign key for at least one
+  many_to_one association, do not clear any related associations from
+  the associations cache.
+
+* In the pg_array extension, if there are separate conversion procs for
+  timetz and time types, the conversion proc for the timetz[] type now
+  correctly uses the conversion proc for the timetz type to convert
+  scalar values, instead of the conversion proc for the time type.
+
+* Empty arrays and hashes are now correctly handled in
+  Dataset#{first,where_all,where_each,where_single_value} when a
+  cached placeholder literalizer is used.
+
+* In the tree plugin, Model#{ancestors,descendants,self_and_siblings}
+  now work correctly when custom parent/children association names
+  are used.
+
+* The inner loop of the postgres adapter row fetching code is now
+  2-3% faster.
+
+* When using the postgres adapter with pg-0.18+, set a
+  type_map_for_queries for the connection to allow it to handle input
+  type casts for Integer, Float, TrueClass, and FalseClass values
+  without allocating strings.
+
+* SQLTime.parse (and therefore Sequel.string_to_time) now respects the
+  SQLTime.date and Sequel.application_timezone settings.
+
+* The jdbc/postgresql adapter now correctly parses timetz types.
+
+* On JRuby 9.2.0.0, when handling BC timestamps without timezones in
+  the pg_extended_date_support extension, assume local time and not
+  UTC time if the database timezone is not specified and
+  Sequel.datetime_class is Time.
+
+* Errors indicating that a MySQL database is in read-only mode are
+  now treated as disconnect errors in the mysql and mysql2 adapters,
+  for better behavior in failover scenarios.
+
+* Sequel::Model datasets now support the use of IN/NOT IN operators
+  where the second argument for the operator (the right hand side) is
+  a set returning function.  Previously, the Sequel::Model code
+  assumed the right hand side of an IN/NOT IN operator was a datasets
+  or array, since those are the only values where Sequel will
+  automatically create such an operator.
+
+* Sequel no longer loads the strscan library in the pg_array extension
+  if it is not necessary because the parser from sequel_pg is used.

data/doc/release_notes/5.11.0.txt

@@ -0,0 +1,83 @@
+= New Features
+
+* Sequel now supports more window frame specification types when
+  using window functions.  You can now provide the window frame
+  specification as a hash, and Sequel will format the correct
+  SQL.  Specifically, this adds support for RANGE and GROUPS,
+  numeric offsets, and EXCLUDE on a database that supports it
+  (e.g. PostgreSQL 11+).  Examples:
+
+    DB[:albums].select{function(c1).over(:partition=>c2, :order=>:c3,
+      :frame=>{:type=>:range, :start=>1, :end=>1})}
+    # SELECT function(c1) OVER (PARTITION BY c2 ORDER BY c3
+    # RANGE BETWEEN 1 PRECEDING AND 1 FOLLOWING) FROM albums
+
+    DB[:albums].select{function(c1).over(:partition=>c2, :order=>:c3,
+      :frame=>{:type=>:groups, :start=>[2, :preceding], :end=>[1, :preceding]})}
+    # SELECT function(c1) OVER (PARTITION BY c2 ORDER BY c3
+    # GROUPS BETWEEN 2 PRECEDING AND 1 PRECEDING) FROM albums
+
+    DB[:albums].select{function(c1).over(:partition=>c2, :order=>:c3,
+      :frame=>{:type=>:range, :start=>:preceding, :exclude=>:current})}
+    # SELECT function(c1) OVER (PARTITION BY c2 ORDER BY c3
+    # RANGE UNBOUNDED PRECEDING EXCLUDE CURRENT ROW) FROM albums
+
+* The SQLite 3.24+ ON CONFLICT clause to INSERT is now supported.
+  This support is very similar to the PostgreSQL support for the
+  same feature, also known as  UPSERT (UPDATE if the row already
+  exists, INSERT if it does not).  This support is different than
+  the previous support for INSERT ON CONFLICT REPLACE (also known as
+  INSERT OR REPLACE), but it uses the same method name in order to
+  be compatible with the PostgreSQL support.  The new syntax requires
+  passing a hash to Dataset#insert_conflict.  Examples:
+
+    DB[:table].insert_conflict({}).insert(a: 1, b: 2)
+    # INSERT INTO TABLE (a, b) VALUES (1, 2)
+    # ON CONFLICT DO NOTHING
+ 
+    DB[:table].insert_conflict(target: :a).insert(a: 1, b: 2)
+    # INSERT INTO TABLE (a, b) VALUES (1, 2)
+    # ON CONFLICT (a) DO NOTHING
+ 
+    DB[:table].insert_conflict(target: :a,
+      conflict_where: {c: true}).insert(a: 1, b: 2)
+    # INSERT INTO TABLE (a, b) VALUES (1, 2)
+    # ON CONFLICT (a) WHERE (c IS TRUE) DO NOTHING
+ 
+    DB[:table].insert_conflict(target: :a,
+      update: {b: Sequel[:excluded][:b]}).insert(a: 1, b: 2)
+    # INSERT INTO TABLE (a, b) VALUES (1, 2)
+    # ON CONFLICT (a) DO UPDATE SET b = excluded.b
+ 
+    DB[:table].insert_conflict(target: :a,
+      update: {b: Sequel[:excluded][:b]},
+      update_where: {Sequel[:table][:status_id] => 1}).insert(a: 1, b: 2)
+    # INSERT INTO TABLE (a, b) VALUES (1, 2) ON CONFLICT (a)
+    # DO UPDATE SET b = excluded.b WHERE (table.status_id = 1)
+
+* Dataset#window for the WINDOW clause has been moved from the
+  PostgreSQL-specific support to core, and has been enabled on
+  MySQL 8+ and SQLAnywhere.  This allows you to specify a shared
+  window specification in a query, which can be used by multiple
+  window functions.
+
+= Other Improvements
+
+* When using the static_cache plugin, Model.first when called without
+  a block and without arguments or with a single Integer argument now
+  uses the cached values instead of issuing a query.
+
+* Using set_column_default with a nil value now correctly removes an
+  existing default value on MySQL when the column is NOT NULL.
+
+* Window function support has been enabled on SQLAnywhere, since it
+  works correctly.
+
+* Dumping schema for numeric/decimal columns with default values
+  now works correctly.  This was broken starting in Sequel 5.9.0
+  due to changes to use BigDecimal() instead of BigDecimal.new().
+
+* The jdbc/sqlserver adapter now works correctly on JRuby 9.2+.
+
+* An additional check constraint violation failure message is now
+  recognized on SQLite.

data/doc/release_notes/5.12.0.txt

@@ -0,0 +1,141 @@
+= New Features
+
+* An eager_graph_eager plugin has been added, which allows you to
+  chain eager loads using separate queries to an existing dataset that
+  uses eager_graph.  Given the following model associations:
+
+    Band.one_to_many :albums
+    Album.one_to_many :tracks
+
+  Let's say you wanted to return bands ordered by album name, and
+  eagerly load those albums, you can do that using:
+
+    Band.eager_graph(:albums).order{albums[:name]}
+
+  Let's say you also wanted to eagerly load the tracks for each album.
+  You could just add them to the eager_graph call:
+
+    Band.eager_graph(albums: :tracks).order{albums[:name]}
+
+  However, the bloats the result set, and you aren't ordering by the
+  track information, so a join is not required.  The eager_graph_eager
+  plugin allows you to specify that the tracks be eagerly loaded in a
+  separate query after the eager_graph load of albums:
+
+    Band.eager_graph(:albums).
+      eager_graph_eager([:albums], :tracks).
+      order{albums[:name]}
+
+  eager_graph_eager's first argument is a dependency chain, specified
+  as an array of symbols.  This specifies the point at which to
+  perform the eager load. The remaining arguments are arguments that
+  could be passed to Dataset#eager to specify what dependent
+  associations should be loaded at that point.
+
+* A caller_logging Database extension has been added, which logs
+  caller information before queries, filtering out the internal
+  Sequel callers.  Example:
+
+    DB.extension :caller_logging
+    DB[:table].first
+    # Logger:
+    # (0.000041s) (source: /path/to/app/foo/t.rb:12 in `get_first`)
+    # SELECT * FROM table LIMIT 1
+
+  You can further filter the caller lines by setting
+  Database#caller_logging_ignore to a regexp of additional caller
+  lines to ignore.  This is useful if you have specific methods or
+  internal extensions/plugins that you would also like to ignore as
+  they obscure the code actually making the request.
+ 
+    DB.caller_logging_ignore = %r{/path/to/app/lib/plugins}
+ 
+  You can also format the caller before it is placed in the logger,
+  using caller_logging_formatter:
+ 
+    DB.caller_logging_formatter = lambda do |caller|
+      "(#{caller.sub(/\A\/path\/to\/app\//, '')})"
+    end
+    DB[:table].first
+    # Logger:
+    # (0.000041s) (foo/t.rb:12 in `get_first`) SELECT * FROM table LIMIT 1
+ 
+* Database#call_procedure has been added to the postgres adapter, and
+  is usable on PostgreSQL 11+ for calling procedures created with
+  CREATE PROCEDURE.
+
+    DB.call_procedure(:foo, 1, "bar")
+    # CALL foo(1, 'bar')
+
+  This method will return a hash of results if the procedure returns
+  a result, or nil if it does not return a result.
+
+= Other Improvements
+
+* It is now possible to use Dataset#eager_graph in an eager load
+  callback for associations that use join tables.  This allows you
+  to eager load some associations using separate queries and other
+  associations using joins.  For example:
+
+    Band.eager(:albums=>proc{|ds| ds.eager_graph(:tracks)})
+
+  Will load the bands in one query, and load the albums and tracks
+  in a separate query using a join.  Previously, this construction
+  worked only for associations that did not use join tables.  It now
+  works for associations that use join tables, as long as existing
+  selected columns are not removed inside the callback.
+
+* The tactical_eager_loading plugin now handles automatic eager
+  loading for associated objects that were created during the
+  load of dataset that uses eager_graph.  When using the plugin,
+  the following code will now only execute 2 queries, instead of
+  issuing a separate query for each album to get the tracks for
+  the album.
+
+    artists = Artist.eager_graph(:albums).all
+    artists.each do |artist|
+      artist.albums.each do |album|
+        album.tracks
+      end
+    end
+
+* Calling Dataset#graph with a dataset with existing selections where
+  the column aliases cannot be determined automatically now works
+  correctly by using a subselect.  Previously, attempting to do this
+  would raise an exception.  This allows the following code to work:
+
+    DB[:table].select_all(:table).select_append(expr).graph(...)
+
+* Datasets now cache the EagerGraphLoader object that is generated to
+  convert arrays of hashes into an object graph, so that subsequent
+  eager loads on the same dataset do not need to recompute the same
+  information.  Most EagerGraphLoader internal state is now frozen to
+  prevent unintentional modification.
+
+* Sequel.extension now loads files from gems.  Previously, it used
+  Kernel.require, which does not load files from gems.
+
+* Adapters that emulate prepared statements using literalization now
+  use a placeholder literalizer and should execute significantly
+  faster.  More prepared statement internal metadata is now frozen
+  to prevent unintentional modification.
+
+* Dataset#intersect, #except, and #nowait are now supported on MariaDB
+  10.3+.
+
+* The constraint_validations extension now respects the
+  constraint_validations_table setting when adding metadata for the
+  constraint validations.
+
+* In the oracle adapter, the clob prepared statement argument type is
+  now mapped to the OCI8::CLOB class, allowing the use of Oracle
+  procedures with clob output parameters.
+
+* The Model.load_cache method in the static_cache plugin is now public.
+
+= Backwards Compatibility
+
+* The private Dataset#prepared_arg? method has been removed.  It is no
+  longer necessary after the refactoring to the prepared statement
+  code.  External adapters that currently call the method should be
+  updated to no longer call the method.