sequel 5.33.0 → 5.58.0

data/lib/sequel/database/schema_generator.rb

@@ -38,7 +38,6 @@ module Sequel
         @constraints = []
         @primary_key = nil
         instance_exec(&block) if block
-        @columns.unshift(@primary_key) if @primary_key && !has_column?(primary_key_name)
       end
 
       # Use custom Bignum method to use :Bignum instead of Bignum class, to work
@@ -144,8 +143,17 @@ module Sequel
       # :identity :: Create an identity column.
       #
       # MySQL specific options:
+      #
       # :generated_type :: Set the type of column when using :generated_always_as,
       #                    should be :virtual or :stored to force a type.
+      # :on_update_current_timestamp :: Use ON UPDATE CURRENT TIMESTAMP when defining the column,
+      #                                 which will update the column value to CURRENT_TIMESTAMP
+      #                                 on every UPDATE.
+      #
+      # Microsoft SQL Server specific options:
+      #
+      # :clustered :: When using :primary_key or :unique, marks the primary key or unique
+      #               constraint as CLUSTERED (if true), or NONCLUSTERED (if false).
       def column(name, type, opts = OPTS)
         columns << {:name => name, :type => type}.merge!(opts)
         if index_opts = opts[:index]
@@ -154,7 +162,7 @@ module Sequel
         nil
       end
       
-      # Adds a named constraint (or unnamed if name is nil),
+      # Adds a named CHECK constraint (or unnamed if name is nil),
       # with the given block or args. To provide options for the constraint, pass
       # a hash as the first argument.
       #
@@ -162,6 +170,15 @@ module Sequel
       #   # CONSTRAINT blah CHECK num >= 1 AND num <= 5
       #   constraint({name: :blah, deferrable: true}, num: 1..5)
       #   # CONSTRAINT blah CHECK num >= 1 AND num <= 5 DEFERRABLE INITIALLY DEFERRED
+      #
+      # If the first argument is a hash, the following options are supported:
+      #
+      # Options:
+      # :name :: The name of the CHECK constraint
+      # :deferrable :: Whether the CHECK constraint should be marked DEFERRABLE.
+      #
+      # PostgreSQL specific options:
+      # :not_valid :: Whether the CHECK constraint should be marked NOT VALID.
       def constraint(name, *args, &block)
         opts = name.is_a?(Hash) ? name : {:name=>name}
         constraints << opts.merge(:type=>:check, :check=>block || args)
@@ -200,14 +217,12 @@ module Sequel
       end
 
       # Add a full text index on the given columns.
+      # See #index for additional options.
       #
       # PostgreSQL specific options:
       # :index_type :: Can be set to :gist to use a GIST index instead of the
       #                default GIN index.
       # :language :: Set a language to use for the index (default: simple).
-      #
-      # Microsoft SQL Server specific options:
-      # :key_index :: The KEY INDEX to use for the full text index.
       def full_text_index(columns, opts = OPTS)
         index(columns, opts.merge(:type => :full_text))
       end
@@ -217,35 +232,43 @@ module Sequel
         columns.any?{|c| c[:name] == name}
       end
       
-      # Add an index on the given column(s) with the given options.
+      # Add an index on the given column(s) with the given options. Examples:
+      #
+      #   index :name
+      #   # CREATE INDEX table_name_index ON table (name)
+      #
+      #   index [:artist_id, :name]
+      #   # CREATE INDEX table_artist_id_name_index ON table (artist_id, name)
+      #
+      #   index [:artist_id, :name], name: :foo
+      #   # CREATE INDEX foo ON table (artist_id, name)
+      #
       # General options:
       #
+      # :include :: Include additional column values in the index, without
+      #             actually indexing on those values (only supported by
+      #             some databases).
       # :name :: The name to use for the index. If not given, a default name
       #          based on the table and columns is used.
-      # :type :: The type of index to use (only supported by some databases)
+      # :type :: The type of index to use (only supported by some databases,
+      #          :full_text and :spatial values are handled specially).
       # :unique :: Make the index unique, so duplicate values are not allowed.
