Laravel 5 : Use different database for testing and local

Laravel 5 : Use different database for testing and local

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Decoupling Development and Testing Databases in Laravel

Practicing Test-Driven Development (TDD) often reveals a friction point that is easy to overlook but hard to live with: the inability to instantly switch between databases without modifying environment variables. In a typical local workflow, you might need a pristine database for running PHPUnit tests while preserving your development data for manual exploration. Manually editing the .env file every time you want to run a test suite breaks the flow and introduces human error.

Laravel provides a native mechanism to solve this without touching the .env file at runtime. The solution lies in understanding how the application environment is loaded and when configuration values are resolved.

Leveraging Environment Variables for Context Switching

The most straightforward approach relies on standard operating system environment variables rather than Laravel's APP_ENV setting alone. While APP_ENV dictates which configuration array is loaded, you can define specific database credentials that only apply to testing contexts by setting an external variable like TEST_DATABASE_URL.

However, a more robust pattern involves utilizing the APP_ENV variable itself to drive logic within your bootstrap sequence or configuration files. By default, Laravel loads the config/database.php file, but it does not automatically swap connection details based on APP_ENV unless you define those connections explicitly in that file.

To differentiate between normal development and testing, you should define multiple database connections within your config/database.php file. You can create a connection named development for your daily work and another named testing for your automated suites. The key is ensuring the application knows which one to use at startup without requiring manual .env edits during the test run.

You can achieve this by setting the APP_ENV variable in your shell session before invoking tests. For example, if your .env file contains:

APP_ENV=local
APP_KEY=base64:...
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=dev_db

You can run your test suite with a modified environment variable to point to the testing database:

export APP_ENV=test
export DB_DATABASE=test_db
php artisan test

This approach works because Laravel reads APP_ENV from the OS environment variables if they are not already defined in the .env file. This allows you to keep your .env static for development while dynamically injecting testing credentials via the command line or shell export commands.

Automating the Switch with Scripts

While manual exports work, they can be tedious. A common and cleaner implementation involves creating a dedicated test script, such as run-tests.sh, that sets up the environment automatically.

In this script, you would define the testing database credentials and set APP_ENV to test. This ensures that every time you execute the script, the application loads the correct configuration context without requiring you to remember specific export commands.

#!/bin/bash
export APP_ENV=test
export DB_CONNECTION=mysql
export DB_HOST=127.0.0.1
export DB_DATABASE=test_db
export DB_USERNAME=root
export DB_PASSWORD=secret_test
php artisan test

This pattern is particularly useful for TDD workflows where rapid iteration depends on instant database resets and isolation. By keeping the development environment untouched, you ensure that manual debugging sessions do not interfere with test expectations.

Trade-offs and Considerations

When implementing this strategy, be mindful of migration strategies. If your tests rely on a clean slate, you will need to ensure that migrations are run against the testing database specifically. Laravel's --database option for artisan commands allows you to target specific connections, but relying solely on command-line flags can become messy if not managed consistently.

Additionally, consider whether your application relies heavily on global state or cached configurations that might persist across environment switches. While Laravel caches configuration in the bootstrap/cache directory, this is typically cleared when the application environment changes significantly or when you run cache clearing commands like php artisan config:clear.

Using separate databases also means managing data lifecycle separately. You may need to ensure that your testing database schema matches your development schema exactly, including custom seeds or complex relationships. If your tests assume a specific structure that differs from your dev environment, the separation might introduce configuration drift issues.

For teams managing multiple environments, this approach scales well as long as the distinction between dev and test is strictly enforced in CI/CD pipelines. Tools like Laravel Company often highlight best practices for managing multi-environment deployments, emphasizing the importance of keeping environment-specific configurations isolated to prevent accidental data leakage or test pollution.

Ultimately, the goal is to reduce cognitive load during testing. By automating the switch between databases, you reclaim time previously spent editing files and focus on writing better tests rather than configuring your environment.

Our network