class ActiveRecord::ConnectionAdapters::AbstractAdapter

Active Record Abstract Adapter

Active Record supports multiple database systems. AbstractAdapter and related classes form the abstraction layer which makes this possible. An AbstractAdapter represents a connection to a database, and provides an abstract interface for database-specific functionality such as establishing a connection, escaping values, building the right SQL fragments for :offset and :limit options, etc.

All the concrete database adapters follow the interface laid down in this class. ActiveRecord::Base.lease_connection returns an AbstractAdapter object, which you can use.

Most of the methods in the adapter are useful during migrations. Most notably, the instance methods provided by SchemaStatements are very useful.

Constants

ADAPTER_NAME
COMMENT_REGEX
EXTENDED_TYPE_MAPS
SIMPLE_INT
TYPE_MAP

Attributes

in_use? [R]

lock [R]

logger [R]

owner [R]

pool [R]

visitor [R]

Public Class Methods

database_exists? (config)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 403
def self.database_exists?(config)
  new(config).database_exists?
end

Does the database for this adapter exist?

dbconsole (config, options = {})

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 128
def self.dbconsole(config, options = {})
  raise NotImplementedError.new("#{self.class} should define `dbconsole` that accepts a db config and options to implement connecting to the db console")
end

Opens a database console session.

find_cmd_and_exec (commands, *args)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 99
def self.find_cmd_and_exec(commands, *args) # :doc:
  commands = Array(commands)

  dirs_on_path = ENV["PATH"].to_s.split(File::PATH_SEPARATOR)
  unless (ext = RbConfig::CONFIG["EXEEXT"]).empty?
    commands = commands.map { |cmd| "#{cmd}#{ext}" }
  end

  full_path_command = nil
  found = commands.detect do |cmd|
    dirs_on_path.detect do |path|
      full_path_command = File.join(path, cmd)
      begin
        stat = File.stat(full_path_command)
      rescue SystemCallError
      else
        stat.file? && stat.executable?
      end
    end
  end

  if found
    exec full_path_command, *args
  else
    abort("Couldn't find database client: #{commands.join(', ')}. Check your $PATH and try again.")
  end
end

type_cast_config_to_boolean (config)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 72
def self.type_cast_config_to_boolean(config)
  if config == "false"
    false
  else
    config
  end
end

type_cast_config_to_integer (config)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 62
def self.type_cast_config_to_integer(config)
  if config.is_a?(Integer)
    config
  elsif SIMPLE_INT.match?(config)
    config.to_i
  else
    config
  end
end

validate_default_timezone (config)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 80
def self.validate_default_timezone(config)
  case config
  when nil
  when "utc", "local"
    config.to_sym
  else
    raise ArgumentError, "default_timezone must be either 'utc' or 'local'"
  end
end

Private Class Methods

extract_limit (sql_type)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1008
def extract_limit(sql_type)
  $1.to_i if sql_type =~ /\((.*)\)/
end

extract_precision (sql_type)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1004
def extract_precision(sql_type)
  $1.to_i if sql_type =~ /\((\d+)(,\d+)?\)/
end

extract_scale (sql_type)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 997
def extract_scale(sql_type)
  case sql_type
  when /\((\d+)\)/ then 0
  when /\((\d+)(,(\d+))\)/ then $3.to_i
  end
end

initialize_type_map (m)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 957
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.freeze

  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).freeze
    else
      Type::Decimal.new(precision: precision, scale: scale).freeze
    end
  end
end

register_class_with_limit (mapping, key, klass)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 990
def register_class_with_limit(mapping, key, klass)
  mapping.register_type(key) do |*args|
    limit = extract_limit(args.last)
    klass.new(limit: limit).freeze
  end
end

Public Instance Methods

active? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 705
def active?
end

Checks whether the connection to the database is still active. This includes checking whether the database is actually capable of responding, i.e. whether the connection isn’t stale.

adapter_name ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 398
def adapter_name
  self.class::ADAPTER_NAME
end

Returns the human-readable name of the adapter. Use mixed case - one can always use downcase if needed.

check_all_foreign_keys_valid! ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 690
def check_all_foreign_keys_valid!
end

Override to check all foreign key constraints in a database. The adapter should raise a ActiveRecord::StatementInvalid if foreign key constraints are not met.

