Resolving Magento 2 Database Connection Errors
When working on a live Magento server, you may encounter database connection errors when running commands like setup:upgrade. In many cases, these issues stem from incorrect configuration of the database details in your env.php or app/etc/env.php files.
Understanding the Error Message
The error message “Port must be configured within host parameter (like localhost:3306)” suggests that Magento is unable to establish a connection with your database because it cannot recognize the port number. The subsequent errors indicate that the database server refused the connection attempt.
[Zend_Db_Adapter_Exception]
SQLSTATE[HY000] [2002] Connection refused
[PDOException]
SQLSTATE[HY000] [2002] Connection refused
Step-by-Step Solution
To resolve this issue, you need to ensure your database connection parameters are correctly set in the app/etc/env.php file.
-
Locate and open the
env.phporapp/etc/env.phpfile using a text editor or an SSH terminal. -
Look for the
db_hostconfiguration parameter under thedb_connection_defaultarray:
'default' => [
'connection' => [
'adapter' => 'mysql',
'host' => 'localhost', // Change this line
'name' => 'magento_database_name',
'user' => 'magento_user',
'password' => 'magento_password'
],
],
-
The
hostparameter should be set to the correct hostname or IP address of your database server. If you’re using a local MySQL installation, it might look likelocalhost:3306. -
If your domain name resolves to your server’s IP address, you can also use that as the host value.
-
Save the changes and close the file.
Best Practices
- Always double-check the database details in the
env.phpfile after any server migration or configuration changes. - Ensure that the MySQL service is running on your server.
- If you’re using a remote database, verify that the firewall rules allow connections from your Magento server to the database.
Debugging Tips
If the issue persists even after updating the env.php file:
- Enable Magento’s debug mode in the
app/etc/env.phpfile:
'db' => [
'transaction_model_class' => 'Magento\Framework\DB\Transaction',
'log' => false,
'logger' => null,
],
-
Run your command again:
php bin/magento setup:upgrade -
Check the Magento exception logs located in
var/log/exception.logfor more detailed information about the error.
Conclusion
Resolving database connection errors in Magento typically involves verifying and updating the database configuration parameters in the env.php file. Always ensure that the host value matches your actual MySQL server’s address or hostname, including the correct port number if needed.
Remember to keep your server’s firewall settings open for communication between your Magento application and the database server. If you’re still experiencing issues after following these steps, consider reaching out to a Magento developer or support team for further assistance.
For more advanced troubleshooting techniques and best practices in Magento 2 development, visit Laravel Company.