ActiveRecord::ConnectionHandling

Methods

clear_query_caches_for_current_thread
connected?
connected_to
connected_to?
connection
connection_config
connection_pool
connection_specification_name
connects_to
current_role
establish_connection
remove_connection
retrieve_connection

Constants

DEFAULT_ENV	=	-> { RAILS_ENV.call \|\| "default_env" }
RAILS_ENV	=	-> { (Rails.env if defined?(Rails.env)) \|\| ENV["RAILS_ENV"].presence \|\| ENV["RACK_ENV"].presence }

Attributes

[W]

connection_specification_name

Instance Public methods

clear_query_caches_for_current_thread()

Clears the query cache for all connections associated with the current thread.

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 177
    def clear_query_caches_for_current_thread
      ActiveRecord::Base.connection_handlers.each_value do |handler|
        handler.connection_pool_list.each do |pool|
          pool.connection.clear_query_cache if pool.active_connection?
        end
      end
    end

🔎 See on GitHub

connected?()

Returns true if Active Record is connected.

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 225
    def connected?
      connection_handler.connected?(connection_specification_name)
    end

🔎 See on GitHub

connected_to(database: nil, role: nil, prevent_writes: false, &blk)

Connects to a database or role (ex writing, reading, or another custom role) for the duration of the block.

If a role is passed, Active Record will look up the connection based on the requested role:

ActiveRecord::Base.connected_to(role: :writing) do
  Dog.create! # creates dog using dog writing connection
end

ActiveRecord::Base.connected_to(role: :reading) do
  Dog.create! # throws exception because we're on a replica
end

ActiveRecord::Base.connected_to(role: :unknown_role) do
  # raises exception due to non-existent role
end

The `database` kwarg is deprecated in 6.1 and will be removed in 6.2

It is not recommended for use as it re-establishes a connection every time it is called.

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 103
    def connected_to(database: nil, role: nil, prevent_writes: false, &blk)
      if database && role
        raise ArgumentError, "connected_to can only accept a `database` or a `role` argument, but not both arguments."
      elsif database
        if database.is_a?(Hash)
          role, database = database.first
          role = role.to_sym
        end

        config_hash = resolve_config_for_connection(database)
        handler = lookup_connection_handler(role)

        handler.establish_connection(config_hash)

        with_handler(role, &blk)
      elsif role
        prevent_writes = true if role == reading_role

        with_handler(role.to_sym) do
          connection_handler.while_preventing_writes(prevent_writes, &blk)
        end
      else
        raise ArgumentError, "must provide a `database` or a `role`."
      end
    end

🔎 See on GitHub

connected_to?(role:)

Returns true if role is the current connected role.

ActiveRecord::Base.connected_to(role: :writing) do
  ActiveRecord::Base.connected_to?(role: :writing) #=> true
  ActiveRecord::Base.connected_to?(role: :reading) #=> false
end

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 135
    def connected_to?(role:)
      current_role == role.to_sym
    end

🔎 See on GitHub

connection()

Returns the connection currently associated with the class. This can also be used to “borrow” the connection to do database work unrelated to any of the specific Active Records.

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 188
    def connection
      retrieve_connection
    end

🔎 See on GitHub

connection_config()

Returns the configuration of the associated connection as a hash:

ActiveRecord::Base.connection_config
# => {pool: 5, timeout: 5000, database: "db/development.sqlite3", adapter: "sqlite3"}

Please use only for reading.

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 212
    def connection_config
      connection_pool.spec.config
    end

🔎 See on GitHub

connection_pool()

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 216
    def connection_pool
      connection_handler.retrieve_connection_pool(connection_specification_name) || raise(ConnectionNotEstablished)
    end

🔎 See on GitHub

connection_specification_name()

Return the specification name from the current class or its parent.

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 195
    def connection_specification_name
      if !defined?(@connection_specification_name) || @connection_specification_name.nil?
        return self == Base ? "primary" : superclass.connection_specification_name
      end
      @connection_specification_name
    end

🔎 See on GitHub

connects_to(database: {})

Connects a model to the databases specified. The database keyword takes a hash consisting of a role and a database_key.

This will create a connection handler for switching between connections, look up the config hash using the database_key and finally establishes a connection to that config.

class AnimalsModel < ApplicationRecord
  self.abstract_class = true

  connects_to database: { writing: :primary, reading: :primary_replica }
end

Returns an array of established connections.

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 68
    def connects_to(database: {})
      connections = []

      database.each do |role, database_key|
        config_hash = resolve_config_for_connection(database_key)
        handler = lookup_connection_handler(role.to_sym)

        connections << handler.establish_connection(config_hash)
      end

      connections
    end

🔎 See on GitHub

current_role()

Returns the symbol representing the current connected role.

ActiveRecord::Base.connected_to(role: :writing) do
  ActiveRecord::Base.current_role #=> :writing
end

ActiveRecord::Base.connected_to(role: :reading) do
  ActiveRecord::Base.current_role #=> :reading
end

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 148
    def current_role
      connection_handlers.key(connection_handler)
    end

🔎 See on GitHub

establish_connection(config_or_env = nil)

Establishes the connection to the database. Accepts a hash as input where the :adapter key must be specified with the name of a database adapter (in lower-case) example for regular databases (MySQL, PostgreSQL, etc):

ActiveRecord::Base.establish_connection(
  adapter:  "mysql2",
  host:     "localhost",
  username: "myuser",
  password: "mypass",
  database: "somedatabase"
)

Example for SQLite database:

ActiveRecord::Base.establish_connection(
  adapter:  "sqlite3",
  database: "path/to/dbfile"
)

Also accepts keys as strings (for parsing from YAML for example):

ActiveRecord::Base.establish_connection(
  "adapter"  => "sqlite3",
  "database" => "path/to/dbfile"
)

Or a URL:

ActiveRecord::Base.establish_connection(
  "postgres://myuser:mypass@localhost/somedatabase"
)

In case ActiveRecord::Base.configurations is set (Rails automatically loads the contents of config/database.yml into it), a symbol can also be given as argument, representing a key in the configuration hash:

ActiveRecord::Base.establish_connection(:production)

The exceptions AdapterNotSpecified, AdapterNotFound and ArgumentError may be returned on an error.

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 49
    def establish_connection(config_or_env = nil)
      config_hash = resolve_config_for_connection(config_or_env)
      connection_handler.establish_connection(config_hash)
    end

🔎 See on GitHub

remove_connection(name = nil)

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 229
    def remove_connection(name = nil)
      name ||= @connection_specification_name if defined?(@connection_specification_name)
      # if removing a connection that has a pool, we reset the
      # connection_specification_name so it will use the parent
      # pool.
      if connection_handler.retrieve_connection_pool(name)
        self.connection_specification_name = nil
      end

      connection_handler.remove_connection(name)
    end

🔎 See on GitHub

retrieve_connection()

📝 Source code

# File activerecord/lib/active_record/connection_handling.rb, line 220
    def retrieve_connection
      connection_handler.retrieve_connection(connection_specification_name)
    end

🔎 See on GitHub