clear_cache! (new_connection: false)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 795
def clear_cache!(new_connection: false)
  if @statements
    @lock.synchronize do
      if new_connection
        @statements.reset
      else
        @statements.clear
      end
    end
  end
end

Clear any caching the database adapter may be doing.

close ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 897
def close
  pool.checkin self
end

Check the connection back in to the connection pool

connect! ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 838
def connect!
  verify!
  self
end

connected? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 698
def connected?
  !@raw_connection.nil?
end

Checks whether the connection to the database was established. This doesn’t include checking whether the database is actually capable of responding, i.e. whether the connection is stale.

connection_retries ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 221
def connection_retries
  (@config[:connection_retries] || 1).to_i
end

database_exists? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 407
def database_exists?
  connect!
  true
rescue ActiveRecord::NoDatabaseError
  false
end

default_timezone ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 237
def default_timezone
  @default_timezone || ActiveRecord.default_timezone
end

disable_extension (name, **)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 617
def disable_extension(name, **)
end

This is meant to be implemented by the adapters that support extensions

disable_referential_integrity () { || ... }

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 683
def disable_referential_integrity
  yield
end

Override to turn off referential integrity while executing &block.

discard! ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 768
def discard!
  # This should be overridden by concrete adapters.
end

Immediately forget this connection ever existed. Unlike disconnect!, this will not communicate with the server.

After calling this method, the behavior of all other methods becomes undefined. This is called internally just before a forked process gets rid of a connection that belonged to its parent.

disconnect! ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 751
def disconnect!
  @lock.synchronize do
    clear_cache!(new_connection: true)
    reset_transaction
    @raw_connection_dirty = false
    @connected_since = nil
    @last_activity = nil
    @verified = false
  end
end

Disconnects from the database if already connected. Otherwise, this method does nothing.

enable_extension (name, **)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 621
def enable_extension(name, **)
end

This is meant to be implemented by the adapters that support extensions

extensions ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 671
def extensions
  []
end

A list of extensions, to be filled in by adapters that support them.

index_algorithms ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 676
def index_algorithms
  {}
end

A list of index algorithms, to be filled by adapters that support them.

lease ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 289
def lease
  if in_use?
    msg = +"Cannot lease connection, "
    if @owner == ActiveSupport::IsolatedExecutionState.context
      msg << "it is already leased by the current thread."
    else
      msg << "it is already in use by a different thread: #{@owner}. " \
             "Current thread: #{ActiveSupport::IsolatedExecutionState.context}."
    end
    raise ActiveRecordError, msg
  end

  @owner = ActiveSupport::IsolatedExecutionState.context
end

this method must only be called while holding connection pool’s mutex

max_jitter ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 213
def max_jitter
  (@config[:pool_jitter] || 0.2).to_f.clamp(MAX_JITTER)
end

pool= (value)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 50
def pool=(value)
  return if value.eql?(@pool)
  @schema_cache = nil
  @pool = value
end

pool_jitter (duration)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 324
def pool_jitter(duration)
  duration * (1.0 - @pool_jitter)
end

prefetch_primary_key? (table_name = nil)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 447
def prefetch_primary_key?(table_name = nil)
  false
end

Should primary key values be selected from their corresponding sequence before the insert statement? If true, next_sequence_value is called before each insert to set the record’s primary key.

prepared_statements ()

Alias for: prepared_statements?

prepared_statements? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 252
def prepared_statements?
  @prepared_statements && !prepared_statements_disabled_cache.include?(object_id)
end

Also aliased as: prepared_statements

preventing_writes? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 245
def preventing_writes?
  return true if replica?
  return false if connection_descriptor.nil?

  connection_descriptor.current_preventing_writes
end

Determines whether writes are currently being prevented.

Returns true if the connection is a replica or returns the value of current_preventing_writes.

raw_connection ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 865
def raw_connection
  with_raw_connection do |conn|
    disable_lazy_transactions!
    @raw_connection_dirty = true
    conn
  end
end

Provides access to the underlying database driver for this adapter. For example, this method returns a Mysql2::Client object in case of Mysql2Adapter, and a PG::Connection object in case of PostgreSQLAdapter.

This is useful for when you need to call a proprietary method such as PostgreSQL’s lo_* methods.

Active Record cannot track if the database is getting modified using this client. If that is the case, generally you’ll want to invalidate the query cache using ActiveRecord::Base.clear_query_cache.

