Database connection refused while setting up Magento via terminal

Database connection refused while setting up Magento via terminal

August 3, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Database connection refused while setting up Magento via terminal

Troubleshooting Database Connection Issues While Setting Up Magento Locally

If you’re facing database connection refused errors while setting up your Magento project locally on MacOS using MAMP PRO or similar tools, you’re not alone. This is a common issue that many developers encounter during the initial setup phase. In this post, we’ll walk through some steps to help you resolve this problem.

Checking Your Database Connection Details

Before diving into troubleshooting, let’s ensure your database connection details are correct. You mentioned using PDO to connect manually, which suggests that your credentials (host, name, user, password) are likely valid. However, there could be a misconfiguration when Magento tries to connect during the setup process.

Here are some things to double-check:

  • Database Host: Make sure your host is correctly set as localhost. If you’re using a remote database, ensure the host address matches exactly with what’s configured in your database settings.
  • Database Name: The name should match the name of the database where you want Magento installed.
  • Username and Password: Ensure these credentials are valid for the selected database.

Enabling Remote Connections

If your database is hosted on a remote server, make sure remote connections are enabled. By default, many databases restrict access only to local clients for security reasons. To allow remote connections:

  1. MySQL/MariaDB:

    • Log in as the root user.
    • Run GRANT ALL PRIVILEGES ON database_name.* TO 'username'@'%' IDENTIFIED BY 'password';
    • Replace database_name, username, and password with your actual details.
    • Restart the MySQL/MariaDB service to apply changes.
  2. PostgreSQL:

    • Connect as a superuser (e.g., postgres).
    • Run ALTER DATABASE database_name ALLOW CONNECTIONS FROM 'all' remote_host;
    • Replace database_name and remote_host with your actual details.
    • Restart the PostgreSQL service.

Firewall and Port Settings

Sometimes, firewall settings or port conflicts can prevent Magento from connecting to your database. Here are a few things to check:

  • Port: Make sure MAMP PRO is using the default ports (8889 for MySQL/MariaDB, 5432 for PostgreSQL) that match what you’ve specified in your app/etc/env.php file.
  • Firewall: Ensure your firewall isn’t blocking traffic on these ports.

Other Considerations

  1. File Permissions: Magento requires specific permissions to write files during setup. Double-check that the necessary folders (like var, pub/media, etc.) have appropriate read and write permissions.

  2. Database Server Status: Confirm that your database server is running. In MAMP PRO, you can easily check this in the main window where your servers are listed.

The Importance of Environment Variables

In many cases, the issue lies with how Magento interprets environment variables. It’s crucial to ensure that the app/etc/env.php file contains the correct database credentials. If this file is misconfigured or empty, Magento will fail during setup.

Remember, always back up your existing configuration before making any changes to avoid data loss.

Wrapping Up

Troubleshooting database connection issues involves a combination of validating your credentials, checking network settings, and ensuring Magento has the necessary permissions. If you’re still facing problems after verifying these points, consider reaching out to official support channels or forums like StackExchange for more targeted help.

Don’t forget to explore our detailed tutorials on Laravel Company, where we offer step-by-step guides for setting up development environments and resolving common issues in Magento and other popular frameworks.

Database Security API Configuration

Our network