activerecord 6.0.0 → 7.2.3

data/lib/active_record/database_configurations/url_config.rb

@@ -2,7 +2,9 @@
 
 module ActiveRecord
   class DatabaseConfigurations
-    # A UrlConfig object is created for each database configuration
+    # = Active Record Database Url Config
+    #
+    # A +UrlConfig+ object is created for each database configuration
     # entry that is created from a URL. This can either be a URL string
     # or a hash with a URL in place of the config hash.
     #
@@ -13,65 +15,62 @@ module ActiveRecord
     # Becomes:
     #
     #   #<ActiveRecord::DatabaseConfigurations::UrlConfig:0x00007fdc3238f340
-    #     @env_name="default_env", @spec_name="primary",
-    #     @config={"adapter"=>"postgresql", "database"=>"foo", "host"=>"localhost"},
+    #     @env_name="default_env", @name="primary",
+    #     @config={adapter: "postgresql", database: "foo", host: "localhost"},
     #     @url="postgres://localhost/foo">
     #
-    # ==== Options
+    # See ActiveRecord::DatabaseConfigurations for more info.
     #
-    # * <tt>:env_name</tt> - The Rails environment, ie "development".
-    # * <tt>:spec_name</tt> - The specification name. In a standard two-tier
-    #   database configuration this will default to "primary". In a multiple
-    #   database three-tier database configuration this corresponds to the name
-    #   used in the second tier, for example "primary_readonly".
-    # * <tt>:url</tt> - The database URL.
-    # * <tt>:config</tt> - The config hash. This is the hash that contains the
-    #   database adapter, name, and other important information for database
-    #   connections.
-    class UrlConfig < DatabaseConfig
-      attr_reader :url, :config
+    class UrlConfig < HashConfig
+      attr_reader :url
+
+      # Initialize a new +UrlConfig+ object
+      #
+      # ==== Options
+      #
+      # * <tt>:env_name</tt> - The \Rails environment, i.e. "development".
+      # * <tt>:name</tt> - The db config name. In a standard two-tier
+      #   database configuration this will default to "primary". In a multiple
+      #   database three-tier database configuration this corresponds to the name
+      #   used in the second tier, for example "primary_readonly".
+      # * <tt>:url</tt> - The database URL.
+      # * <tt>:config</tt> - The config hash. This is the hash that contains the
+      #   database adapter, name, and other important information for database
+      #   connections.
+      def initialize(env_name, name, url, configuration_hash = {})
+        super(env_name, name, configuration_hash)
 
-      def initialize(env_name, spec_name, url, config = {})
-        super(env_name, spec_name)
-        @config = build_config(config, url)
         @url = url
-      end
+        @configuration_hash = @configuration_hash.merge(build_url_hash)
 
-      def url_config? # :nodoc:
-        true
-      end
+        if @configuration_hash[:schema_dump] == "false"
+          @configuration_hash[:schema_dump] = false
+        end
 
-      # Determines whether a database configuration is for a replica / readonly
-      # connection. If the +replica+ key is present in the config, +replica?+ will
-      # return +true+.
-      def replica?
-        config["replica"]
-      end
+        if @configuration_hash[:query_cache] == "false"
+          @configuration_hash[:query_cache] = false
+        end
+
+        to_boolean!(@configuration_hash, :replica)
+        to_boolean!(@configuration_hash, :database_tasks)
 
-      # The migrations paths for a database configuration. If the
-      # +migrations_paths+ key is present in the config, +migrations_paths+
-      # will return its value.
-      def migrations_paths
-        config["migrations_paths"]
+        @configuration_hash.freeze
       end
 
       private
-
-        def build_url_hash(url)
-          if url.nil? || /^jdbc:/.match?(url)
-            { "url" => url }
-          else
-            ActiveRecord::ConnectionAdapters::ConnectionSpecification::ConnectionUrlResolver.new(url).to_hash
+        def to_boolean!(configuration_hash, key)
+          if configuration_hash[key].is_a?(String)
+            configuration_hash[key] = configuration_hash[key] != "false"
           end
         end
 
-        def build_config(original_config, url)
-          hash = build_url_hash(url)
-
-          if original_config[env_name]
-            original_config[env_name].merge(hash)
+        # Return a Hash that can be merged into the main config that represents
+        # the passed in url
+        def build_url_hash
+          if url.nil? || url.start_with?("jdbc:", "http:", "https:")
+            { url: url }
           else
-            original_config.merge(hash)
+            ConnectionUrlResolver.new(url).to_hash
           end
         end
     end

data/lib/active_record/database_configurations.rb

@@ -1,112 +1,194 @@
 # frozen_string_literal: true
 