reconnect! (restore_transactions: false)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 711
def reconnect!(restore_transactions: false)
  retries_available = connection_retries
  deadline = retry_deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) + retry_deadline

  @lock.synchronize do
    attempt_configure_connection do
      @allow_preconnect = false

      reconnect

      enable_lazy_transactions!
      @raw_connection_dirty = false
      @last_activity = @connected_since = Process.clock_gettime(Process::CLOCK_MONOTONIC)
      @verified = true
      @allow_preconnect = true

      reset_transaction(restore: restore_transactions) do
        clear_cache!(new_connection: true)
        configure_connection
      end
    rescue => original_exception
      translated_exception = translate_exception_class(original_exception, nil, nil)
      retry_deadline_exceeded = deadline && deadline < Process.clock_gettime(Process::CLOCK_MONOTONIC)

      if !retry_deadline_exceeded && retries_available > 0
        retries_available -= 1

        if retryable_connection_error?(translated_exception)
          backoff(connection_retries - retries_available)
          retry
        end
      end

      raise translated_exception
    end
  end
end

Disconnects from the database if already connected, and establishes a new connection with the database. Implementors should define private reconnect instead.

replica? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 217
def replica?
  @config[:replica] || false
end

requires_reloading? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 808
def requires_reloading?
  false
end

Returns true if its required to reload the connection between requests for development mode.

reset! ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 780
def reset!
  attempt_configure_connection do
    clear_cache!(new_connection: true)
    reset_transaction
    configure_connection
  end
end

Reset the state of this connection, directing the DBMS to clear transactions and other connection-related server-side state. Usually a database-dependent operation.

If a database driver or protocol does not support such a feature, implementors may alias this to reconnect!. Otherwise, implementors should call super immediately after resetting the connection (and while still holding @lock).

retry_deadline ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 229
def retry_deadline
  if @config[:retry_deadline]
    @config[:retry_deadline].to_f
  else
    nil
  end
end

role ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 310
def role
  @pool.role
end

The role (e.g. :writing) for the current connection. In a non-multi role application, :writing is returned.

savepoint_errors_invalidate_transactions? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 431
def savepoint_errors_invalidate_transactions?
  false
end

Do TransactionRollbackErrors on savepoints affect the parent transaction?

schema_cache ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 320
def schema_cache
  @pool.schema_cache || (@schema_cache ||= BoundSchemaReflection.for_lone_connection(@pool.schema_reflection, self))
end

schema_version ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 932
def schema_version
  pool.migration_context.current_version
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.

shard ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 316
def shard
  @pool.shard
end

The shard (e.g. :default) for the current connection. In a non-sharded application, :default is returned.

supports_advisory_locks? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 440
def supports_advisory_locks?
  false
end

Does this adapter support application-enforced advisory locking?

supports_bulk_alter? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 420
def supports_bulk_alter?
  false
end

supports_check_constraints? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 512
def supports_check_constraints?
  false
end

Does this adapter support creating check constraints?

supports_comments? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 547
def supports_comments?
  false
end

Does this adapter support metadata comments on database objects (tables, columns, indexes)?

supports_comments_in_create? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 552
def supports_comments_in_create?
  false
end

Can comments for tables, columns, and indexes be specified in create/alter table statements?

supports_common_table_expressions? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 571
def supports_common_table_expressions?
  false
end

supports_concurrent_connections? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 595
def supports_concurrent_connections?
  true
end

supports_datetime_with_precision? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 537
def supports_datetime_with_precision?
  false
end

Does this adapter support datetime with precision?

supports_ddl_transactions? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 416
def supports_ddl_transactions?
  false
end

Does this adapter support DDL rollbacks in transactions? That is, would CREATE TABLE or ALTER TABLE get rolled back by a transaction?

supports_deferrable_constraints? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 507
def supports_deferrable_constraints?
  false
end

Does this adapter support creating deferrable constraints?

supports_disabling_indexes? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 603
def supports_disabling_indexes?
  false
end

supports_exclusion_constraints? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 517
def supports_exclusion_constraints?
  false
end

Does this adapter support creating exclusion constraints?

supports_explain? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 476
def supports_explain?
  false
end

Does this adapter support explain?

supports_expression_index? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 471
def supports_expression_index?
  false
end

Does this adapter support expression indices?

supports_extensions? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 486
def supports_extensions?
  false
end

Does this adapter support database extensions?

supports_foreign_keys? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 497
def supports_foreign_keys?
  false
