trait RefreshDatabase

Traits

Provides per-worker database isolation for parallel testing.

Methods

array
migrateFreshUsing()

The parameters that should be used when running "migrate:fresh".

bool
shouldDropViews()

Determine if views should be dropped when refreshing the database.

bool
shouldDropTypes()

Determine if types should be dropped when refreshing the database.

bool
shouldSeed()

Determine if the seed task should be run when refreshing the database.

mixed
seeder()

Determine the specific seeder class that should be used when refreshing the database.

void
configureParallelDatabaseName(mixed $app)

Rewrite the default connection's database name for parallel testing.

void
ensureParallelDatabaseExists()

Ensure the per-worker database exists, creating it if needed.

bool
shouldManageParallelDatabase(mixed $driver, string $database)

Determine if the database should be managed for parallel testing.

string
parallelTestDatabase(string $database, string $token)

Get the per-worker test database name.

void
refreshDatabase()

Define hooks to migrate the database before and after each test.

void
restoreInMemoryDatabase()

Restore the in-memory database between tests.

bool
usingInMemoryDatabases()

Determine if any of the connections transacting is using in-memory databases.

bool
usingInMemoryDatabase(string|null $name = null)

Determine if a given database connection is an in-memory database.

void
refreshTestDatabase()

Refresh a conventional test database.

bool
hasMissingInMemoryDatabaseForRefresh()

Determine if a transacting in-memory database is missing its cached PDO.

void
updateLocalCacheOfInMemoryDatabases()

Update locally cached in-memory PDO connections after migration.

void
migrateDatabases()

Migrate the database.

void
setUpRefreshDatabaseInCoroutine()

Start database transaction in the test coroutine.

void
tearDownRefreshDatabaseInCoroutine()

Rollback database transaction in the test coroutine.

void
beginDatabaseTransactionWork()

Start transactions on all connections.

void
rollbackDatabaseTransactionWork()

Rollback transactions on all connections.

array
connectionsToTransact()

The database connections that should have transactions.

void
beforeRefreshingDatabase()

Perform any work that should take place before the database has started refreshing.

void
afterRefreshingDatabase()

Perform any work that should take place once the database has finished refreshing.

string
getRefreshConnection()

Get the default database connection name.

Details

protected array migrateFreshUsing()

The parameters that should be used when running "migrate:fresh".

Return Value

array

protected bool shouldDropViews()

Determine if views should be dropped when refreshing the database.

Return Value

bool

protected bool shouldDropTypes()

Determine if types should be dropped when refreshing the database.

Return Value

bool

protected bool shouldSeed()

Determine if the seed task should be run when refreshing the database.

Return Value

bool

protected mixed seeder()

Determine the specific seeder class that should be used when refreshing the database.

Return Value

mixed

protected void configureParallelDatabaseName(mixed $app)

Rewrite the default connection's database name for parallel testing.

Config-only — does not create connections or purge pools. Called early in CreatesApplication (after config is loaded, before defineEnvironment) so that custom connections derived from the default connection inherit the per-worker database name.

No-op when not running in parallel or when using in-memory SQLite.

Parameters

mixed $app

Return Value

void

protected void ensureParallelDatabaseExists()

Ensure the per-worker database exists, creating it if needed.

Called before Testbench database requirements and from database testing traits (RefreshDatabase, DatabaseMigrations, DatabaseTruncation, DatabaseTransactions) after the app is booted and connections are available. The config has already been rewritten by configureParallelDatabaseName().

No-op when not running in parallel or when using in-memory SQLite.

Return Value

void

protected bool shouldManageParallelDatabase(mixed $driver, string $database)

Determine if the database should be managed for parallel testing.

Parameters

mixed $driver
string $database

Return Value

bool

protected string parallelTestDatabase(string $database, string $token)

Get the per-worker test database name.

Parameters

string $database
string $token

Return Value

string

at line 28
void refreshDatabase()

Define hooks to migrate the database before and after each test.

For tests using RunTestsInCoroutine, the transaction and post-refresh hooks are deferred to setUpRefreshDatabaseInCoroutine() to keep all transaction state in the same coroutine.

Return Value

void

at line 57
protected void restoreInMemoryDatabase()

Restore the in-memory database between tests.

Return Value

void

at line 81
protected bool usingInMemoryDatabases()

Determine if any of the connections transacting is using in-memory databases.

Return Value

bool

at line 95
protected bool usingInMemoryDatabase(string|null $name = null)

Determine if a given database connection is an in-memory database.

Parameters

string|null $name

Return Value

bool

at line 112
protected void refreshTestDatabase()

Refresh a conventional test database.

Runs migrations if needed. For non-coroutine tests, also starts the wrapper transaction. For coroutine tests, transaction handling is deferred to setUpRefreshDatabaseInCoroutine().

Return Value

void

at line 159
protected bool hasMissingInMemoryDatabaseForRefresh()

Determine if a transacting in-memory database is missing its cached PDO.

Return Value

bool

at line 178
protected void updateLocalCacheOfInMemoryDatabases()

Update locally cached in-memory PDO connections after migration.

Return Value

void

at line 202
protected void migrateDatabases()

Migrate the database.

Return Value

void

at line 217
protected void setUpRefreshDatabaseInCoroutine()

Start database transaction in the test coroutine.

Called by RunTestsInCoroutine before the test runs. Maintains correct ordering: transaction starts, then afterRefreshingDatabase runs, then test executes. This keeps all transaction state in the same coroutine.

Note: restoreInMemoryDatabase() runs earlier in refreshDatabase() before migrations, which is the correct ordering for in-memory SQLite.

Return Value

void

at line 228
protected void tearDownRefreshDatabaseInCoroutine()

Rollback database transaction in the test coroutine.

Called by RunTestsInCoroutine after the test runs.

Return Value

void

at line 236
protected void beginDatabaseTransactionWork()

Start transactions on all connections.

Return Value

void

at line 270
protected void rollbackDatabaseTransactionWork()

Rollback transactions on all connections.

Return Value

void

at line 301
protected array connectionsToTransact()

The database connections that should have transactions.

Return Value

array

at line 311
protected void beforeRefreshingDatabase()

Perform any work that should take place before the database has started refreshing.

Return Value

void

at line 319
protected void afterRefreshingDatabase()

Perform any work that should take place once the database has finished refreshing.

Return Value

void

at line 327
protected string getRefreshConnection()

Get the default database connection name.

Return Value

string