Quick Summary
The "Error establishing a database connection" error on macOS indicates that your website or application is unable to communicate with its database server. This usually prevents the website from loading correctly, or the application from operating as expected.
Common Causes
- Incorrect Database Credentials: The username, password, database name, or host used to connect to the database server are incorrect. This is a common issue after updates or migrations.
- Database Server is Down: The database server itself (e.g., MySQL, PostgreSQL) is not running or is unreachable. This could be due to server maintenance, a crash, or network issues.
- Database Server Not Running Locally: If you are running the database server locally on your Mac, it might not be started. This applies if you are using tools like XAMPP, MAMP, or Docker.
- Database Connection Limit Reached: The database server has reached its maximum number of allowed connections. This is more common in high-traffic scenarios or if a previous process did not properly close a connection.
- Firewall Issues: The macOS firewall, or a third-party firewall, may be blocking connections to the database server's port (e.g., 3306 for MySQL, 5432 for PostgreSQL).
- Corrupted Database Files: Although less common, the database files themselves may be corrupted, preventing the server from starting or accepting connections.
Step-by-Step Fixes
Method 1: Verify Database Credentials
Step 1: Locate the configuration file for your website or application. This usually contains the database connection details. The location depends on the specific application. Some common configuration file names are wp-config.php (for WordPress), settings.php (for Drupal), or config.php (for Laravel).
Step 2: Open the configuration file in a text editor.
Step 3: Carefully verify the following values:
- Database Name
- Username
- Password
- Host (Database Server Address). Often 'localhost' or '127.0.0.1' for local servers.
Step 4: If necessary, update the incorrect values with the correct information obtained from your hosting provider or database administrator.
Step 5: Save the changes to the configuration file.
Step 6: Refresh your website or application in your browser to see if the connection is now established.
Method 2: Check Database Server Status and Start it
Step 1: If you are using a local development environment like XAMPP, MAMP, or Docker, ensure that the database server (e.g., MySQL, PostgreSQL) is running.
Step 2: Open the XAMPP or MAMP control panel (or the Docker Desktop application).
Step 3: Look for the database server service (e.g., MySQL, MariaDB, PostgreSQL).
Step 4: If the server status indicates it is stopped, click the 'Start' button to start the service.
Step 5: Wait for the service to start completely (the status should change to 'Running' or similar).
Step 6: If the server fails to start, check the logs for error messages. These logs can usually be found in the XAMPP/MAMP/Docker logs directory or the system logs.
Step 7: Restart your computer if all other attempts fail to start the service.
Method 3: Test Database Connection Remotely (if applicable)
Step 1: Open Terminal on your macOS.
Step 2: Attempt to connect to the database server using the command line. Replace `your_username`, `your_database_host`, and `your_database_name` with the actual values.
Step 3a (MySQL): Execute this command: `mysql -u your_username -h your_database_host -p your_database_name`. You will be prompted for your password.
Step 3b (PostgreSQL): Execute this command: `psql -U your_username -h your_database_host -d your_database_name`. You might be prompted for your password. If the database requires a specific port number, add `-p port_number` to the command.
Step 4: If the connection is successful, you will see a database prompt (e.g., `mysql>`, `postgres=>`).
Step 5: If the connection fails, the error message in the terminal provides further details which can assist with troubleshooting network connectivity or authentication issues.
Method 4: Check Firewall Settings
Step 1: Open System Preferences from the Apple menu.
Step 2: Click on 'Security & Privacy'.
Step 3: Click on the 'Firewall' tab.
Step 4: If the Firewall is turned on, check if your database server port (e.g., 3306 for MySQL, 5432 for PostgreSQL) is blocked.
Step 5: If the database server requires access and isn't explicitly allowed, add an exception or disable the firewall temporarily for testing purposes (remember to re-enable it afterwards!). This involves granting the specific database application permission through the firewall.
Step 6: If you are using a third-party firewall software, consult its documentation for instructions on adding exceptions or temporarily disabling.