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.

1 files changed, 117 insertions, 0 deletions

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