-      # :where :: Create a partial index (only supported by some databases)
+      # :where :: A filter expression, used to create a partial index (only
+      #           supported by some databases).
       #
       # PostgreSQL specific options:
       #
       # :concurrently :: Create the index concurrently, so it doesn't block
       #                  operations on the table while the index is being
       #                  built.
-      # :opclass :: Use a specific operator class in the index.
-      # :include :: Include additional column values in the index, without
-      #             actually indexing on those values (PostgreSQL 11+).
+      # :if_not_exists :: Only create the index if an index of the same name doesn't already exist.
+      # :opclass :: Set an opclass to use for all columns (per-column opclasses require
+      #             custom SQL).
       # :tablespace :: Specify tablespace for index.
       #
       # Microsoft SQL Server specific options:
       #
-      # :include :: Include additional column values in the index, without
-      #             actually indexing on those values.
-      #
-      #   index :name
-      #   # CREATE INDEX table_name_index ON table (name)
-      #
-      #   index [:artist_id, :name]
-      #   # CREATE INDEX table_artist_id_name_index ON table (artist_id, name)
+      # :key_index :: Sets the KEY INDEX to the given value.
       def index(columns, opts = OPTS)
         indexes << {:columns => Array(columns)}.merge!(opts)
         nil
@@ -311,6 +334,7 @@ module Sequel
       end
       
       # Add a spatial index on the given columns.
+      # See #index for additional options.
       def spatial_index(columns, opts = OPTS)
         index(columns, opts.merge(:type => :spatial))
       end
@@ -366,8 +390,7 @@ module Sequel
       end
       
       # Add a column with the given name, type, and opts.
-      # See CreateTableGenerator#column for the available options (except for +:index+, use a
-      # separate +add_index+ call to add an index for the column).
+      # See CreateTableGenerator#column for the available options.
       #
       #   add_column(:name, String) # ADD COLUMN name varchar(255)
       #
@@ -380,7 +403,10 @@ module Sequel
       # :after :: The name of an existing column that the new column should be positioned after
       # :first :: Create this new column before all other existing columns
       def add_column(name, type, opts = OPTS)
-        @operations << {:op => :add_column, :name => name, :type => type}.merge!(opts)
+        op = {:op => :add_column, :name => name, :type => type}.merge!(opts)
+        index_opts = op.delete(:index)
+        @operations << op
+        add_index(name, index_opts.is_a?(Hash) ? index_opts : OPTS) if index_opts
         nil
       end
       
@@ -409,8 +435,7 @@ module Sequel
       end
 
       # Add a foreign key with the given name and referencing the given table.
-      # See CreateTableGenerator#column for the available options (except for +:index+, use a
-      # separate +add_index+ call to add an index for the column).
+      # See CreateTableGenerator#column for the available options.
       #
       # You can also pass an array of column names for creating composite foreign
       # keys. In this case, it will assume the columns exist and will only add
@@ -437,7 +462,7 @@ module Sequel
       end
       
       # Add a full text index on the given columns.
-      # See CreateTableGenerator#index for available options.
+      # See CreateTableGenerator#full_text_index for available options.
       def add_full_text_index(columns, opts = OPTS)
         add_index(columns, {:type=>:full_text}.merge!(opts))
       end
@@ -446,34 +471,6 @@ module Sequel
       # CreateTableGenerator#index for available options.
       #
       #   add_index(:artist_id) # CREATE INDEX table_artist_id_index ON table (artist_id)
-      #
-      # Options:
-      #
-      # :name :: Give a specific name for the index. Highly recommended if you plan on
-      #          dropping the index later.
-      # :where :: A filter expression, used to setup a partial index (if supported).
-      # :unique :: Create a unique index.
-      #
-      # PostgreSQL specific options:
-      #
-      # :concurrently :: Create the index concurrently, so it doesn't require an exclusive lock
-      #                  on the table.
-      # :index_type :: The underlying index type to use for a full_text index, gin by default).
-      # :language :: The language to use for a full text index (simple by default).
-      # :opclass :: Set an opclass to use for all columns (per-column opclasses require
-      #             custom SQL).
-      # :type :: Set the index type (e.g. full_text, spatial, hash, gin, gist, btree).
-      # :if_not_exists :: Only create the index if an index of the same name doesn't already exists
-      #
-      # MySQL specific options:
-      #
-      # :type :: Set the index type, with full_text and spatial indexes handled specially.
-      #
-      # Microsoft SQL Server specific options:
-      #
-      # :include :: Includes additional columns in the index.
-      # :key_index :: Sets the KEY INDEX to the given value.
-      # :type :: clustered uses a clustered index, full_text uses a full text index.
       def add_index(columns, opts = OPTS)
         @operations << {:op => :add_index, :columns => Array(columns)}.merge!(opts)
         nil

