Diagnosis and Resolution of SQLSTATE[HY000] [2002] Connection Refused Error in Laravel Homestead

Problem Background and Error Phenomenon

In Laravel Homestead development environments, encountering the SQLSTATE[HY000] [2002] Connection refused error when executing the php artisan migrate command is a common issue. Users report experiencing this problem on Mac OS X systems using Homestead 2.2.1 and Laravel 5.2, where database connections succeed through management tools like Sequel Pro but fail with connection refusal when running migration commands in the terminal.

Core Problem Analysis

Through detailed analysis of the Q&A data, we identified that the root cause primarily lies in the completeness of database configuration files. In standard Laravel projects, the config/database.php file defines database connection parameters, while the .env file stores environment-specific variable values.

The critical issue emerges in the port configuration of the MySQL section. The default config/database.php file may lack port definition:

'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', 'localhost'),
    'database' => env('DB_DATABASE', 'forge'),
    'username' => env('DB_USERNAME', 'forge'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8',
    'collation' => 'utf8_unicode_ci',
    'prefix' => '',
    'strict' => false,
    'engine' => null,
],

As shown in the code above, the configuration indeed does not include port settings. This means that even if developers set DB_PORT=33060 in the .env file, this value will not be read into the actual database connection configuration.

Solution Implementation

To resolve this issue, port settings need to be added to the MySQL configuration in the config/database.php file:

'mysql' => [
    'driver' => 'mysql',
    'host' => env('DB_HOST', 'localhost'),
    'port' => env('DB_PORT', 3306),
    'database' => env('DB_DATABASE', 'forge'),
    'username' => env('DB_USERNAME', 'forge'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => 'utf8',
    'collation' => 'utf8_unicode_ci',
    'prefix' => '',
    'strict' => false,
    'engine' => null,
],

Simultaneously, ensure the correct port value is set in the .env file:

DB_PORT=33060

Supplementary Solutions

Beyond the port configuration issue, other answers and reference articles provide valuable supplementary solutions:

Host Address Configuration: In some cases, changing DB_HOST from 127.0.0.1 to localhost can resolve the issue. This occurs because different connection methods may resolve host addresses differently.

Configuration Cache Clearance: After modifying configurations, run the php artisan config:cache command to clear configuration cache and ensure new settings take effect.

MAMP Environment Special Handling: For development environments using MAMP, Unix socket configuration may be necessary:

'unix_socket' => env('DB_SOCKET', ''),

And set in the .env file:

DB_SOCKET=/Applications/MAMP/tmp/mysql/mysql.sock

Best Practice Recommendations

Based on thorough problem analysis, we recommend developers follow these best practices when configuring Laravel database connections:

Complete Configuration Check: When encountering database connection issues, first verify that the config/database.php file includes all necessary configuration items, particularly port and potential socket settings.

Environment Consistency: Ensure database configurations remain consistent across development, testing, and production environments to avoid connection problems due to environmental differences.

Configuration Validation: After modifying configurations, use the php artisan config:show command to verify that configurations are correctly loaded.

Through systematic troubleshooting methods and comprehensive configuration checks, developers can effectively prevent and resolve SQLSTATE[HY000] [2002] connection refused errors, ensuring smooth database operations in Laravel projects.