Merge pull request #7552 from cakephp/update-readwrite

Update migration docs for read/write connection roles

en/appendices/4-5-migration-guide.rst

@@ -97,16 +97,11 @@ New Features
 Database
 --------
 
-- ``ConnectionManager`` now supports read and role connection roles. Roles are determined by
-  the datasource/config name. A read role always has a ":read" suffix and a write role does not.
-- ``ConnectionManager::get()`` now has ``$role`` parameter to find the connection for a role. You
-  can pass any connection name in to find the read or write connection for it.
+- ``ConnectionManager`` now supports read and role connection roles. Roles can be configured
+  with ``read`` and ``write`` keys in the connection config that override the shared config.
 - ``ConnectionManager::aliases()`` was added.
-- ``Query::useRole()``, ``Query::useReadRole()``, and ``Query::useWriteRole()`` were added to let you
-  switch a query to a specific connection role. This immediately changes the current connection if
-  the current connection role does not match.
-- ``Conection::role()`` was added to return the role of the connection.
-- New query subclasses, and query methods added to ``Table``.
+- ``SelectQuery::useConnectionRole()``, ``SelectQuery::useReadRole()``, and ``SelectQuery::useWriteRole()``
+  were added to let you switch a query to a specific connection role.
 
 Error
 -----

en/orm/database-basics.rst

@@ -262,17 +262,32 @@ pastry\_stores, and savory\_cakes.
 Read and Write Connections
 ==========================
 
-Connections can have read and write roles based on naming conventions. Read
+Connections can have separate read and write roles. Read
 roles are expected to represent read-only replicas and write roles are expected
 to be the default connection and support write operations.
 
-Connections should always have a write role configured. Passing a read-only config
-to ``ConfigurationManager::setConfig()`` without a matching write connection will
-throw an exception.
+Read roles are configured by providing a ``read`` key in the connection config.
+Write roles are configured by providing a ``write`` key.
+
+Role configurations override the values in the shared connection config. If the read
+and write role configurations are the same, a single connection to the database is used
+for both::
+
+    'default' => [
+        'driver' => 'mysql',
+        'username' => '...',
+        'password' => '...',
+        'database' => '...',
+        'read' => [
+            'host' => 'read-db.example.com',
+        ],
+        'read' => [
+            'host' => 'write-db.example.com',
+        ]
+    ];
 
-Read-only roles have a ``:read`` suffix in their name. Write roles are any connection
-without the ``:read`` suffix. ``ConnectionManager::get()`` accepts a role parameter
-to perform the look up based on name and role.
+You can specify the same value for both ``read`` and ``write`` key without creating
+multiple connections to the database.
 
 .. versionadded:: 4.5.0
     Read and write connection roles were added.
@@ -304,20 +319,6 @@ existing known connection::
 
 Attempting to load connections that do not exist will throw an exception.
 
-You can pass "read" or "write" as the ``$role`` when you want to look up
-the correct connection for that role regardless of the connection name::
-
-    use Cake\Database\Connection;
-    use Cake\Datasource\ConnectionManager;
-
-    $readConnection = ConnectionManager::get('default', true, Connection::READ_ROLE);
-
-If there isn't a read-only connection configured, the write connection will be
-returned instead.
-
-.. versionadded:: 4.5.0
-    Read and write connection roles were added.
-
 Creating Connections at Runtime
 -------------------------------