data/lib/sequel/database/schema_methods.rb

@@ -63,7 +63,7 @@ module Sequel
     # definitions using <tt>create_table</tt>, and +add_index+ accepts all the options
     # available for index definition.
     #
-    # See <tt>Schema::AlterTableGenerator</tt> and the {"Migrations and Schema Modification" guide}[rdoc-ref:doc/migration.rdoc].
+    # See <tt>Schema::AlterTableGenerator</tt> and the {Migrations guide}[rdoc-ref:doc/migration.rdoc].
     def alter_table(name, &block)
       generator = alter_table_generator(&block)
       remove_cached_schema(name)
@@ -183,6 +183,15 @@ module Sequel
     #             keys.
     # :tablespace :: The tablespace to use for the table.
     #
+    # SQLite specific options:
+    # :strict :: Create a STRICT table, which checks that the values for the columns
+    #            are the correct type (similar to all other SQL databases). Note that
+    #            when using this option, all column types used should be one of the
+    #            following: +int+, +integer+, +real+, +text+, +blob+, and +any+.
+    #            The +any+ type is treated like a SQLite column in a non-strict table,
+    #            allowing any type of data to be stored. This option is supported on
+    #            SQLite 3.37.0+.
+    #
     # See <tt>Schema::CreateTableGenerator</tt> and the {"Schema Modification" guide}[rdoc-ref:doc/schema_modification.rdoc].
     def create_table(name, options=OPTS, &block)
       remove_cached_schema(name)
@@ -240,7 +249,7 @@ module Sequel
       if supports_create_or_replace_view?
         options = options.merge(:replace=>true)
       else
-        drop_view(name) rescue nil
+        swallow_database_error{drop_view(name)}
       end
 
       create_view(name, source, options)
@@ -262,6 +271,10 @@ module Sequel
     #   # SELECT * FROM items WHERE foo
     #   # WITH CHECK OPTION
     #
+    #   DB.create_view(:bar_items, DB[:items].select(:foo), columns: [:bar])
+    #   # CREATE VIEW bar_items (bar) AS
+    #   # SELECT foo FROM items
+    #
     # Options:
     # :columns :: The column names to use for the view.  If not given,
     #             automatically determined based on the input dataset.
@@ -494,7 +507,9 @@ module Sequel
       when :drop_index
         drop_index_sql(table, op)
       else
-        "ALTER TABLE #{quote_schema_table(table)} #{alter_table_op_sql(table, op)}"
+        if sql = alter_table_op_sql(table, op)
+          "ALTER TABLE #{quote_schema_table(table)} #{sql}"
+        end
       end
     end
 
@@ -578,14 +593,14 @@ module Sequel
         sql << ' NULL'
       end
     end
-    
+
     # Add primary key SQL fragment to column creation SQL.
     def column_definition_primary_key_sql(sql, column)
       if column[:primary_key]
         if name = column[:primary_key_constraint_name]
           sql << " CONSTRAINT #{quote_identifier(name)}"
         end
-        sql << ' PRIMARY KEY'
+        sql << " " << primary_key_constraint_sql_fragment(column)
         constraint_deferrable_sql_append(sql, column[:primary_key_deferrable])
       end
     end
@@ -606,7 +621,7 @@ module Sequel
         if name = column[:unique_constraint_name]
           sql << " CONSTRAINT #{quote_identifier(name)}"
         end
-        sql << ' UNIQUE'
+        sql << ' ' << unique_constraint_sql_fragment(column)
         constraint_deferrable_sql_append(sql, column[:unique_deferrable])
       end
     end
@@ -654,11 +669,11 @@ module Sequel
         check = "(#{check})" unless check[0..0] == '(' && check[-1..-1] == ')'
         sql << "CHECK #{check}"
       when :primary_key
