sequel 5.20.0 → 5.49.0

data/doc/postgresql.rdoc

@@ -139,10 +139,81 @@ 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
-allows you do create an unlogged table by specifying the <tt>unlogged: true</tt> option to +create_table+:
+allows you to create an unlogged table by specifying the <tt>unlogged: true</tt> option to +create_table+:
 
   DB.create_table(:table, unlogged: true){Integer :i}
   # CREATE UNLOGGED TABLE "table" ("i" integer)
@@ -341,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
@@ -357,6 +428,14 @@ rows that are distinct on just those columns:
   DB[:table].distinct(:id).all
   # SELECT DISTINCT ON ("id") * FROM "table"
 
+=== JOIN USING table alias
+
+Sequel allows passing an SQL::AliasedExpression to join table methods to use a USING
+join with a table alias for the USING columns:
+
+  DB[:t1].join(:t2, Sequel.as([:c1, :c2], :alias))
+  # SELECT * FROM "t1" INNER JOIN "t2" USING ("c1", "c2") AS "alias"
+
 === Calling PostgreSQL 11+ Procedures <tt>postgres only</tt>
 
 PostgreSQL 11+ added support for procedures, which are different from the user defined

data/doc/querying.rdoc

@@ -498,7 +498,7 @@ filters:
   # SELECT * FROM artists WHERE (id != 5)
   
   Artist.where(id: 5).exclude{name > 'A'}
-  # SELECT * FROM artists WHERE ((id = 5) OR (name <= 'A')
+  # SELECT * FROM artists WHERE ((id = 5) AND (name <= 'A')
 
 So to do a NOT IN with an array:
 
@@ -746,7 +746,7 @@ shortcuts for all common (and most uncommon) join types. For example
 
   Album.join(:artists, id: :artist_id)
   # SELECT * FROM albums
-  # INNER JOIN artists ON (artists.id = albums.artist_id))))
+  # INNER JOIN artists ON (artists.id = albums.artist_id)
 
 And +left_join+ does a LEFT JOIN:
 
@@ -870,14 +870,14 @@ In this case, you don't even need to specify any conditions.
 ==== Join Blocks
 
 You can provide a block to any of the join methods that accept
-conditions.  This block should accept 3 arguments, the table alias
+conditions.  This block should accept 3 arguments: the table alias
 for the table currently being joined, the table alias for the last
 table joined (or first table), and an array of previous
 <tt>Sequel::SQL::JoinClause</tt>s.
 
 This allows you to qualify columns similar to how the implicit
 qualification works, without worrying about the specific aliases
-being used.  For example, lets say you wanted to join the albums
+being used.  For example, let's say you wanted to join the albums
 and artists tables, but only want albums where the artist's name
 comes before the album's name.
 

data/doc/release_notes/5.21.0.txt

@@ -0,0 +1,87 @@
+= New Features
+
+* The pg_json extension now adds a Database#wrap_json_primitives
+  accessor.  When set to true, JSON primitive values (string, number,
+  true, false, and null) will be wrapped by delegate Ruby objects
+  instead of using Ruby primitives.  This allows the values to round
+  trip, so the following code will work even for primitive values in
+  json_column:
+
+    DB.extension :pg_json
+    DB.wrap_json_primitives = true
+    value = DB[:table].get(:json_column)
+    DB[:other_table].insert(json_column: value)
+
+  This should be enabled with care, especially in cases where false
+  and null JSON values are used, as the behavior will change if
+  the objects are used in a boolean context in Ruby, as only false
+  and nil in Ruby are treated as false:
+
+    # assume JSON false or null value
+    value = DB[:table].get(:json_column)
+
+    if value
+      # executed if wrap_json_primitives is true
+    else
+      # executed by default
+    end
+
+  When typecasting input in model objects to a JSON type, string
+  input will still be parsed as JSON.  However, you can set the
+  Database#typecast_json_strings accessor to true, and then string
+  input will be considered as a JSON string instead of parsing the
+  string as JSON.
+
+  To prevent backwards compatibility issues, Sequel.pg_json/pg_jsonb
+  behavior has not changed.  To support wrapping Ruby primitives in
+  the delegate objects, new Sequel.pg_json_wrap/pg_jsonb_wrap methods
+  have been added.  These methods only handle the Ruby primitives,
+  they cannot be used if the existing object is already a delegate
+  object.
+
+  As model objects always consider a nil value as SQL NULL and do
+  not typecast it, if you want to explicitly set a JSON null value,
+  you need to wrap it explicitly:
+
+    model_object.json_column = Sequel.pg_json_wrap(nil)
+
+= Other Improvements
+
+* Sequel now supports window function options :window, :exclude, and
+  :frame :type=>:groups, :start, and :end on SQLite 3.28.0+.
+
+* The server_block extension now respects the :servers_hash Database
+  option.  This makes it more similar to Sequel's default behavior.
+  However, that means by default, the server_block extension will
+  default to handling unknown shards as the default shard, instead
+  of raising an error for them.
+
+* The rcte_tree plugin now disallows eager graphing of the ancestors
+  and descendants associations.  Previously, eager graphing of these
+  associations generated incorrect results.  It is not possible to
+  eager graph these extensions, but normal eager loading does work.
+
+* The ado adapter's performance has been improved by using faster
+  callables for type conversion and a more efficient inner loop.
+
+* The sqlite adapter now converts a :timeout option given as a string
+  to an integer.  This allows you to use the option inside of a
+  connection string.
+
+* The mysql and mysql2 adapters now recognize an additional
+  DatabaseLockTimeout error.
+
+* The jdbc/mysql adapter now works correctly when using JRuby with
+  Java 11.
+
+* The ado adapter now handles numeric values when using locales that
+  use comma instead of period as the decimal separator.
+
+= Backwards Compatibility
+
+* In the pg_json extension, the following singleton methods of
+  Sequel::Postgres::JSONDatabaseMethods are now deprecated:
+
+  * parse_json
+  * db_parse_json
+  * db_parse_jsonb 