end

Does this adapter support creating foreign key constraints?

supports_foreign_tables? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 562
def supports_foreign_tables?
  false
end

Does this adapter support foreign/external tables?

supports_index_include? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 466
def supports_index_include?
  false
end

Does this adapter support including non-key columns?

supports_index_sort_order? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 456
def supports_index_sort_order?
  false
end

Does this adapter support index sort order?

supports_indexes_in_create? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 492
def supports_indexes_in_create?
  false
end

Does this adapter support creating indexes in the same statement as creating the table?

supports_insert_conflict_target? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 591
def supports_insert_conflict_target?
  false
end

supports_insert_on_duplicate_skip? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 583
def supports_insert_on_duplicate_skip?
  false
end

supports_insert_on_duplicate_update? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 587
def supports_insert_on_duplicate_update?
  false
end

supports_insert_returning? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 579
def supports_insert_returning?
  false
end

supports_json? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 542
def supports_json?
  false
end

Does this adapter support JSON data type?

supports_lazy_transactions? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 575
def supports_lazy_transactions?
  false
end

supports_materialized_views? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 532
def supports_materialized_views?
  false
end

Does this adapter support materialized views?

supports_nulls_not_distinct? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 599
def supports_nulls_not_distinct?
  false
end

supports_optimizer_hints? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 567
def supports_optimizer_hints?
  false
end

Does this adapter support optimizer hints?

supports_partial_index? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 461
def supports_partial_index?
  false
end

Does this adapter support partial indices?

supports_partitioned_indexes? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 451
def supports_partitioned_indexes?
  false
end

supports_restart_db_transaction? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 435
def supports_restart_db_transaction?
  false
end

supports_savepoints? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 425
def supports_savepoints?
  false
end

Does this adapter support savepoints?

supports_transaction_isolation? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 481
def supports_transaction_isolation?
  false
end

Does this adapter support setting the isolation level for a transaction?

supports_unique_constraints? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 522
def supports_unique_constraints?
  false
end

Does this adapter support creating unique constraints?

supports_validate_constraints? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 502
def supports_validate_constraints?
  false
end

Does this adapter support creating invalid constraints?

supports_views? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 527
def supports_views?
  false
end

Does this adapter support views?

supports_virtual_columns? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 557
def supports_virtual_columns?
  false
end

Does this adapter support virtual columns?

throw_away! ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 789
def throw_away!
  pool.remove self
  disconnect!
end

Removes the connection from the pool and disconnect it.

unprepared_statement () { || ... }

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 389
def unprepared_statement
  cache = prepared_statements_disabled_cache.add?(object_id) if @prepared_statements
  yield
ensure
  cache&.delete(object_id)
end

verify! ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 815
def verify!
  unless active?
    @lock.synchronize do
      if @unconfigured_connection
        attempt_configure_connection do
          @raw_connection = @unconfigured_connection
          @unconfigured_connection = nil
          configure_connection
          @last_activity = Process.clock_gettime(Process::CLOCK_MONOTONIC)
          @verified = true
          @allow_preconnect = true
        end
        return
      end

      reconnect!(restore_transactions: true)
    end
  end

  @last_activity = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  @verified = true
end

Checks whether the connection to the database is still active (i.e. not stale). This is done under the hood by calling active?. If the connection is no longer active, then this method will reconnect to the database.

verify_timeout ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 225
def verify_timeout
  (@config[:verify_timeout] || 2).to_i
end

Private Instance Methods

any_raw_connection ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1160
def any_raw_connection
  @raw_connection || valid_raw_connection
end

Returns a raw connection for internal use with methods that are known to both be thread-safe and not rely upon actual server communication. This is useful for e.g. string escaping methods.

arel_visitor ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1263
def arel_visitor
  Arel::Visitors::ToSql.new(self)
end

attempt_configure_connection () { || ... }

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1289
def attempt_configure_connection
  yield
rescue Exception # Need to handle things such as Timeout::ExitException
  disconnect!
  raise
end

backoff (counter)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1149
def backoff(counter)
  sleep 0.1 * counter
end

build_result (columns:, rows:, column_types: nil)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1274
def build_result(columns:, rows:, column_types: nil)
  ActiveRecord::Result.new(columns, rows, column_types)
end

Builds the result object.

This is an internal hook to make possible connection adapters to build custom result objects with connection-specific data.

