class ActiveRecord::DatabaseConfigurations
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.
Attributes
Public Class Methods
Source
# File lib/active_record/database_configurations.rb, line 73 def initialize(configurations = {}) @configurations = build_configs(configurations) end
Source
# File lib/active_record/database_configurations.rb, line 61 def self.register_db_config_handler(&block) db_config_handlers << block end
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
.
Public Instance Methods
Source
# File 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
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 tonil
which will collect configs for all environments. -
name:
The db config name (i.e. primary, animals, etc.). Defaults tonil
. If noenv_name
is specified the config for the default env and the passedname
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 bydatabase_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 tofalse
.
Source
# File lib/active_record/database_configurations.rb, line 150 def empty? configurations.empty? end
Checks if the application’s configurations are empty.
Source
# File 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
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.
Private Instance Methods
Source
# File lib/active_record/database_configurations.rb, line 200 def build_configs(configs) return configs.configurations if configs.is_a?(DatabaseConfigurations) return configs if configs.is_a?(Array) db_configs = configs.flat_map do |env_name, config| if config.is_a?(Hash) && config.values.all?(Hash) walk_configs(env_name.to_s, config) else build_db_config_from_raw_config(env_name.to_s, "primary", config) end end unless db_configs.find(&:for_current_env?) db_configs << environment_url_config(default_env, "primary", {}) end merge_db_environment_variables(default_env, db_configs.compact) end
Source
# File lib/active_record/database_configurations.rb, line 239 def build_configuration_sentence configs = configs_for(include_hidden: true) configs.group_by(&:env_name).map do |env, config| names = config.map(&:name) if names.size > 1 "#{env}: #{names.join(", ")}" else env end end.join("\n") end
Source
# File lib/active_record/database_configurations.rb, line 273 def build_db_config_from_hash(env_name, name, config) url = config[:url] config_without_url = config.dup config_without_url.delete :url DatabaseConfigurations.db_config_handlers.reverse_each do |handler| config = handler.call(env_name, name, url, config_without_url) return config if config end nil end
Source
# File lib/active_record/database_configurations.rb, line 252 def build_db_config_from_raw_config(env_name, name, config) case config when String build_db_config_from_string(env_name, name, config) when Hash build_db_config_from_hash(env_name, name, config.symbolize_keys) else raise InvalidConfigurationError, "'{ #{env_name} => #{config} }' is not a valid configuration. Expected '#{config}' to be a URL string or a Hash." end end
Source
# File lib/active_record/database_configurations.rb, line 263 def build_db_config_from_string(env_name, name, config) url = config uri = URI.parse(url) if uri.scheme UrlConfig.new(env_name, name, url) else raise InvalidConfigurationError, "'{ #{env_name} => #{config} }' is not a valid configuration. Expected '#{config}' to be a URL string or a Hash." end end
Source
# File lib/active_record/database_configurations.rb, line 188 def default_env ActiveRecord::ConnectionHandling::DEFAULT_ENV.call.to_s end
Source
# File lib/active_record/database_configurations.rb, line 192 def env_with_configs(env = nil) if env configurations.select { |db_config| db_config.env_name == env } else configurations end end
Source
# File lib/active_record/database_configurations.rb, line 295 def environment_url_config(env, name, config) url = environment_value_for(name) return unless url UrlConfig.new(env, name, url, config) end
Source
# File lib/active_record/database_configurations.rb, line 302 def environment_value_for(name) name_env_key = "#{name.upcase}_DATABASE_URL" url = ENV[name_env_key] url ||= ENV["DATABASE_URL"] if name == "primary" url end
Source
# File lib/active_record/database_configurations.rb, line 286 def merge_db_environment_variables(current_env, configs) configs.map do |config| next config if config.is_a?(UrlConfig) || config.env_name != current_env url_config = environment_url_config(current_env, config.name, config.configuration_hash) url_config || config end end
Source
# File lib/active_record/database_configurations.rb, line 225 def resolve_symbol_connection(name) if db_config = find_db_config(name) db_config else raise AdapterNotSpecified, <<~MSG The `#{name}` database is not configured for the `#{default_env}` environment. Available database configurations are: #{build_configuration_sentence} MSG end end
Source
# File lib/active_record/database_configurations.rb, line 219 def walk_configs(env_name, config) config.map do |name, sub_config| build_db_config_from_raw_config(env_name, name.to_s, sub_config) end end