activerecord 6.1.4 → 7.0.0.rc1

data/lib/active_record/connection_adapters/abstract/schema_statements.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/string/access"
-require "digest/sha2"
+require "openssl"
 
 module ActiveRecord
   module ConnectionAdapters # :nodoc:
@@ -29,7 +29,7 @@ module ActiveRecord
         table_name[0...table_alias_length].tr(".", "_")
       end
 
-      # Returns the relation names useable to back Active Record models.
+      # Returns the relation names usable to back Active Record models.
       # For most adapters this means all #tables and #views.
       def data_sources
         query_values(data_source_sql, "SCHEMA")
@@ -124,6 +124,9 @@ module ActiveRecord
       #   column_exists?(:suppliers, :name)
       #
       #   # Check a column exists of a particular type
+      #   #
+      #   # This works for standard non-casted types (eg. string) but is unreliable
+      #   # for types that may get cast to something else (eg. char, bigint).
       #   column_exists?(:suppliers, :name, :string)
       #
       #   # Check a column exists with a specific definition
@@ -518,24 +521,31 @@ module ActiveRecord
 
       # Add a new +type+ column named +column_name+ to +table_name+.
       #
+      # See {ActiveRecord::ConnectionAdapters::TableDefinition.column}[rdoc-ref:ActiveRecord::ConnectionAdapters::TableDefinition#column].
+      #
       # The +type+ parameter is normally one of the migrations native types,
       # which is one of the following:
       # <tt>:primary_key</tt>, <tt>:string</tt>, <tt>:text</tt>,
       # <tt>:integer</tt>, <tt>:bigint</tt>, <tt>:float</tt>, <tt>:decimal</tt>, <tt>:numeric</tt>,
       # <tt>:datetime</tt>, <tt>:time</tt>, <tt>:date</tt>,
-      # <tt>:binary</tt>, <tt>:boolean</tt>.
+      # <tt>:binary</tt>, <tt>:blob</tt>, <tt>:boolean</tt>.
       #
       # You may use a type not in this list as long as it is supported by your
       # database (for example, "polygon" in MySQL), but this will not be database
       # agnostic and should usually be avoided.
       #
       # Available options are (none of these exists by default):
+      # * <tt>:comment</tt> -
+      #   Specifies the comment for the column. This option is ignored by some backends.
+      # * <tt>:collation</tt> -
+      #   Specifies the collation for a <tt>:string</tt> or <tt>:text</tt> column.
+      #   If not specified, the column will have the same collation as the table.
+      # * <tt>:default</tt> -
+      #   The column's default value. Use +nil+ for +NULL+.
       # * <tt>:limit</tt> -
       #   Requests a maximum column length. This is the number of characters for a <tt>:string</tt> column
-      #   and number of bytes for <tt>:text</tt>, <tt>:binary</tt>, and <tt>:integer</tt> columns.
+      #   and number of bytes for <tt>:text</tt>, <tt>:binary</tt>, <tt>:blob</tt>, and <tt>:integer</tt> columns.
       #   This option is ignored by some backends.
-      # * <tt>:default</tt> -
-      #   The column's default value. Use +nil+ for +NULL+.
       # * <tt>:null</tt> -
       #   Allows or disallows +NULL+ values in the column.
       # * <tt>:precision</tt> -
@@ -604,7 +614,13 @@ module ActiveRecord
       #  # Ignores the method call if the column exists
       #  add_column(:shapes, :triangle, 'polygon', if_not_exists: true)
       def add_column(table_name, column_name, type, **options)
-        return if options[:if_not_exists] == true && column_exists?(table_name, column_name, type)
+        return if options[:if_not_exists] == true && column_exists?(table_name, column_name)
+
+        if supports_datetime_with_precision?
+          if type == :datetime && !options.key?(:precision)
+            options[:precision] = 6
+          end
+        end
 
         at = create_alter_table table_name
         at.add_column(column_name, type, **options)
@@ -629,9 +645,8 @@ module ActiveRecord
           raise ArgumentError.new("You must specify at least one column name. Example: remove_columns(:people, :first_name)")
         end
 