-        sql << "PRIMARY KEY #{literal(constraint[:columns])}"
+        sql << "#{primary_key_constraint_sql_fragment(constraint)} #{literal(constraint[:columns])}"
       when :foreign_key
         sql << column_references_table_constraint_sql(constraint.merge(:deferrable=>nil))
       when :unique
-        sql << "UNIQUE #{literal(constraint[:columns])}"
+        sql << "#{unique_constraint_sql_fragment(constraint)} #{literal(constraint[:columns])}"
       else
         raise Error, "Invalid constraint type #{constraint[:type]}, should be :check, :primary_key, :foreign_key, or :unique"
       end
@@ -811,23 +826,20 @@ module Sequel
     # Proxy the filter_expr call to the dataset, used for creating constraints.
     # Support passing Proc arguments as blocks, as well as treating plain strings
     # as literal strings, so that previous migrations that used this API do not break.
-    def filter_expr(*args, &block)
-      if args.length == 1
-        arg = args.first
-        if arg.is_a?(Proc) && !block
-          block = args.first
-          args = nil
-        elsif arg.is_a?(String)
-          args = [Sequel.lit(*args)]
-        elsif arg.is_a?(Array)
-          if arg.first.is_a?(String)
-            args = [Sequel.lit(*arg)]
-          elsif arg.length > 1
-            args = [Sequel.&(*arg)]
-          end
+    def filter_expr(arg=nil, &block)
+      if arg.is_a?(Proc) && !block
+        block = arg
+        arg = nil
+      elsif arg.is_a?(String)
+        arg = Sequel.lit(arg)
+      elsif arg.is_a?(Array)
+        if arg.first.is_a?(String)
+          arg = Sequel.lit(*arg)
+        elsif arg.length > 1
+          arg = Sequel.&(*arg)
         end
       end
-      schema_utility_dataset.literal(schema_utility_dataset.send(:filter_expr, *args, &block))
+      schema_utility_dataset.literal(schema_utility_dataset.send(:filter_expr, arg, &block))
     end
 
     # SQL statement for creating an index for the table with the given name
@@ -893,6 +905,11 @@ module Sequel
       on_delete_clause(action)
     end
     
+    # Add fragment for primary key specification, separated for easier overridding.
+    def primary_key_constraint_sql_fragment(_)
+      'PRIMARY KEY'
+    end
+    
     # Proxy the quote_schema_table method to the dataset
     def quote_schema_table(table)
       schema_utility_dataset.quote_schema_table(table)
@@ -1048,6 +1065,11 @@ module Sequel
       "#{type}#{literal(Array(elements)) if elements}#{' UNSIGNED' if column[:unsigned]}"
     end
 
+    # Add fragment for unique specification, separated for easier overridding.
+    def unique_constraint_sql_fragment(_)
+      'UNIQUE'
+    end
+    
     # Whether clob should be used for String text: true columns.
     def uses_clob_for_text?
       false

data/lib/sequel/database/transactions.rb

@@ -82,7 +82,7 @@ module Sequel
     # :server :: The server/shard the transaction is being executed on.
     def rollback_on_exit(opts=OPTS)
       synchronize(opts[:server]) do |conn|
-        raise Error, "Cannot call Sequel:: Database#rollback_on_exit! unless inside a transaction" unless h = _trans(conn)
+        raise Error, "Cannot call Sequel:: Database#rollback_on_exit unless inside a transaction" unless h = _trans(conn)
         rollback = !opts[:cancel]
 
         if supports_savepoints?
@@ -154,7 +154,7 @@ module Sequel
     #              Note that this should not be used unless the entire transaction
     #              block is idempotent, as otherwise it can cause non-idempotent
     #              behavior to execute multiple times.
-    # :rollback :: Can the set to :reraise to reraise any Sequel::Rollback exceptions
+    # :rollback :: Can be set to :reraise to reraise any Sequel::Rollback exceptions
     #              raised, or :always to always rollback even if no exceptions occur
     #              (useful for testing).
     # :server :: The server to use for the transaction. Set to :default, :read_only, or
@@ -205,6 +205,10 @@ module Sequel
             end
           end
 