data/doc/release_notes/5.22.0.txt

@@ -0,0 +1,48 @@
+= New Features
+
+* Sequel now supports Ruby 2.7+ startless ranges in filters:
+
+    DB[:table].where(:column=>(..10))
+    # SELECT * FROM table WHERE (column <= 10)
+
+    DB[:table].where(:column=>(...10))
+    # SELECT * FROM table WHERE (column < 10)
+
+  It also supports startless, endless ranges in filters, using a
+  condition that is always true:
+
+    DB[:table].where(:column=>(nil..nil))
+    # SELECT * FROM table WHERE (1 = 1)
+
+* Sequel now supports startless ranges in the pg_range extension:
+
+    DB.extension :pg_range
+
+    DB[:table].insert(:column=>(..10))
+    # INSERT INTO "table" ("column") VALUES ('[,10]') RETURNING "id"
+
+    DB[:table].insert(:column=>(...10))
+    # INSERT INTO "table" ("column") VALUES ('[,10)') RETURNING "id"
+
+    DB[:table].insert(:column=>(nil..nil))
+    # INSERT INTO "table" ("column") VALUES ('[,]') RETURNING "id"
+
+* Sequel now supports a :materialized option in Dataset#with on
+  PostgreSQL 12+, to control the inlining of common table expressions:
+
+    DB[:t].with(:t, DB[:t2], :materialized=>false)
+    # WITH "t" AS NOT MATERIALIZED (SELECT * FROM "t2")
+    # SELECT * FROM "t"
+
+    DB[:t].with(:t, DB[:t2], :materialized=>true)
+    # WITH "t" AS MATERIALIZED (SELECT * FROM "t2")
+    # SELECT * FROM "t"
+
+= Other Improvements
+
+* Database#primary_key_sequence now works for tables without serial
+  sequences on PostgreSQL 12+.
+
+* Dataset#multi_insert and #import with return: :primary_key option
+  on Microsoft SQL Server now work correctly if the dataset uses
+  a row_proc (e.g. for model datasets).

data/doc/release_notes/5.23.0.txt

@@ -0,0 +1,56 @@
+= New Features
+
+* An insert_conflict plugin has been added for automatically handling
+  constraint conflicts when saving new model instances.  It is
+  supported on PostgreSQL 9.5+ and SQLite 3.24.0+.
+
+    Album.new(name: 'Foo', copies_sold: 1000).
+      insert_conflict(
+        target: :name,
+        update: {copies_sold: Sequel[:excluded][:b]}
+      ).
+      save
+
+* On Microsoft SQL Server, the Database :ansi option has been added,
+  which sets the following ANSI related options:
+
+  * ANSI_NULLS
+  * ANSI_PADDING
+  * ANSI_WARNINGS
+  * ANSI_NULL_DFLT_ON
+  * QUOTED_IDENTIFIER
+  * CONCAT_NULL_YIELDS_NULL
+
+= Other Improvements
+
+* Sequel.datetime_class = Time is now supported when using the
+  named_timezones extension.  For backwards compatibility, the
+  named_timezones extension still sets
+  Sequel.datetime_class = DateTime.  When using Ruby 2.6+, the
+  Time instances have the timezone set on them using Ruby 2.6+'s
+  timezone support, but basic support works correctly in earlier
+  versions of Ruby.
+
+* On Microsoft SQL Server, Sequel now handles parsing schema for
+  tables in another database on the same server or in a database
+  on a linked server.
+
+* The pg_json extension now correctly handles subclasses of core
+  classes when wrapping objects.  This stopped working in Sequel
+  5.21.0, when support for wrapping JSON primitives was added.
+
+* Sequel now works around a couple bugs in jdbc-sqlite 3.27.2.1,
+  allowing schema parsing and foreign key parsing to work.
+
+* Dataset#execute* private methods now respect an explicitly given
+  :server option, fixing Dataset#paged_each in the postgres adapter
+  when using sharding.
+
+* Timezone offsets are now handled correctly when typecasting an array
+  or hash to datetime when Sequel.datetime_class = Time.
+
+* Sequel now avoids errors when parsing schema when using the mock
+  SQLite adapter.
+
+* A minor thread-safety issue has been fixed in the named_timezones
+  extension.