+require "uri"
 require "active_record/database_configurations/database_config"
 require "active_record/database_configurations/hash_config"
 require "active_record/database_configurations/url_config"
+require "active_record/database_configurations/connection_url_resolver"
 
 module ActiveRecord
-  # ActiveRecord::DatabaseConfigurations returns an array of DatabaseConfig
-  # objects (either a HashConfig or UrlConfig) that are constructed from the
-  # application's database configuration hash or URL string.
+  # = 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.
   class DatabaseConfigurations
     class InvalidConfigurationError < StandardError; end
 
     attr_reader :configurations
     delegate :any?, to: :configurations
 
+    singleton_class.attr_accessor :db_config_handlers # :nodoc:
+    self.db_config_handlers = [] # :nodoc:
+
+    # 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+.
+    def self.register_db_config_handler(&block)
+      db_config_handlers << block
+    end
+
+    register_db_config_handler do |env_name, name, url, config|
+      if url
+        UrlConfig.new(env_name, name, url, config)
+      else
+        HashConfig.new(env_name, name, config)
+      end
+    end
+
     def initialize(configurations = {})
       @configurations = build_configs(configurations)
     end
 
     # Collects the configs for the environment and optionally the specification
-    # name passed in. To include replica configurations pass <tt>include_replicas: true</tt>.
+    # name passed in. To include replica configurations pass <tt>include_hidden: true</tt>.
     #
-    # If a spec name is provided a single DatabaseConfig object will be
-    # returned, otherwise an array of DatabaseConfig objects will be
+    # 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
     #
     # * <tt>env_name:</tt> The environment name. Defaults to +nil+ which will collect
     #   configs for all environments.
-    # * <tt>spec_name:</tt> The specification name (i.e. primary, animals, etc.). Defaults
-    #   to +nil+.
-    # * <tt>include_replicas:</tt> Determines whether to include replicas in
-    #   the returned list. Most of the time we're only iterating over the write
-    #   connection (i.e. migrations don't need to run for the write and read connection).
-    #   Defaults to +false+.
-    def configs_for(env_name: nil, spec_name: nil, include_replicas: false)
+    # * <tt>name:</tt> 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.
+    # * <tt>config_key:</tt> 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.
+    # * <tt>include_hidden:</tt> Determines whether to include replicas and configurations
+    #   hidden by <tt>database_tasks: false</tt> 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+.
+    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_replicas
+      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.replica?
+          db_config.configuration_hash.key?(config_key)
         end
       end
 
-      if spec_name
+      if name
         configs.find do |db_config|
-          db_config.spec_name == spec_name
+          db_config.name == name.to_s
         end
       else
         configs
       end
     end
 
-    # Returns the config hash that corresponds with the environment
-    #
-    # If the application has multiple databases +default_hash+ will
-    # return the first config hash for the environment.
-    #
-    #   { database: "my_db", adapter: "mysql2" }
-    def default_hash(env = ActiveRecord::ConnectionHandling::DEFAULT_ENV.call.to_s)
-      default = find_db_config(env)
-      default.config if default
-    end
-    alias :[] :default_hash
-
-    # Returns a single DatabaseConfig object based on the requested environment.
+    # 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.
+    # the first +DatabaseConfig+ for the environment.
     def find_db_config(env)
+      env = env.to_s
       configurations.find do |db_config|
-        db_config.env_name == env.to_s ||
-          (db_config.for_current_env? && db_config.spec_name == env.to_s)
+        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 the DatabaseConfigurations object as a Hash.
-    def to_h
-      configs = configurations.reverse.inject({}) do |memo, db_config|
-        memo.merge(db_config.to_legacy_hash)
-      end
-
-      Hash[configs.to_a.reverse]
+    # 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`.
+    def primary?(name) # :nodoc:
+      return true if name == "primary"
+
+      first_config = find_db_config(default_env)
+      first_config && name == first_config.name
     end
 
     # Checks if the application's configurations are empty.
-    #
-    # Aliased to blank?
     def empty?
       configurations.empty?
     end
     alias :blank? :empty?
 
-    def each
-      throw_getter_deprecation(:each)
-      configurations.each { |config|
-        yield [config.env_name, config.config]
-      }
-    end
-
-    def first
-      throw_getter_deprecation(:first)
-      config = configurations.first
-      [config.env_name, config.config]
+    # 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"})
+    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
 
     private
+      def default_env
+        ActiveRecord::ConnectionHandling::DEFAULT_ENV.call.to_s
+      end
+
       def env_with_configs(env = nil)
         if env
           configurations.select { |db_config| db_config.env_name == env }
@@ -120,114 +202,108 @@ module ActiveRecord
         return configs if configs.is_a?(Array)
 
         db_configs = configs.flat_map do |env_name, config|
