Active Record Database Configurations

ActiveRecord::DatabaseConfigurations returns an array of DatabaseConfig objects that are constructed from the application’s database configuration hash or URL string.

The array of DatabaseConfig objects in an application default to either a HashConfig or UrlConfig. You can retrieve your application’s config by using ActiveRecord::Base.configurations.

If you register a custom handler, objects will be created according to the conditions of the handler. See ::register_db_config_handler for more on registering custom handlers.

Namespace

Class

Methods

Attributes

[R] configurations

Class Public methods

new(configurations = {})

📝 Source code 
# File activerecord/lib/active_record/database_configurations.rb, line 73
    def initialize(configurations = {})
      @configurations = build_configs(configurations)
    end
🔎 See on GitHub

register_db_config_handler(&block)

Allows an application to register a custom handler for database configuration objects. This is useful for creating a custom handler that responds to methods your application needs but Active Record doesn’t implement. For example if you are using Vitess, you may want your Vitess configurations to respond to ‘sharded?`. To implement this define the following in an initializer:

ActiveRecord::DatabaseConfigurations.register_db_config_handler do |env_name, name, url, config|
  next unless config.key?(:vitess)
  VitessConfig.new(env_name, name, config)
end

Note: applications must handle the condition in which custom config should be created in your handler registration otherwise all objects will use the custom handler.

Then define your VitessConfig to respond to the methods your application needs. It is recommended that you inherit from one of the existing database config classes to avoid having to reimplement all methods. Custom config handlers should only implement methods Active Record does not.

class VitessConfig < ActiveRecord::DatabaseConfigurations::UrlConfig
  def sharded?
    configuration_hash.fetch("sharded", false)
  end
end

For configs that have a :vitess key, a VitessConfig object will be created instead of a UrlConfig.

📝 Source code 
# File activerecord/lib/active_record/database_configurations.rb, line 61
    def self.register_db_config_handler(&block)
      db_config_handlers << block
    end
🔎 See on GitHub

Instance Public methods

blank?()

Alias for: empty?

configs_for(env_name: nil, name: nil, config_key: nil, include_hidden: false)

Collects the configs for the environment and optionally the specification name passed in. To include replica configurations pass include_hidden: true.

If a name is provided a single DatabaseConfig object will be returned, otherwise an array of DatabaseConfig objects will be returned that corresponds with the environment and type requested.

Options

  • env_name: The environment name. Defaults to nil which will collect configs for all environments.

  • name: The db config name (i.e. primary, animals, etc.). Defaults to nil. If no env_name is specified the config for the default env and the passed name will be returned.

  • config_key: Selects configs that contain a particular key in the configuration hash. Useful for selecting configs that use a custom db config handler or finding configs with hashes that contain a particular key.

  • include_hidden: Determines whether to include replicas and configurations hidden by database_tasks: false in the returned list. Most of the time we’re only iterating over the primary connections (i.e. migrations don’t need to run for the write and read connection). Defaults to false.

📝 Source code 
# File activerecord/lib/active_record/database_configurations.rb, line 98
    def configs_for(env_name: nil, name: nil, config_key: nil, include_hidden: false)
      env_name ||= default_env if name
      configs = env_with_configs(env_name)

      unless include_hidden
        configs = configs.select do |db_config|
          db_config.database_tasks?
        end
      end

      if config_key
        configs = configs.select do |db_config|
          db_config.configuration_hash.key?(config_key)
        end
      end

      if name
        configs.find do |db_config|
          db_config.name == name.to_s
        end
      else
        configs
      end
    end
🔎 See on GitHub

empty?()

Checks if the application’s configurations are empty.

Also aliased as: blank?
📝 Source code 
# File activerecord/lib/active_record/database_configurations.rb, line 150
    def empty?
      configurations.empty?
    end
🔎 See on GitHub

find_db_config(env)

Returns a single DatabaseConfig object based on the requested environment.

If the application has multiple databases find_db_config will return the first DatabaseConfig for the environment.

📝 Source code 
# File activerecord/lib/active_record/database_configurations.rb, line 127
    def find_db_config(env)
      env = env.to_s
      configurations.find do |db_config|
        db_config.for_current_env? && (db_config.env_name == env || db_config.name == env)
      end || configurations.find do |db_config|
        db_config.env_name == env
      end
    end
🔎 See on GitHub