build_statement_pool ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1267
def build_statement_pool
end

can_perform_case_insensitive_comparison_for? (column)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 891
def can_perform_case_insensitive_comparison_for?(column)
  true
end

collector ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1249
def collector
  if prepared_statements
    Arel::Collectors::Composite.new(
      Arel::Collectors::SQLString.new,
      Arel::Collectors::Bind.new,
    )
  else
    Arel::Collectors::SubstituteBinds.new(
      self,
      Arel::Collectors::SQLString.new,
    )
  end
end

column_for (table_name, column_name)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1238
def column_for(table_name, column_name)
  column_name = column_name.to_s
  columns(table_name).detect { |c| c.name == column_name } ||
    raise(ActiveRecordError, "No such column: #{table_name}.#{column_name}")
end

column_for_attribute (attribute)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1244
def column_for_attribute(attribute)
  table_name = attribute.relation.name
  schema_cache.columns_hash(table_name)[attribute.name.to_s]
end

configure_connection ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1285
def configure_connection
  check_version
end

Perform any necessary initialization upon the newly-established @raw_connection – this is the place to modify the adapter’s connection settings, run queries to configure any application-global “session” variables, etc.

Implementations may assume this method will only be called while holding @lock (or from initialize).

default_prepared_statements ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1296
def default_prepared_statements
  true
end

extended_type_map_key ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1177
def extended_type_map_key
  if @default_timezone
    { default_timezone: @default_timezone }
  end
end

invalidate_transaction (exception)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1135
def invalidate_transaction(exception)
  return unless exception.is_a?(TransactionRollbackError)
  return unless savepoint_errors_invalidate_transactions?

  current_transaction.invalidate!
end

log (sql, name = "SQL", binds = [], type_casted_binds = [], async: false, allow_retry: false, &block)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1205
def log(sql, name = "SQL", binds = [], type_casted_binds = [], async: false, allow_retry: false, &block) # :doc:
  instrumenter.instrument(
    "sql.active_record",
    sql:               sql,
    name:              name,
    binds:             binds,
    type_casted_binds: type_casted_binds,
    async:             async,
    allow_retry:       allow_retry,
    connection:        self,
    transaction:       current_transaction.user_transaction.presence,
    affected_rows:     0,
    row_count:         0,
    &block
  )
rescue ActiveRecord::StatementInvalid => ex
  raise ex.set_query(sql, binds)
end

reconnect ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1153
def reconnect
  raise NotImplementedError.new("#{self.class} should define `reconnect` to implement adapter-specific logic for reconnecting to the database")
end

reconnect_can_restore_state? ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1017
def reconnect_can_restore_state?
  transaction_manager.restorable? && !@raw_connection_dirty
end

retryable_connection_error? (exception)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1130
def retryable_connection_error?(exception)
  (exception.is_a?(ConnectionNotEstablished) && !exception.is_a?(ConnectionNotDefined)) ||
    exception.is_a?(ConnectionFailed)
end

retryable_query_error? (exception)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1142
def retryable_query_error?(exception)
  # We definitely can't retry if we were inside an invalidated transaction.
  return false if current_transaction.invalidated?

  exception.is_a?(Deadlocked) || exception.is_a?(LockWaitTimeout)
end

translate_exception (exception, message:, sql:, binds:)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1228
def translate_exception(exception, message:, sql:, binds:)
  # override in derived class
  case exception
  when RuntimeError, ActiveRecord::ActiveRecordError
    exception
  else
    ActiveRecord::StatementInvalid.new(message, sql: sql, binds: binds, connection_pool: @pool)
  end
end

translate_exception_class (native_error, sql, binds)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1193
def translate_exception_class(native_error, sql, binds)
  return native_error if native_error.is_a?(ActiveRecordError)

  message = "#{native_error.class.name}: #{native_error.message}"

  active_record_error = translate_exception(
    native_error, message: message, sql: sql, binds: binds
  )
  active_record_error.set_backtrace(native_error.backtrace)
  active_record_error
end

type_map ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1183
def type_map
  if key = extended_type_map_key
    self.class::EXTENDED_TYPE_MAPS.compute_if_absent(key) do
      self.class.extended_type_map(**key)
    end
  else
    self.class::TYPE_MAP
  end
end