-          if config.is_a?(Hash) && config.all? { |_, v| v.is_a?(Hash) }
+          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
 
-        current_env = ActiveRecord::ConnectionHandling::DEFAULT_ENV.call.to_s
-
         unless db_configs.find(&:for_current_env?)
-          db_configs << environment_url_config(current_env, "primary", {})
+          db_configs << environment_url_config(default_env, "primary", {})
         end
 
-        merge_db_environment_variables(current_env, db_configs.compact)
+        merge_db_environment_variables(default_env, db_configs.compact)
       end
 
       def walk_configs(env_name, config)
-        config.map do |spec_name, sub_config|
-          build_db_config_from_raw_config(env_name, spec_name.to_s, sub_config)
+        config.map do |name, sub_config|
+          build_db_config_from_raw_config(env_name, name.to_s, sub_config)
         end
       end
 
-      def build_db_config_from_raw_config(env_name, spec_name, config)
+      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
+
+      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
+
+      def build_db_config_from_raw_config(env_name, name, config)
         case config
         when String
-          build_db_config_from_string(env_name, spec_name, config)
+          build_db_config_from_string(env_name, name, config)
         when Hash
-          build_db_config_from_hash(env_name, spec_name, config.stringify_keys)
+          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
 
-      def build_db_config_from_string(env_name, spec_name, config)
+      def build_db_config_from_string(env_name, name, config)
         url = config
         uri = URI.parse(url)
         if uri.scheme
-          ActiveRecord::DatabaseConfigurations::UrlConfig.new(env_name, spec_name, url)
+          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
 
-      def build_db_config_from_hash(env_name, spec_name, config)
-        if config.has_key?("url")
-          url = config["url"]
-          config_without_url = config.dup
-          config_without_url.delete "url"
+      def build_db_config_from_hash(env_name, name, config)
+        url = config[:url]
+        config_without_url = config.dup
+        config_without_url.delete :url
 
-          ActiveRecord::DatabaseConfigurations::UrlConfig.new(env_name, spec_name, url, config_without_url)
-        else
-          ActiveRecord::DatabaseConfigurations::HashConfig.new(env_name, spec_name, config)
+        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
 
       def merge_db_environment_variables(current_env, configs)
         configs.map do |config|
-          next config if config.url_config? || config.env_name != current_env
+          next config if config.is_a?(UrlConfig) || config.env_name != current_env
 
-          url_config = environment_url_config(current_env, config.spec_name, config.config)
+          url_config = environment_url_config(current_env, config.name, config.configuration_hash)
           url_config || config
         end
       end
 
-      def environment_url_config(env, spec_name, config)
-        url = environment_value_for(spec_name)
+      def environment_url_config(env, name, config)
+        url = environment_value_for(name)
         return unless url
 
-        ActiveRecord::DatabaseConfigurations::UrlConfig.new(env, spec_name, url, config)
+        UrlConfig.new(env, name, url, config)
       end
 
-      def environment_value_for(spec_name)
-        spec_env_key = "#{spec_name.upcase}_DATABASE_URL"
-        url = ENV[spec_env_key]
-        url ||= ENV["DATABASE_URL"] if spec_name == "primary"
+      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
-
-      def method_missing(method, *args, &blk)
-        case method
-        when :fetch
-          throw_getter_deprecation(method)
-          configs_for(env_name: args.first)
-        when :values
-          throw_getter_deprecation(method)
-          configurations.map(&:config)
-        when :[]=
-          throw_setter_deprecation(method)
-
-          env_name = args[0]
-          config = args[1]
-
-          remaining_configs = configurations.reject { |db_config| db_config.env_name == env_name }
-          new_config = build_configs(env_name => config)
-          new_configs = remaining_configs + new_config
-
-          ActiveRecord::Base.configurations = new_configs
-        else
-          raise NotImplementedError, "`ActiveRecord::Base.configurations` in Rails 6 now returns an object instead of a hash. The `#{method}` method is not supported. Please use `configs_for` or consult the documentation for supported methods."
-        end
-      end
-
-      def throw_setter_deprecation(method)
-        ActiveSupport::Deprecation.warn("Setting `ActiveRecord::Base.configurations` with `#{method}` is deprecated. Use `ActiveRecord::Base.configurations=` directly to set the configurations instead.")
-      end
-
-      def throw_getter_deprecation(method)
-        ActiveSupport::Deprecation.warn("`ActiveRecord::Base.configurations` no longer returns a hash. Methods that act on the hash like `#{method}` are deprecated and will be removed in Rails 6.1. Use the `configs_for` method to collect and iterate over the database configurations.")
-      end
   end
 end