+          if opts[:savepoint] && !supports_savepoints?
+            raise Sequel::InvalidOperation, "savepoints not supported on #{database_type}"
+          end
+
           if already_in_transaction?(conn, opts)
             if opts[:rollback] == :always && !opts.has_key?(:savepoint)
               if supports_savepoints? 
@@ -418,11 +422,10 @@ module Sequel
     end
 
     # Retrieve the savepoint hooks that should be run for the given
-    # connection and commit status.
+    # connection and commit status.  This expacts that you are
+    # already inside a savepoint when calling.
     def savepoint_hooks(conn, committed)
-      if in_savepoint?(conn)
-        _trans(conn)[:savepoints].last[committed ? :after_commit : :after_rollback]
-      end
+      _trans(conn)[:savepoints].last[committed ? :after_commit : :after_rollback]
     end
 
     # Retrieve the transaction hooks that should be run for the given

data/lib/sequel/dataset/actions.rb

@@ -19,7 +19,7 @@ module Sequel
     METHS
 
     # The clone options to use when retrieving columns for a dataset.
-    COLUMNS_CLONE_OPTIONS = {:distinct => nil, :limit => 1, :offset=>nil, :where=>nil, :having=>nil, :order=>nil, :row_proc=>nil, :graph=>nil, :eager_graph=>nil}.freeze
+    COLUMNS_CLONE_OPTIONS = {:distinct => nil, :limit => 0, :offset=>nil, :where=>nil, :having=>nil, :order=>nil, :row_proc=>nil, :graph=>nil, :eager_graph=>nil}.freeze
 
     # Inserts the given argument into the database.  Returns self so it
     # can be used safely when chaining:
@@ -457,6 +457,55 @@ module Sequel
       _aggregate(:max, arg)
     end
 
+    # Execute a MERGE statement, which allows for INSERT, UPDATE, and DELETE
+    # behavior in a single query, based on whether rows from a source table
+    # match rows in the current table, based on the join conditions.
+    #
+    # Unless the dataset uses static SQL, to use #merge, you must first have
+    # called #merge_using to specify the merge source and join conditions.
+    # You will then likely to call one or more of the following methods
+    # to specify MERGE behavior by adding WHEN [NOT] MATCHED clauses:
+    #
+    # * #merge_insert
+    # * #merge_update
+    # * #merge_delete
+    # 
+    # The WHEN [NOT] MATCHED clauses are added to the SQL in the order these
+    # methods were called on the dataset.  If none of these methods are
+    # called, an error is raised.
+    #
+    # Example:
+    #
+    #   DB[:m1]
+    #     merge_using(:m2, i1: :i2).
+    #     merge_insert(i1: :i2, a: Sequel[:b]+11).
+    #     merge_delete{a > 30}.
+    #     merge_update(i1: Sequel[:i1]+:i2+10, a: Sequel[:a]+:b+20).
+    #     merge
+    #
+    # SQL:
+    #
+    #   MERGE INTO m1 USING m2 ON (i1 = i2)
+    #   WHEN NOT MATCHED THEN INSERT (i1, a) VALUES (i2, (b + 11))
+    #   WHEN MATCHED AND (a > 30) THEN DELETE
+    #   WHEN MATCHED THEN UPDATE SET i1 = (i1 + i2 + 10), a = (a + b + 20)
+    #
+    # On PostgreSQL, two additional merge methods are supported, for the
+    # PostgreSQL-specific DO NOTHING syntax.
+    #
+    # * #merge_do_nothing_when_matched
+    # * #merge_do_nothing_when_not_matched
+    #
+    # This method is supported on Oracle, but Oracle's MERGE support is
+    # non-standard, and has the following issues:
+    #
+    # * DELETE clause requires UPDATE clause
+    # * DELETE clause requires a condition
+    # * DELETE clause only affects rows updated by UPDATE clause
+    def merge
+      execute_ddl(merge_sql)
+    end
+
     # Returns the minimum value for the given column/expression.
     # Uses a virtual row block if no argument is given.
     #
@@ -546,7 +595,7 @@ module Sequel
       unless @opts[:order]
         raise Sequel::Error, "Dataset#paged_each requires the dataset be ordered"
       end
-      unless block_given?
+      unless defined?(yield)
         return enum_for(:paged_each, opts)
       end
 
