Improve errors and handling of hashes for database configurations

In chat Sam Saffron asked how to use the setter now that configurations
is no longer a hash and you need to do AR::Base.configurations["test"]=.

Technically you can do `ActiveRecord::Base.configurations = { the hash
}` but I realized the old way throws an error and is unintuitive.

To aid in the transition from hashes to objects this PR makes a few
changes:

1) Re-adds a deprecated hash setter `[]=` that will add a new hash
to the configurations list OR replace an existing hash if that
environment is already present. This won't be supported in future Rails
versions but a good error is important.

2) Changed to throw deprecation warnings on the methods we decided to support
for hash conversion and raise on the methods we don't support.

3) Refactored the setter/getter hash deprecation warnings messages and
rewrote them.

Getters message:

```
DEPRECATION WARNING: `ActiveRecord::Base.configurations` no longer
returns a hash. Methods that act on the hash like `values` are
deprecated and will be removed in Rails 6.1. Use the `configs_for`
method to collect and iterate over the database configurations.
```

Setter message:

```
DEPRECATION WARNING: Setting `ActiveRecord::Base.configurations` with
`[]=` is deprecated. Use `ActiveRecord::Base.configurations=` directly
to set the configurations instead.
```

4) Rewrote the legacy configurations test file to test all the public
methods in the DatabaseConfigurations class.

3 files changed, 141 insertions, 49 deletions

diff --git a/activerecord/lib/active_record/database_configurations.rb b/activerecord/lib/active_record/database_configurations.rb
index 73adf66684..c36b87829e 100644
--- a/activerecord/lib/active_record/database_configurations.rb
+++ b/activerecord/lib/active_record/database_configurations.rb
@@ -102,6 +102,7 @@ module ActiveRecord
 
       def build_configs(configs)
         return configs.configurations if configs.is_a?(DatabaseConfigurations)
+        return configs if configs.is_a?(Array)
 
         build_db_config = configs.each_pair.flat_map do |env_name, config|
           walk_configs(env_name.to_s, "primary", config)
@@ -166,21 +167,38 @@ module ActiveRecord
       end
 
       def method_missing(method, *args, &blk)
-        if Hash.method_defined?(method)
-          ActiveSupport::Deprecation.warn \
-            "Returning a hash from ActiveRecord::Base.configurations is deprecated. Therefore calling `#{method}` on the hash is also deprecated. Please switch to using the `configs_for` method instead to collect and iterate over database configurations."
-        end
-
         case method
         when :each, :first
+          throw_getter_deprecation(method)
           configurations.send(method, *args, &blk)
         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