data/doc/release_notes/5.24.0.txt

@@ -0,0 +1,56 @@
+= New Features
+
+* A :cache_file plugin option has been added to the
+  pg_auto_constraint_validations plugin.  This option specifies
+  a file to use to cache the metadata the plugin uses, so the
+  plugin does not need to run 5 queries per model at startup to
+  load the metadata.  This can dramatically improve startup time
+  when using the plugin with a large number of models.
+
+  To create the metadata file, load the plugin into Sequel::Model
+  (or whatever class you are using as the base class for your
+  model classes) with the :cache_file option, and after loading
+  all of the subclasses of that class, run:
+
+    Sequel::Model.dump_pg_auto_constraint_validations_cache
+
+  As when using the schema_caching and index_caching extensions,
+  it is up to the user to ensure that the cached metadata matches
+  the current database schema.  Sequel does no checking of this,
+  as checking would take more time, and the point of this plugin
+  is to improve startup performance.
+
+* A static_cache_cache plugin has been added.  This plugin allows
+  for caching rows for models using the static_cache plugin. This
+  prevents the need to issue a query at model creation time to
+  get the rows.  This plugin should be loaded into Sequel::Model
+  (or whatever class you are using as the base class for your
+  model classes) before loading the models using the static_cache
+  plugin.  To create the metadata file, after all subclasses of
+  that class have been loaded, run:
+
+    Sequel::Model.dump_static_cache_cache
+
+* :unique_deferrable and :primary_key_deferrable column
+  options are now supported on PostgreSQL 9+ and Oracle. This
+  allows you to created deferrable unique and primary key
+  column constraints.  You could already create deferrable
+  table constraints using the :deferrable option to the primary_key
+  and unique methods.
+
+* A :generated_always_as column option is now supported on
+  PostgreSQL 12+, for creating generated columns.
+
+* A Database#skip_logging? private method has been added.  This
+  is designed for use in extensions, to force log timing even
+  when no loggers are configured.
+
+= Other Improvements
+
+* Sequel no longer sets the :host option to localhost by default
+  in the mysql2 adapter.  This prevents Sequel from overriding
+  a host specified in the defaults_file.
+
+* All database array types are converted to Ruby arrays in the
+  jdbc adapter.  Previously, this was only done in the
+  jdbc/postgresql subadapter.

data/doc/release_notes/5.25.0.txt

@@ -0,0 +1,32 @@
+= New Features
+
+* An association_multi_add_remove plugin has been added.  This plugin
+  adds a shortcut for adding or removing multiple associated objects
+  in a single method call:
+
+    Artist.plugin :association_multi_add_remove
+    Artist.many_to_one :albums
+    Artist[1].add_albums([Album[2], Album[3]])
+    Artist[1].remove_albums([Album[4], Album[5]])
+
+  It also offers a setter method, which will add and remove associated
+  objects as necessary:
+
+    Artist[1].albums = [Album[3], Album[4]]
+
+= Other Improvements
+
+* The sharding plugin now integrates with the server_block extension.
+  This makes it so if you retrieve a model instance inside a
+  with_server block, saving the model instance will save it back to
+  the shard from which it was retrieved.
+
+* Setting a default for a column on Microsoft SQL Server now works
+  correctly if the column already has a default.
+
+* Sequel::SQL::NumericMethods#coerce no longer raises NoMethodError
+  if the super method is not defined.  This fixes some cases when
+  comparing Date/DateTime instances to Sequel objects.
+
+* The csv_serializer plugin now avoids keyword argument separation
+  issues on Ruby 2.7+.

data/doc/release_notes/5.26.0.txt

