Class: ActiveRecord::DatabaseConfigurations

Inherits:
Object
  • Object
show all
Defined in:
activerecord/lib/active_record/database_configurations.rb,
activerecord/lib/active_record/database_configurations/url_config.rb,
activerecord/lib/active_record/database_configurations/hash_config.rb,
activerecord/lib/active_record/database_configurations/database_config.rb,
activerecord/lib/active_record/database_configurations/connection_url_resolver.rb

Overview

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.

Defined Under Namespace

Classes: ConnectionUrlResolver, DatabaseConfig, HashConfig, InvalidConfigurationError, UrlConfig

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(configurations = {}) ⇒ DatabaseConfigurations

Returns a new instance of DatabaseConfigurations.



75
76
77
 
# File 'activerecord/lib/active_record/database_configurations.rb', line 75

def initialize(configurations = {})
  @configurations = build_configs(configurations)
end

Instance Attribute Details

#configurations ⇒ Object (readonly)

Returns the value of attribute configurations.



26
27
28
 
# File 'activerecord/lib/active_record/database_configurations.rb', line 26

def configurations
  @configurations
end

#db_config_handlers ⇒ Object

:nodoc:



29
30
31
 
# File 'activerecord/lib/active_record/database_configurations.rb', line 29

def db_config_handlers
  @db_config_handlers
end

Class Method Details

.register_db_config_handler(&block) ⇒ Object

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:

ActiveSupport.on_load(:active_record_database_configurations) do
ActiveRecord::DatabaseConfigurations.register_db_config_handler do |env_name, name, url, config|
  next unless config.key?(:vitess)
  VitessConfig.new(env_name, name, config)
end
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.



63
64
65
 
# File 'activerecord/lib/active_record/database_configurations.rb', line 63

def self.register_db_config_handler(&block)
  db_config_handlers << block
end

Instance Method Details

#configs_for(env_name: nil, name: nil, config_key: nil, include_hidden: false) ⇒ Object

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.


100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'activerecord/lib/active_record/database_configurations.rb', line 100

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

#empty? ⇒ Boolean Also known as: blank?

Checks if the application's configurations are empty.

Returns:

  • (Boolean) 


152
153
154
 
# File 'activerecord/lib/active_record/database_configurations.rb', line 152

def empty?
  configurations.empty?
end

#find_db_config(env) ⇒ Object

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.



129
130
131
132
133
134
135
136
 
# File 'activerecord/lib/active_record/database_configurations.rb', line 129

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

#primary?(name) ⇒ Boolean

A primary configuration is one that is named primary or if there is no primary, the first configuration for an environment will be treated as primary. This is used as the "default" configuration and is used when the application needs to treat one configuration differently. For example, when Rails dumps the schema, the primary configuration's schema file will be named schema.rb instead of primary_schema.rb.

Returns:

  • (Boolean) 


144
145
146
147
148
149
 
# File 'activerecord/lib/active_record/database_configurations.rb', line 144

def primary?(name) # :nodoc:
  return true if name == "primary"

  first_config = find_db_config(default_env)
  first_config && name == first_config.name
end

#resolve(config) ⇒ Object

Returns fully resolved connection, accepts hash, string or symbol. Always returns a DatabaseConfiguration::DatabaseConfig

Examples

Symbol representing current environment.

DatabaseConfigurations.new("production" => {}).resolve(:production)
# => DatabaseConfigurations::HashConfig.new(env_name: "production", config: {})

One layer deep hash of connection values.

DatabaseConfigurations.new({}).resolve("adapter" => "sqlite3")
# => DatabaseConfigurations::HashConfig.new(config: {"adapter" => "sqlite3"})

Connection URL.

DatabaseConfigurations.new({}).resolve("postgresql://localhost/foo")
# => DatabaseConfigurations::UrlConfig.new(config: {"adapter" => "postgresql", "host" => "localhost", "database" => "foo"})


176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'activerecord/lib/active_record/database_configurations.rb', line 176

def resolve(config) # :nodoc:
  return config if DatabaseConfigurations::DatabaseConfig === config

  case config
  when Symbol
    resolve_symbol_connection(config)
  when Hash, String
    build_db_config_from_raw_config(default_env, "primary", config)
  else
    raise TypeError, "Invalid type for configuration. Expected Symbol, String, or Hash. Got #{config.inspect}"
  end
end