Merge pull request #33637 from eileencodes/ar-connection-management-refactoring

Refactor Active Record configurations

1 files changed, 47 insertions, 0 deletions

diff --git a/activerecord/CHANGELOG.md b/activerecord/CHANGELOG.md
index 71dcecd346..a7c2680015 100644
--- a/activerecord/CHANGELOG.md
+++ b/activerecord/CHANGELOG.md
@@ -1,3 +1,50 @@
+*   ActiveRecord::Base.configurations now returns an object.
+
+    ActiveRecord::Base.configurations used to return a hash, but this
+    is an inflexible data model. In order to improve multiple-database
+    handling in Rails, we've changed this to return an object. Some methods
+    are provided to make the object behave hash-like in order to ease the
+    transition process. Since most applications don't manipulate the hash
+    we've decided to add backwards-compatible functionality that will throw
+    a deprecation warning if used, however calling `ActiveRecord::Base.configurations`
+    will use the new version internally and externally.
+
+    For example, the following database.yml...
+
+    ```
+    development:
+      adapter: sqlite3
+      database: db/development.sqlite3
+    ```
+
+    Used to become a hash:
+
+    ```
+    { "development" => { "adapter" => "sqlite3", "database" => "db/development.sqlite3" } }
+    ```
+
+    Is now converted into the following object:
+
+    ```
+    #<ActiveRecord::DatabaseConfigurations:0x00007fd1acbdf800 @configurations=[
+      #<ActiveRecord::DatabaseConfigurations::HashConfig:0x00007fd1acbded10 @env_name="development",
+        @spec_name="primary", @config={"adapter"=>"sqlite3", "database"=>"db/development.sqlite3"}>
+      ]
+    ```
+
+    Iterating over the database configurations has also changed. Instead of
+    calling hash methods on the `configurations` hash directly, a new method `configs_for` has
+    been provided that allows you to select the correct configuration. `env_name` is a required
+    argument, `spec_name` is optional as well as passing a block. These return an array of
+    database config objects for the requested environment and specification name respectively.
+
+    ```
+    ActiveRecord::Base.configurations.configs_for("development")
+    ActiveRecord::Base.configurations.configs_for("development", "primary")
+    ```
+
+    *Eileen M. Uchitelle*, *Aaron Patterson*
+
 *   Add database configuration to disable advisory locks.
 
     ```