-        column_names.each do |column_name|
-          remove_column(table_name, column_name, type, **options)
-        end
+        remove_column_fragments = remove_columns_for_alter(table_name, *column_names, type: type, **options)
+        execute "ALTER TABLE #{quote_table_name(table_name)} #{remove_column_fragments.join(', ')}"
       end
 
       # Removes the column from the table definition.
@@ -641,7 +656,8 @@ module ActiveRecord
       # The +type+ and +options+ parameters will be ignored if present. It can be helpful
       # to provide these in a migration's +change+ method so it can be reverted.
       # In that case, +type+ and +options+ will be used by #add_column.
-      # Indexes on the column are automatically removed.
+      # Depending on the database you're using, indexes using this column may be
+      # automatically removed or modified to remove this column from the index.
       #
       # If the options provided include an +if_exists+ key, it will be used to check if the
       # column does not exist. This will silently ignore the migration rather than raising
@@ -766,7 +782,7 @@ module ActiveRecord
       #
       #   CREATE INDEX by_name_surname ON accounts(name(10), surname(15))
       #
-      # Note: SQLite doesn't support index length.
+      # Note: only supported by MySQL
       #
       # ====== Creating an index with a sort order (desc or asc, asc is the default)
       #
@@ -901,7 +917,7 @@ module ActiveRecord
         remove_index(table_name, name: old_name)
       end
 
-      def index_name(table_name, options) #:nodoc:
+      def index_name(table_name, options) # :nodoc:
         if Hash === options
           if options[:column]
             "index_#{table_name}_on_#{Array(options[:column]) * '_and_'}"
@@ -1027,6 +1043,10 @@ module ActiveRecord
       #
       #   ALTER TABLE "articles" ADD CONSTRAINT fk_rails_e74ce85cbc FOREIGN KEY ("author_id") REFERENCES "authors" ("id")
       #
+      # ====== Creating a foreign key, ignoring method call if the foreign key exists
+      #
+      #  add_foreign_key(:articles, :authors, if_not_exists: true)
+      #
       # ====== Creating a foreign key on a specific column
       #
       #   add_foreign_key :articles, :users, column: :author_id, primary_key: "lng_id"
@@ -1054,10 +1074,17 @@ module ActiveRecord
       #   Action that happens <tt>ON DELETE</tt>. Valid values are +:nullify+, +:cascade+ and +:restrict+
       # [<tt>:on_update</tt>]
       #   Action that happens <tt>ON UPDATE</tt>. Valid values are +:nullify+, +:cascade+ and +:restrict+
+      # [<tt>:if_not_exists</tt>]
+      #   Specifies if the foreign key already exists to not try to re-add it. This will avoid
+      #   duplicate column errors.
       # [<tt>:validate</tt>]
       #   (PostgreSQL only) Specify whether or not the constraint should be validated. Defaults to +true+.
+      # [<tt>:deferrable</tt>]
+      #   (PostgreSQL only) Specify whether or not the foreign key should be deferrable. Valid values are booleans or
+      #   +:deferred+ or +:immediate+ to specify the default behavior. Defaults to +false+.
       def add_foreign_key(from_table, to_table, **options)
         return unless supports_foreign_keys?
+        return if options[:if_not_exists] == true && foreign_key_exists?(from_table, to_table)
 
         options = foreign_key_options(from_table, to_table, options)
         at = create_alter_table from_table
@@ -1087,12 +1114,18 @@ module ActiveRecord
       #
       #   remove_foreign_key :accounts, name: :special_fk_name
       #
+      # Checks if the foreign key exists before trying to remove it. Will silently ignore indexes that
+      # don't exist.
+      #
+      #   remove_foreign_key :accounts, :branches, if_exists: true
+      #
       # The +options+ hash accepts the same keys as SchemaStatements#add_foreign_key
       # with an addition of
       # [<tt>:to_table</tt>]
       #   The name of the table that contains the referenced primary key.
       def remove_foreign_key(from_table, to_table = nil, **options)
         return unless supports_foreign_keys?
+        return if options[:if_exists] == true && !foreign_key_exists?(from_table, to_table)
 
         fk_name_to_delete = foreign_key_for!(from_table, to_table: to_table, **options).name
 
@@ -1256,6 +1289,25 @@ module ActiveRecord
         columns
       end
 