@@ -0,0 +1,35 @@
+= New Features
+
+* Support for SQL/JSON path expressions has been added to the
+  pg_json_ops extension. These are supported in PostgreSQL 12+.
+  Examples:
+
+    j = Sequel.pg_json_op(:json_column)
+    j.path_exists('$.foo')      # (jsonb_column @? '$.foo')
+    j.path_match('$.foo')       # (jsonb_column @@ '$.foo')
+    j.path_exists!('$.foo')     # jsonb_path_exists(jsonb_column, '$.foo')
+    j.path_match!('$.foo')      # jsonb_path_match(jsonb_column, '$.foo')
+    j.path_query('$.foo')       # jsonb_path_query(jsonb_column, '$.foo')
+    j.path_query_array('$.foo') # jsonb_path_query_array(jsonb_column, '$.foo')
+    j.path_query_first('$.foo') # jsonb_path_query_first(jsonb_column, '$.foo')
+
+* The nested_attributes method in the nested_attributes plugin now
+  supports a :require_modification option, which can override the
+  default require_modification setting for the nested objects. This
+  can be useful to avoid errors if multiple requests are submitted
+  simultaneously to delete the same nested row.
+
+= Other Improvements
+
+* The dirty plugin now works correctly with the typecast_on_load
+  plugin.
+
+* Sequel::Postgres::PGRange#hash has been added to the pg_range
+  extension, allowing PGRange instances to be usable as hash keys.
+
+* Table aliases are now supported for single table INSERT
+  statements on PostgreSQL 9.5+, which can make some insert_conflict
+  usage easier.
+
+* Two more foreign key constraint violation types are now recognized
+  on MySQL 8.0.13+.

data/doc/release_notes/5.27.0.txt

@@ -0,0 +1,21 @@
+= New Features
+
+* Sequel::DEFAULT has been added a constant for the DEFAULT expression,
+  useful in inserts and especially updates:
+
+    DB[:a].where(:id=>1).update(:b=>Sequel::DEFAULT)
+    # UPDATE "a" SET "b" = DEFAULT WHERE "id" = 1
+
+* SQL::Function#filter for filtered aggregate functions is now
+  supported on all databases.  On databases not supporting it natively
+  (all except PostgreSQL 9.4+ and SQLite 3.30+), a CASE statement is
+  used to emulate the support.
+
+= Other Improvements
+
+* NULLS FIRST/LAST is now used without emulation on SQLite 3.30+.
+
+* The pg_enum extension now works correctly on PostgreSQL 8.3-9.0.
+
+* Postgres::ArrayOp#join in the pg_array_ops extension now works
+  correctly on PostgreSQL <9.1.

data/doc/release_notes/5.28.0.txt

@@ -0,0 +1,16 @@
+= New Features
+
+* An any_not_empty extension has been added, for making Dataset#any?
+  without a block be the same as !empty?.  This can result in a
+  much faster database query.
+
+* An exclude_or_null extension has been added, adding a
+  Dataset#exclude_or_null method that returns rows where the given
+  expression is false or NULL.  This extension is supported on
+  PostgreSQL, SQLite, MySQL, H2, and HSQLDB.
+
+= Other Improvements
+
+* When using the jdbc/postgresql adapter, calling with_fetch_size
+  on a dataset will emit a warning.  This is because the driver
+  will ignore the setting.

data/doc/release_notes/5.29.0.txt

@@ -0,0 +1,22 @@
+= New Features
+
+* An empty_failure_backtraces plugin has been added for using empty
+  backtraces for ValidationFailed and HookFailed exceptions. In many
+  cases, these exceptions are automatically handled (e.g. web form
+  submission handling to display appropriate error pages), and using
+  empty backtraces is 10-15x faster on JRuby 9.2.7.0+.
+
+* Dataset#json_serializer_opts has been added to the json_serializer
+  plugin.  This allows setting default options on a per-Dataset basis
+  for all Dataset#to_json calls.
+
+= Other Improvements
+
+* Another disconnect error is now recognized in the tinytds adapter.
+
+* Using Sequel with the the CRuby master branch (what will be Ruby 3)
+  now works by supporting a second argument for
+  Dataset#initialize_clone.
+
+* Sequel now avoids a warning in verbose mode when using the postgres
+  adapter, a recent version of ruby-pg, and bound variables.

data/doc/release_notes/5.30.0.txt

@@ -0,0 +1,20 @@
+= New Features
+
+* Sequel now supports generated columns on SQLite 3.31+ using the
+  :generated_always_as and :generated_type options. Example:
+
+    DB.create_table(:table) do
+      primary_key :id
+      Numeric :amount, null: false
+      Numeric :tax, null: false
+      Numeric :total, generated_always_as: (Sequel[:amount] + :tax)
+    end
+
+= Other Improvements
+
+* The Database#transaction :before_retry option is now called before
+  retrying the transaction even when the :num_retries option is set
+  to nil.
+
+* The gem no longer ships with specs and older release notes, reducing
+  the gem size by over 40%.