Migrator checks ran/pending migrations ignoring the $connection property

[stebogit]

Laravel Version

9.x

PHP Version

8.1

Database Driver & Version

MySQL 8

Description

Ref: #41153

According to the documentation the $connection property allows you to make changes to a non default database; alternatively you can run the migrate command with --database option to achieve the same result. According to #41161 the $connection property on the migration class has precedence over the --database option.

However when using the $connection property the migrate command checks/updates the migrations table on the default database/connection, whereas the --database option also instructs the command to use the migrations table on that same database.

As I understand it, the migrations table tracks changes made to the database they belong to, therefore I'd expect the $connection property to define also the "location" of the migrations table.
If instead the table is supposed to represent changes to any database the app interacts with, I'd suggest mentioning that in the documentation.

Steps To Reproduce

return new class extends Migration
{
    protected $connection = 'mydb';

    public function up()
    {
        // create `my_table`
    }
}

$ php artisan migrate

   INFO  Running migrations.  

  2023_04_15_163710_create_table ..................... 68ms DONE

$ php artisan migrate --database=mydb

   INFO  Preparing database.  

  Creating migration table ........................... 28ms DONE

   INFO  Running migrations.  

  2023_04_15_163710_create_table ..................... 45ms DONE

[nunomaduro]

@stebogit Thank you for creating this issue. After investigating this issue, keep in mind that is expected those two runs you specified to have different results. As, defining--database=mydb is not the same thing as having one migration with $connection = 'mydb'; .

When you use the --database=mydb option, you are indicating that all migrations without a $connection specified should be executed on the mydb database. This includes the creation of the "migrations" table.

The purpose of the "migrations" table is to keep track of changes made to any database the application interacts with. Therefore, if you believe that this information is not sufficiently clear, I encourage you to submit a pull request to the documentation to provide further clarification. Thank you for your understanding and contribution!