+      def distinct_relation_for_primary_key(relation) # :nodoc:
+        values = columns_for_distinct(
+          visitor.compile(relation.table[relation.primary_key]),
+          relation.order_values
+        )
+
+        limited = relation.reselect(values).distinct!
+        limited_ids = select_rows(limited.arel, "SQL").map(&:last)
+
+        if limited_ids.empty?
+          relation.none!
+        else
+          relation.where!(relation.primary_key => limited_ids)
+        end
+
+        relation.limit_value = relation.offset_value = nil
+        relation
+      end
+
       # Adds timestamps (+created_at+ and +updated_at+) columns to +table_name+.
       # Additional options (like +:null+) are forwarded to #add_column.
       #
@@ -1277,11 +1329,10 @@ module ActiveRecord
       #  remove_timestamps(:suppliers)
       #
       def remove_timestamps(table_name, **options)
-        remove_column table_name, :updated_at
-        remove_column table_name, :created_at
+        remove_columns table_name, :updated_at, :created_at
       end
 
-      def update_table_definition(table_name, base) #:nodoc:
+      def update_table_definition(table_name, base) # :nodoc:
         Table.new(table_name, base)
       end
 
@@ -1488,7 +1539,7 @@ module ActiveRecord
         def foreign_key_name(table_name, options)
           options.fetch(:name) do
             identifier = "#{table_name}_#{options.fetch(:column)}_fk"
-            hashed_identifier = Digest::SHA256.hexdigest(identifier).first(10)
+            hashed_identifier = OpenSSL::Digest::SHA256.hexdigest(identifier).first(10)
 
             "fk_rails_#{hashed_identifier}"
           end
@@ -1516,7 +1567,7 @@ module ActiveRecord
           options.fetch(:name) do
             expression = options.fetch(:expression)
             identifier = "#{table_name}_#{expression}_chk"
-            hashed_identifier = Digest::SHA256.hexdigest(identifier).first(10)
+            hashed_identifier = OpenSSL::Digest::SHA256.hexdigest(identifier).first(10)
 
             "chk_rails_#{hashed_identifier}"
           end

data/lib/active_record/connection_adapters/abstract/transaction.rb

@@ -73,7 +73,7 @@ module ActiveRecord
       end
     end
 
-    class NullTransaction #:nodoc:
+    class NullTransaction # :nodoc:
       def initialize; end
       def state; end
       def closed?; true; end
@@ -82,7 +82,7 @@ module ActiveRecord
       def add_record(record, _ = true); end
     end
 
-    class Transaction #:nodoc:
+    class Transaction # :nodoc:
       attr_reader :connection, :state, :savepoint_name, :isolation_level
       attr_accessor :written
 
@@ -221,7 +221,7 @@ module ActiveRecord
       end
     end
 
-    class TransactionManager #:nodoc:
+    class TransactionManager # :nodoc:
       def initialize(connection)
         @stack = []
         @connection = connection
@@ -333,26 +333,19 @@ module ActiveRecord
               # @connection still holds an open or invalid transaction, so we must not
               # put it back in the pool for reuse.
               @connection.throw_away! unless transaction.state.rolledback?
+            elsif Thread.current.status == "aborting" || (!completed && transaction.written)
+              # The transaction is still open but the block returned earlier.
+              #
+              # The block could return early because of a timeout or because the thread is aborting,
+              # so we are rolling back to make sure the timeout didn't caused the transaction to be
+              # committed incompletely.
+              rollback_transaction
             else
-              if Thread.current.status == "aborting"
-                rollback_transaction
-              else
-                if !completed && transaction.written
-                  ActiveSupport::Deprecation.warn(<<~EOW)
-                    Using `return`, `break` or `throw` to exit a transaction block is
-                    deprecated without replacement. If the `throw` came from
-                    `Timeout.timeout(duration)`, pass an exception class as a second
-                    argument so it doesn't use `throw` to abort its block. This results
-                    in the transaction being committed, but in the next release of Rails
-                    it will rollback.
-                  EOW
-                end
-                begin
-                  commit_transaction
-                rescue Exception
-                  rollback_transaction(transaction) unless transaction.state.completed?
-                  raise
-                end
+              begin
+                commit_transaction
+              rescue Exception
+                rollback_transaction(transaction) unless transaction.state.completed?
+                raise
               end
             end
           end

data/lib/active_record/connection_adapters/abstract_adapter.rb

