Merge pull request #8222 from kenjis/docs-db-migration

docs: [Migration] clarify that `$db` is for testing purposes

Author: kenjis

system/Database/MigrationRunner.php

@@ -122,14 +122,11 @@ class MigrationRunner
     protected $groupSkip = false;
 
     /**
-     * Constructor.
+     * The migration can manage multiple databases. So it should always use the
+     * default DB group so that it creates the `migrations` table in the default
+     * DB group. Therefore, passing $db is for testing purposes only.
      *
-     * When passing in $db, you may pass any of the following to connect:
-     * - group name
-     * - existing connection instance
-     * - array of database configuration values
-     *
-     * @param array|ConnectionInterface|string|null $db
+     * @param array|ConnectionInterface|string|null $db DB group. For testing purposes only.
      *
      * @throws ConfigException
      */

user_guide_src/source/dbmgmt/migration.rst

@@ -66,7 +66,7 @@ Database Groups
 ===============
 
 A migration will only be run against a single database group. If you have multiple groups defined in
-**app/Config/Database.php**, then it will run against the ``$defaultGroup`` as specified
+**app/Config/Database.php**, then by default it will run against the ``$defaultGroup`` as specified
 in that same configuration file.
 
 There may be times when you need different schemas for different
@@ -79,6 +79,9 @@ match the name of the database group exactly:
 
 .. literalinclude:: migration/003.php
 
+.. note:: The **migrations** table that tracks which migrations have already been
+    run will be always created in the default database group.
+
 Namespaces
 ==========