@@ -607,14 +656,16 @@ module Sequel
     # as_hash, it accepts an optional :hash parameter, into which entries will
     # be merged. 
     #
-    #   DB[:table].select_hash(:id, :name) # SELECT id, name FROM table
+    #   DB[:table].select_hash(:id, :name)
+    #   # SELECT id, name FROM table
     #   # => {1=>'a', 2=>'b', ...}
     #
     # You can also provide an array of column names for either the key_column,
     # the value column, or both:
     #
-    #   DB[:table].select_hash([:id, :foo], [:name, :bar]) # SELECT * FROM table
-    #   # {[1, 3]=>['a', 'c'], [2, 4]=>['b', 'd'], ...}
+    #   DB[:table].select_hash([:id, :foo], [:name, :bar])
+    #   # SELECT id, foo, name, bar FROM table
+    #   # => {[1, 3]=>['a', 'c'], [2, 4]=>['b', 'd'], ...}
     #
     # When using this method, you must be sure that each expression has an alias
     # that Sequel can determine.
@@ -626,14 +677,16 @@ module Sequel
     # Similar to to_hash_groups, but only selects the columns given.  Like to_hash_groups,
     # it accepts an optional :hash parameter, into which entries will be merged. 
     #
-    #   DB[:table].select_hash_groups(:name, :id) # SELECT id, name FROM table
+    #   DB[:table].select_hash_groups(:name, :id)
+    #   # SELECT id, name FROM table
     #   # => {'a'=>[1, 4, ...], 'b'=>[2, ...], ...}
     #
     # You can also provide an array of column names for either the key_column,
     # the value column, or both:
     #
-    #   DB[:table].select_hash_groups([:first, :middle], [:last, :id]) # SELECT * FROM table
-    #   # {['a', 'b']=>[['c', 1], ['d', 2], ...], ...}
+    #   DB[:table].select_hash_groups([:first, :middle], [:last, :id])
+    #   # SELECT first, middle, last, id FROM table
+    #   # => {['a', 'b']=>[['c', 1], ['d', 2], ...], ...}
     #
     # When using this method, you must be sure that each expression has an alias
     # that Sequel can determine.

data/lib/sequel/dataset/features.rb

@@ -51,6 +51,11 @@ module Sequel
       false
     end
 
+    # Whether deleting from joined datasets is supported, false by default.
+    def supports_deleting_joins?
+      supports_modifying_joins?
+    end
+    
     # Whether the database supports derived column lists (e.g.
     # "table_expr AS table_alias(column_alias1, column_alias2, ...)"), true by
     # default.
@@ -120,6 +125,11 @@ module Sequel
       false
     end
 
+    # Whether the MERGE statement is supported, false by default.
+    def supports_merge?
+      false
+    end
+
     # Whether modifying joined datasets is supported, false by default.
     def supports_modifying_joins?
       false
@@ -178,6 +188,11 @@ module Sequel
       true
     end
     
+    # Whether updating joined datasets is supported, false by default.
+    def supports_updating_joins?
+      supports_modifying_joins?
+    end
+    
     # Whether the dataset supports the WINDOW clause to define windows used by multiple
     # window functions, false by default.
     def supports_window_clause?

data/lib/sequel/dataset/placeholder_literalizer.rb

@@ -114,10 +114,8 @@ module Sequel
             prepared_sql << sql
             prepared_sql << "$#{prepared_args[i]}"
           end
-          if final_sql
-            frags << final_sql
-            prepared_sql << final_sql
-          end
+          frags << final_sql
+          prepared_sql << final_sql
 
           [prepared_sql, frags]
         end
@@ -213,9 +211,7 @@ module Sequel
           end
           ds.literal_append(s, v)
         end
-        if sql = @final_sql
-          s << sql
-        end
+        s << @final_sql
         s
       end
     end

data/lib/sequel/dataset/prepared_statements.rb

@@ -201,7 +201,9 @@ module Sequel
         when :insert_pk
           fetch_rows(prepared_sql){|r| return r.values.first}
         when Array
+          # :nocov:
           case prepared_type[0]
+          # :nocov:
           when :map, :as_hash, :to_hash, :to_hash_groups
             public_send(*prepared_type, &block) 
           end