Unexpected Behavior of afterCommit With Multiple Database Connections

[MannikJ]

I encountered unexpected errors after adding another database connection to $connectionsToTransact with RefreshDatabase. Through testing and reading related issues, it appears that Laravel’s afterCommit handling still doesn’t fully support multi-database setups.

Look at this example test case:

<?php

namespace Tests\Feature;

use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\DB;
use Tests\TestCase;

class RefreshDatabaseWithMultipleConnectionsTest extends TestCase
{
    protected array $connectionsToTransact = [null, 'other_connection'];

    use RefreshDatabase;

    public function test_with_nested_transaction_on_default_connection(): void
    {
        $executed = false;

        DB::transaction(function () use (&$executed) {
            DB::afterCommit(function () use (&$executed) {
                $executed = true;
            });
        });

        $this->assertTrue($executed); // SUCCEEDS!
    }

    public function test_without_nested_transaction_on_default_connection(): void
    {
        $executed = false;

        DB::afterCommit(function () use (&$executed) {
            $executed = true;
        });
        
        $this->assertTrue($executed); // FAILS!
    }
}

The reason lies in the Illuminate\Foundation\Testing\DatabaseTransactionManager, which skips root transactions when adding callbacks:

public function callbackApplicableTransactions() {
    return $this->pendingTransactions->skip(1)->values();
}

With multiple connections, this logic only skips the root transaction for the default connection and mistakenly attaches the callback to the root transaction of the secondary connection. This behavior is functional with single databases but fails to handle multiple connections correctly, as the uncommitted secondary transaction prevents afterCommit from executing.

The dedicated DatabaseTransactionManager for testing was introduced not a long time ago by #48523 to fix issues with nested connections and and was seen as a fix for issue #48472, which reported that afterCommit callbacks were not executed in tests with RefreshDatabase and multiple database connections added to $connectionsToTransact.
I borrowed the first example test from this issue. So before the mentioned PR was merged, the first example test wasn't working either.
However, it seems inconsistent that the first test now passes, but the second fails, especially given that removing other_connection from $transactionsToTransact will make it pass.

Suggested Improvements:

1. Enhanced Skipping Logic: Skip all root transactions across active connections, allowing correct callback handling in multi-database environments.

2. Connection-Specific Callbacks: DB::afterCommit() could let users specify targeted connections, making DB::transaction() and DB::afterCommit() work as expected with the default connection while preserving control over additional connections.

These changes would align afterCommit behavior more intuitively with multi-database use cases.

I would consider 1. as mandatory, since the current skipping logic is not sufficiently respecting multi database connection setups, 2. would be a nice improvement.

[tonysm]

I've created a PR that aims to fix this: #53377