valid_raw_connection ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1169
def valid_raw_connection
  (@verified && @raw_connection) ||
    # `allow_retry: false`, to force verification: the block won't
    # raise, so a retry wouldn't help us get the valid connection we
    # need.
    with_raw_connection(allow_retry: false, materialize_transactions: false) { |conn| conn }
end

Similar to any_raw_connection, but ensures it is validated and connected. Any method called on this result still needs to be independently thread-safe, so it probably shouldn’t talk to the server… but some drivers fail if they know the connection has gone away.

verified! ()

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1125
def verified!
  @last_activity = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  @verified = true
end

Mark the connection as verified. Call this inside a ‘with_raw_connection` block only when the block is guaranteed to exercise the raw connection.

warning_ignored? (warning)

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1300
def warning_ignored?(warning)
  ActiveRecord.db_warnings_ignore.any? do |warning_matcher|
    warning.message.match?(warning_matcher) || warning.code.to_s.match?(warning_matcher)
  end
end

with_raw_connection (allow_retry: false, materialize_transactions: true) { |raw_connection| ... }

Source

# File lib/active_record/connection_adapters/abstract_adapter.rb, line 1054
def with_raw_connection(allow_retry: false, materialize_transactions: true)
  @lock.synchronize do
    connect! if @raw_connection.nil? && reconnect_can_restore_state?

    self.materialize_transactions if materialize_transactions

    retries_available = allow_retry ? connection_retries : 0
    deadline = retry_deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) + retry_deadline
    reconnectable = reconnect_can_restore_state?

    if @verified
      # Cool, we're confident the connection's ready to use. (Note this might have
      # become true during the above #materialize_transactions.)
    elsif (last_activity = seconds_since_last_activity) && last_activity < verify_timeout
      # We haven't actually verified the connection since we acquired it, but it
      # has been used very recently. We're going to assume it's still okay.
    elsif reconnectable
      if allow_retry
        # Not sure about the connection yet, but if anything goes wrong we can
        # just reconnect and re-run our query
      else
        # We can reconnect if needed, but we don't trust the upcoming query to be
        # safely re-runnable: let's verify the connection to be sure
        verify!
      end
    else
      # We don't know whether the connection is okay, but it also doesn't matter:
      # we wouldn't be able to reconnect anyway. We're just going to run our query
      # and hope for the best.
    end

    begin
      yield @raw_connection
    rescue => original_exception
      translated_exception = translate_exception_class(original_exception, nil, nil)
      invalidate_transaction(translated_exception)
      retry_deadline_exceeded = deadline && deadline < Process.clock_gettime(Process::CLOCK_MONOTONIC)

      if !retry_deadline_exceeded && retries_available > 0
        retries_available -= 1

        if retryable_query_error?(translated_exception)
          backoff(connection_retries - retries_available)
          retry
        elsif reconnectable && retryable_connection_error?(translated_exception)
          reconnect!(restore_transactions: true)
          # Only allowed to reconnect once, because reconnect! has its own retry
          # loop
          reconnectable = false
          retry
        end
      end

      unless retryable_query_error?(translated_exception)
        # Barring a known-retryable error inside the query (regardless of
        # whether we were in a _position_ to retry it), we should infer that
        # there's likely a real problem with the connection.
        @last_activity = nil
        @verified = false
      end

      raise translated_exception
    ensure
      dirty_current_transaction if materialize_transactions
    end
  end
end

Lock the monitor, ensure we’re properly connected and transactions are materialized, and then yield the underlying raw connection object.

If allow_retry is true, a connection-related exception will cause an automatic reconnect and re-run of the block, up to the connection’s configured connection_retries setting and the configured retry_deadline limit. (Note that when allow_retry is true, it’s possible to return without having marked the connection as verified. If the block is guaranteed to exercise the connection, consider calling ‘verified!` to avoid needless verification queries in subsequent calls.)

If materialize_transactions is false, the block will be run without ensuring virtual transactions have been materialized in the DB server’s state. The active transaction will also remain clean (if it is not already dirty), meaning it’s able to be restored by reconnecting and opening an equivalent-depth set of new transactions. This should only be used by transaction control methods, and internal transaction-agnostic queries.

It’s not the primary use case, so not something to optimize for, but note that this method does need to be re-entrant: materialize_transactions will re-enter if it has work to do, and the yield block can also do so under some circumstances.

In the latter case, we really ought to guarantee the inner call will not reconnect (which would interfere with the still-yielded connection in the outer block), but we currently provide no special enforcement there.