@@ -36,7 +36,7 @@ module ActiveRecord
       include Savepoints
 
       SIMPLE_INT = /\A\d+\z/
-      COMMENT_REGEX = %r{(?:\-\-.*\n)*|/\*(?:[^\*]|\*[^/])*\*/}m
+      COMMENT_REGEX = %r{(?:--.*\n)*|/\*(?:[^*]|\*[^/])*\*/}m
 
       attr_accessor :pool
       attr_reader :visitor, :owner, :logger, :lock
@@ -68,7 +68,7 @@ module ActiveRecord
       def self.build_read_query_regexp(*parts) # :nodoc:
         parts += DEFAULT_READ_QUERY
         parts = parts.map { |part| /#{part}/i }
-        /\A(?:[\(\s]|#{COMMENT_REGEX})*#{Regexp.union(*parts)}/
+        /\A(?:[(\s]|#{COMMENT_REGEX})*#{Regexp.union(*parts)}/
       end
 
       def self.quoted_column_names # :nodoc:
@@ -88,7 +88,7 @@ module ActiveRecord
         @logger              = logger
         @config              = config
         @pool                = ActiveRecord::ConnectionAdapters::NullPool.new
-        @idle_since          = Concurrent.monotonic_time
+        @idle_since          = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         @visitor = arel_visitor
         @statements = build_statement_pool
         @lock = ActiveSupport::Concurrency::LoadInterlockAwareMonitor.new
@@ -102,6 +102,25 @@ module ActiveRecord
         )
       end
 
+      EXCEPTION_NEVER = { Exception => :never }.freeze # :nodoc:
+      EXCEPTION_IMMEDIATE = { Exception => :immediate }.freeze # :nodoc:
+      private_constant :EXCEPTION_NEVER, :EXCEPTION_IMMEDIATE
+      def with_instrumenter(instrumenter, &block) # :nodoc:
+        Thread.handle_interrupt(EXCEPTION_NEVER) do
+          previous_instrumenter = @instrumenter
+          @instrumenter = instrumenter
+          Thread.handle_interrupt(EXCEPTION_IMMEDIATE, &block)
+        ensure
+          @instrumenter = previous_instrumenter
+        end
+      end
+
+      def check_if_write_query(sql) # :nodoc:
+        if preventing_writes? && write_query?(sql)
+          raise ActiveRecord::ReadOnlyError, "Write query attempted while in readonly mode: #{sql}"
+        end
+      end
+
       def replica?
         @config[:replica] || false
       end
@@ -121,10 +140,10 @@ module ActiveRecord
       # will return true based on +current_preventing_writes+.
       def preventing_writes?
         return true if replica?
-        return ActiveRecord::Base.connection_handler.prevent_writes if ActiveRecord::Base.legacy_connection_handling
-        return false if connection_klass.nil?
+        return ActiveRecord::Base.connection_handler.prevent_writes if ActiveRecord.legacy_connection_handling
+        return false if connection_class.nil?
 
-        connection_klass.current_preventing_writes
+        connection_class.current_preventing_writes
       end
 
       def migrations_paths # :nodoc:
@@ -159,7 +178,7 @@ module ActiveRecord
       alias :prepared_statements :prepared_statements?
 
       def prepared_statements_disabled_cache # :nodoc:
-        Thread.current[:ar_prepared_statements_disabled_cache] ||= Set.new
+        ActiveSupport::IsolatedExecutionState[:active_record_prepared_statements_disabled_cache] ||= Set.new
       end
 
       class Version
@@ -201,8 +220,20 @@ module ActiveRecord
         @owner = Thread.current
       end
 
-      def connection_klass # :nodoc:
-        @pool.connection_klass
+      def connection_class # :nodoc:
+        @pool.connection_class
+      end
+
+      # The role (ie :writing) for the current connection. In a
+      # non-multi role application, `:writing` is returned.
+      def role
+        @pool.role
+      end
+
+      # The shard (ie :default) for the current connection. In
+      # a non-sharded application, `:default` is returned.
+      def shard
+        @pool.shard
       end
 
       def schema_cache
@@ -223,7 +254,7 @@ module ActiveRecord
               "Current thread: #{Thread.current}."
           end
 
-          @idle_since = Concurrent.monotonic_time
+          @idle_since = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           @owner = nil
         else
           raise ActiveRecordError, "Cannot expire connection, it is not currently leased."
@@ -246,7 +277,7 @@ module ActiveRecord
       # Seconds since this connection was returned to the pool
       def seconds_idle # :nodoc:
         return 0 if in_use?
-        Concurrent.monotonic_time - @idle_since
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - @idle_since
       end
 
       def unprepared_statement
@@ -344,6 +375,11 @@ module ActiveRecord
         false
       end
 
+      # Does this adapter support creating deferrable constraints?
+      def supports_deferrable_constraints?
+        false
+      end
+
       # Does this adapter support creating check constraints?
       def supports_check_constraints?
         false
@@ -418,6 +454,15 @@ module ActiveRecord
         false
       end
 
+      def supports_concurrent_connections?
+        true
+      end
+
+      def async_enabled? # :nodoc:
+        supports_concurrent_connections? &&
+          !ActiveRecord.async_query_executor.nil? && !pool.async_executor.nil?
+      end
+
       # This is meant to be implemented by the adapters that support extensions
       def disable_extension(name)
       end
@@ -426,6 +471,10 @@ module ActiveRecord
       def enable_extension(name)
       end
 
+      # This is meant to be implemented by the adapters that support custom enum types
+      def create_enum(*) # :nodoc:
+      end
+
       def advisory_locks_enabled? # :nodoc:
         supports_advisory_locks? && @advisory_locks_enabled
       end
@@ -461,6 +510,11 @@ module ActiveRecord
         yield
       end
 
+      # Override to check all foreign key constraints in a database.
+      def all_foreign_keys_valid?
+        true
+      end
+
       # CONNECTION MANAGEMENT ====================================
 
       # Checks whether the connection to the database is still active. This includes
@@ -599,78 +653,93 @@ module ActiveRecord
       def check_version # :nodoc:
       end
 
-      private
-        def type_map
-          @type_map ||= Type::TypeMap.new.tap do |mapping|
-            initialize_type_map(mapping)
-          end
+      # Returns the version identifier of the schema currently available in
+      # the database. This is generally equal to the number of the highest-
+      # numbered migration that has been executed, or 0 if no schema
+      # information is present / the database is empty.
+      def schema_version
+        migration_context.current_version
+      end
+
+      def field_ordered_value(column, values) # :nodoc:
+        node = Arel::Nodes::Case.new(column)
+        values.each.with_index(1) do |value, order|
+          node.when(value).then(order)
         end
 
-        def initialize_type_map(m = type_map)
-          register_class_with_limit m, %r(boolean)i,       Type::Boolean
-          register_class_with_limit m, %r(char)i,          Type::String
-          register_class_with_limit m, %r(binary)i,        Type::Binary
-          register_class_with_limit m, %r(text)i,          Type::Text
-          register_class_with_precision m, %r(date)i,      Type::Date
-          register_class_with_precision m, %r(time)i,      Type::Time
-          register_class_with_precision m, %r(datetime)i,  Type::DateTime
-          register_class_with_limit m, %r(float)i,         Type::Float
-          register_class_with_limit m, %r(int)i,           Type::Integer
-
-          m.alias_type %r(blob)i,      "binary"
-          m.alias_type %r(clob)i,      "text"
-          m.alias_type %r(timestamp)i, "datetime"
-          m.alias_type %r(numeric)i,   "decimal"
-          m.alias_type %r(number)i,    "decimal"
-          m.alias_type %r(double)i,    "float"
-
-          m.register_type %r(^json)i, Type::Json.new
-
-          m.register_type(%r(decimal)i) do |sql_type|
-            scale = extract_scale(sql_type)
-            precision = extract_precision(sql_type)
-
-            if scale == 0
-              # FIXME: Remove this class as well
-              Type::DecimalWithoutScale.new(precision: precision)
-            else
-              Type::Decimal.new(precision: precision, scale: scale)
+        Arel::Nodes::Ascending.new(node.else(values.length + 1))
+      end
+
+      class << self
+        private
+          def initialize_type_map(m)
+            register_class_with_limit m, %r(boolean)i,       Type::Boolean
+            register_class_with_limit m, %r(char)i,          Type::String
+            register_class_with_limit m, %r(binary)i,        Type::Binary
+            register_class_with_limit m, %r(text)i,          Type::Text
+            register_class_with_precision m, %r(date)i,      Type::Date
+            register_class_with_precision m, %r(time)i,      Type::Time
+            register_class_with_precision m, %r(datetime)i,  Type::DateTime
+            register_class_with_limit m, %r(float)i,         Type::Float
+            register_class_with_limit m, %r(int)i,           Type::Integer
+
+            m.alias_type %r(blob)i,      "binary"
+            m.alias_type %r(clob)i,      "text"
+            m.alias_type %r(timestamp)i, "datetime"
+            m.alias_type %r(numeric)i,   "decimal"
+            m.alias_type %r(number)i,    "decimal"
+            m.alias_type %r(double)i,    "float"
+
+            m.register_type %r(^json)i, Type::Json.new
+
+            m.register_type(%r(decimal)i) do |sql_type|
+              scale = extract_scale(sql_type)
+              precision = extract_precision(sql_type)
+
+              if scale == 0
+                # FIXME: Remove this class as well
+                Type::DecimalWithoutScale.new(precision: precision)
+              else
+                Type::Decimal.new(precision: precision, scale: scale)
+              end
             end
           end
-        end
 
-        def reload_type_map
-          type_map.clear
-          initialize_type_map
-        end
+          def register_class_with_limit(mapping, key, klass)
+            mapping.register_type(key) do |*args|
+              limit = extract_limit(args.last)
+              klass.new(limit: limit)
+            end
+          end
 
-        def register_class_with_limit(mapping, key, klass)
-          mapping.register_type(key) do |*args|
-            limit = extract_limit(args.last)
-            klass.new(limit: limit)
+          def register_class_with_precision(mapping, key, klass)
+            mapping.register_type(key) do |*args|
+              precision = extract_precision(args.last)
+              klass.new(precision: precision)
+            end
           end
-        end
 
-        def register_class_with_precision(mapping, key, klass)
-          mapping.register_type(key) do |*args|
-            precision = extract_precision(args.last)
-            klass.new(precision: precision)
+          def extract_scale(sql_type)
+            case sql_type
+            when /\((\d+)\)/ then 0
+            when /\((\d+)(,(\d+))\)/ then $3.to_i
+            end
           end
-        end
 
-        def extract_scale(sql_type)
-          case sql_type
-          when /\((\d+)\)/ then 0
-          when /\((\d+)(,(\d+))\)/ then $3.to_i
+          def extract_precision(sql_type)
+            $1.to_i if sql_type =~ /\((\d+)(,\d+)?\)/
           end
-        end
 
-        def extract_precision(sql_type)
-          $1.to_i if sql_type =~ /\((\d+)(,\d+)?\)/
-        end
+          def extract_limit(sql_type)
+            $1.to_i if sql_type =~ /\((.*)\)/
+          end
+      end
+
+      TYPE_MAP = Type::TypeMap.new.tap { |m| initialize_type_map(m) }
 
-        def extract_limit(sql_type)
-          $1.to_i if sql_type =~ /\((.*)\)/
+      private
+        def type_map
+          TYPE_MAP
         end
 
         def translate_exception_class(e, sql, binds)
@@ -683,7 +752,7 @@ module ActiveRecord
           exception
         end
 
-        def log(sql, name = "SQL", binds = [], type_casted_binds = [], statement_name = nil) # :doc:
+        def log(sql, name = "SQL", binds = [], type_casted_binds = [], statement_name = nil, async: false, &block) # :doc:
           @instrumenter.instrument(
             "sql.active_record",
             sql:               sql,
@@ -691,15 +760,21 @@ module ActiveRecord
             binds:             binds,
             type_casted_binds: type_casted_binds,
             statement_name:    statement_name,
+            async:             async,
             connection:        self) do
-            @lock.synchronize do
-              yield
-            end
+            @lock.synchronize(&block)
           rescue => e
             raise translate_exception_class(e, sql, binds)
           end
         end
 
+        def transform_query(sql)
+          ActiveRecord.query_transformers.each do |transformer|
+            sql = transformer.call(sql)
+          end
+          sql
+        end
+
         def translate_exception(exception, message:, sql:, binds:)
           # override in derived class
           case exception