Solving SQLSTATE[HY000] [2002]: Database Connection Issues in Laravel Sail Environments

As a senior developer, I’ve seen countless times how frustrating environment-specific errors can be. When you are working with modern frameworks like Laravel and containerization tools like Laravel Sail, the complexity often shifts from application logic to infrastructure configuration—specifically, managing networking between your host machine and the Docker containers.

The error you are encountering, SQLSTATE[HY000] [2002] No such file or directory or Connection refused, when running commands like sail artisan migrate, is a classic symptom of a breakdown in the communication path to your database server inside the Docker environment. It rarely means the SQL itself is wrong; it almost always means the application container cannot find or reach the database service container.

Let’s dive deep into why this happens and how to fix it, moving beyond the common guesswork.

Understanding the Root Cause: Networking in Docker Compose

When you use Laravel Sail, you are relying on Docker Compose to spin up multiple services (PHP/Laravel application, MySQL/PostgreSQL database). The connection failure usually stems from one of three areas: incorrect service naming, volume mounting issues, or a timing problem during container startup.

The specific query failing—select * from information_schema.tables...—is the system checking metadata about the database. If this fails, it confirms that the PHP process inside the container cannot establish a valid connection to the database service defined in your docker-compose.yml.

Systematic Troubleshooting Steps

Since you have already tried changing DB_HOST and clearing caches, we need to look at the infrastructure layer. Here is a systematic approach:

1. Verify Service Naming in .env

The most common mistake is assuming the database hostname is always localhost or 127.0.0.1. Inside a Docker network, containers communicate using their service names defined in the docker-compose.yml file, not on the host machine's IP address.

Action: Check your docker-compose.yml file to see what the database service is named (e.g., mysql, pgsql). Your .env file should reference this name.

Example Correction:
If your database service is named mysql in docker-compose.yml, your .env file should look like this:

DB_CONNECTION=mysql
DB_HOST=mysql  # Use the service name defined in docker-compose.yml
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password

This configuration tells Laravel (and thus Sail) to connect to the service named mysql within the Docker network, ensuring successful communication between containers, which is a core principle of robust application architecture, much like what we strive for at laravelcompany.com.

2. Ensure Proper Volume Mounting and Permissions

If networking seems correct but the error persists, permissions related to file access or volume mounting can interfere. When dealing with data persistence (like migrations), ensure that the volumes are correctly mapped and accessible by both the host system and the container.

Action: If you are managing persistent data outside of Sail's default setup, review your Docker volumes (volumes: section) in docker-compose.yml. Ensure there are no conflicting permissions or misconfigured paths.

3. The Full Container Reset (The Nuclear Option)

You mentioned running ./vendor/bin/sail down --rmi all -v. This command is excellent for a clean slate, as it tears down the containers and removes associated volumes, forcing Docker to start everything fresh with a clean state. If this step failed previously, try running it again, ensuring you are in the root directory of your Laravel project before executing it.

Conclusion: Building Reliable Infrastructure

Database connection errors in containerized environments are fundamentally an infrastructure problem disguised as a code problem. By shifting your focus from application-level settings (DB_HOST=localhost) to infrastructure-level settings (service names in docker-compose and Docker networking), you resolve the issue efficiently.

Remember, successful deployment relies on predictable environment setup. Always treat your Docker Compose file as the single source of truth for how your services interact. By correctly configuring the service hostnames, you ensure that Laravel and Sail can reliably connect to their respective databases, allowing you to focus on writing brilliant business logic without infrastructure headaches.