-          super
+          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
diff --git a/activerecord/test/cases/database_configurations_test.rb b/activerecord/test/cases/database_configurations_test.rb
new file mode 100644
index 0000000000..ed8151f01a
--- /dev/null
+++ b/activerecord/test/cases/database_configurations_test.rb
@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "cases/helper"
+
+class DatabaseConfigurationsTest < ActiveRecord::TestCase
+  unless in_memory_db?
+    def test_empty_returns_true_when_db_configs_are_empty
+      old_config = ActiveRecord::Base.configurations
+      config = {}
+
+      ActiveRecord::Base.configurations = config
+
+      assert_predicate ActiveRecord::Base.configurations, :empty?
+      assert_predicate ActiveRecord::Base.configurations, :blank?
+    ensure
+      ActiveRecord::Base.configurations = old_config
+      ActiveRecord::Base.establish_connection :arunit
+    end
+  end
+
+  def test_configs_for_getter_with_env_name
+    configs = ActiveRecord::Base.configurations.configs_for(env_name: "arunit")
+
+    assert_equal 1, configs.size
+    assert_equal ["arunit"], configs.map(&:env_name)
+  end
+
+  def test_configs_for_getter_with_env_and_spec_name
+    config = ActiveRecord::Base.configurations.configs_for(env_name: "arunit", spec_name: "primary")
+
+    assert_equal "arunit", config.env_name
+    assert_equal "primary", config.spec_name
+  end
+
+  def test_default_hash_returns_config_hash_from_default_env
+    original_rails_env = ENV["RAILS_ENV"]
+    ENV["RAILS_ENV"] = "arunit"
+
+    assert_equal ActiveRecord::Base.configurations.configs_for(env_name: "arunit", spec_name: "primary").config, ActiveRecord::Base.configurations.default_hash
+  ensure
+    ENV["RAILS_ENV"] = original_rails_env
+  end
+
+  def test_find_db_config_returns_a_db_config_object_for_the_given_env
+    config = ActiveRecord::Base.configurations.find_db_config("arunit2")
+
+    assert_equal "arunit2", config.env_name
+    assert_equal "primary", config.spec_name
+  end
+
+  def test_to_h_turns_db_config_object_back_into_a_hash
+    configs = ActiveRecord::Base.configurations
+    assert_equal "ActiveRecord::DatabaseConfigurations", configs.class.name
+    assert_equal "Hash", configs.to_h.class.name
+    assert_equal ["arunit", "arunit2", "arunit_without_prepared_statements"], ActiveRecord::Base.configurations.to_h.keys.sort
+  end
+end
+
+class LegacyDatabaseConfigurationsTest < ActiveRecord::TestCase
+  unless in_memory_db?
+    def test_setting_configurations_hash
+      old_config = ActiveRecord::Base.configurations
+      config = { "adapter" => "sqlite3" }
+
+      assert_deprecated do
+        ActiveRecord::Base.configurations["readonly"] = config
+      end
+
+      assert_equal ["arunit", "arunit2", "arunit_without_prepared_statements", "readonly"], ActiveRecord::Base.configurations.configs_for.map(&:env_name).sort
+    ensure
+      ActiveRecord::Base.configurations = old_config
+      ActiveRecord::Base.establish_connection :arunit
+    end
+  end
+
+  def test_can_turn_configurations_into_a_hash
+    assert ActiveRecord::Base.configurations.to_h.is_a?(Hash), "expected to be a hash but was not."
+    assert_equal ["arunit", "arunit2", "arunit_without_prepared_statements"].sort, ActiveRecord::Base.configurations.to_h.keys.sort
+  end
+
+  def test_each_is_deprecated
+    assert_deprecated do
+      ActiveRecord::Base.configurations.each do |db_config|
+        assert_equal "primary", db_config.spec_name
+      end
+    end
+  end
+
+  def test_first_is_deprecated
+    assert_deprecated do
+      db_config = ActiveRecord::Base.configurations.first
+      assert_equal "arunit", db_config.env_name
+      assert_equal "primary", db_config.spec_name
+    end
+  end
+
+  def test_fetch_is_deprecated
+    assert_deprecated do
+      db_config = ActiveRecord::Base.configurations.fetch("arunit").first
+      assert_equal "arunit", db_config.env_name
+      assert_equal "primary", db_config.spec_name
+    end
+  end
+
+  def test_values_are_deprecated
+    config_hashes = ActiveRecord::Base.configurations.configurations.map(&:config)
+    assert_deprecated do
+      assert_equal config_hashes, ActiveRecord::Base.configurations.values
+    end
+  end
+
+  def test_unsupported_method_raises
+    assert_raises NotImplementedError do
+      ActiveRecord::Base.configurations.select { |a| a == "foo" }
+    end
+  end
+end
diff --git a/activerecord/test/cases/legacy_configurations_test.rb b/activerecord/test/cases/legacy_configurations_test.rb
deleted file mode 100644
index c36feb5116..0000000000
--- a/activerecord/test/cases/legacy_configurations_test.rb
+++ /dev/null
@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-require "cases/helper"
-
-module ActiveRecord
-  class LegacyConfigurationsTest < ActiveRecord::TestCase
-    def test_can_turn_configurations_into_a_hash
-      assert ActiveRecord::Base.configurations.to_h.is_a?(Hash), "expected to be a hash but was not."
-      assert_equal ["arunit", "arunit2", "arunit_without_prepared_statements"].sort, ActiveRecord::Base.configurations.to_h.keys.sort
-    end
-
-    def test_each_is_deprecated
-      assert_deprecated do
-        ActiveRecord::Base.configurations.each do |db_config|
-          assert_equal "primary", db_config.spec_name
-        end
-      end
-    end
-
-    def test_first_is_deprecated
-      assert_deprecated do
-        db_config = ActiveRecord::Base.configurations.first
-        assert_equal "arunit", db_config.env_name
-        assert_equal "primary", db_config.spec_name
-      end
-    end
-
-    def test_fetch_is_deprecated
-      assert_deprecated do
-        db_config = ActiveRecord::Base.configurations.fetch("arunit").first
-        assert_equal "arunit", db_config.env_name
-        assert_equal "primary", db_config.spec_name
-      end
-    end
-
-    def test_values_are_deprecated
-      config_hashes = ActiveRecord::Base.configurations.configurations.map(&:config)
-      assert_deprecated do
-        assert_equal config_hashes, ActiveRecord::Base.configurations.values
-      end
-    end
-  end
-end