WordPress is the most commonly used CMS for websites. It is based on PHP and the website data is stored in a MySQL database, the details of which are mentioned in the configuration file.

As the information is stored in a MySQL database, it is common to encounter database-related errors during installation, migration, upgrade or occasional browsing of the WP site.

How to fix WordPress ‘Error establishing database connection’ message

If you notice WordPress ‘Error establishing database connection’ message in your site, it could be due to a number of reasons. Today we’ll discuss the 3 major causes and see how to fix them.

1. Incorrect details in the WordPress config file

WordPress stores the details such as the URL, permalinks, user account details, blog posts, categories, etc. in a database, which is specified in the config file.

During installation of WordPress, these following database parameters are provided by the user and WordPress stores it in the ‘wp-config.php’ configuration file.

Database Name - name of the database used by WordPress

Database Username - name of the MySQL user used to access the database

Database Password - password of the user used to access the database

Database Host - hostname of the database Server, usually localhost

For a database connection to be established, these parameters should be correct and should work fine.

MySQL database credentials in WordPress config

The MySQL user should be able to connect to the Database server with the password provided, and the user should be given adequate privileges to access the database.

Only if all these conditions are met, the database connection would be properly established and the WordPress would be able to fetch information from the database.

If there is any problem establishing the database connection during any website activity, the WordPress site would show the message ‘Error establishing database connection’.

Solution:

1. The first thing to confirm when you see the database connection error, is to confirm the database connectivity. This can be done from the MySQL server.

Get the information from the wp-config.php file. Use the command ‘mysql -u username -p’ to connect. Provide the password and confirm the privilege for the user to the database using ‘use databasename’ command.

Verify the WordPress database connectivity

If the database connection is established fine, you should see a snippet like above. You can also test the database connectivity using ‘mysql_connect’ function in PHP.

If the connection is not established, you will see error similar to “Connect failed: Access denied for user ‘user’@’localhost’ (using password: YES)”. If so, you need to correct the database details in the config file with the valid ones and test the connection again.

2. If the user doesn’t have enough privilege to the database, grant the required rights. The error message ‘Access denied for user ‘username’@’localhost’ to database ‘DATABASE’‘ will be shown in the absence of enough privileges.

You can create MySQL users and grant privileges to them from the cPanel -> ‘MySQL Databases’ section or from the backend as the MySQL root user.

3. If you notice an error such as ‘Unknown database ‘db_name’’, it means that the database itself is non-existent and need to be created first.

You can create the database from cPanel -> ‘MySQL Databases’ section or from the backend as the MySQL root user. Also confirm that the name of the database that is given in the config file is correct.

2. MySQL server not working

MySQL server may sometimes get overloaded due to traffic spikes or abusive user accounts. This can lead to connectivity issues or inaccessible database server.

Especially, if you have WordPress websites running on a shared server with multiple accounts, there may be chances of database connectivity issues happening at peak hours.

If the database server is having issues, the error messages shown can be ‘No such host is known’, ‘MySQL Server is unreachable’, ‘A connection attempt failed’, etc.

Solution: 

To verify if the MySQL server is running and accessible, connect to MySQL using ‘mysql’ command and check the service status and uptime.

MySQL ‘process list’ shows the list of processes and queries running in the MySQL. Examining it for too many concurrent connections, will reveal if there is any abuse or attack going on.

MySQL process list check

Optimizing the MySQL service configuration file and tweaking the settings are done to ensure that MySQL load is always within the limits and service is not interrupted. The number of database connections can be limited in the config file.

For high traffic websites, we configure solutions such as replication and clustering to ensure high availability for the database servers. To know more about which HA solution suits your business, read our post on ‘MySQL high availability solutions’.

3. Corrupt database and files

Database connection errors in WordPress can happen due to corrupted database or files too. When databases get corrupted, they need to be repaired, for the site to work fine.

If you see an error like “One or more database tables are unavailable. The database may need to be repaired”, then you need to repair the database.

Solution:

WordPress itself has a feature to repair the database. To enable this repair mode, add this line in the ‘wp-admin.php’ file.

define( 'WP_ALLOW_REPAIR', true );

Once this setting is done, access the URL http://www.yoursite.com/wp-admin/maint/repair.php. It will present a page to ‘Repair Database’.

Repair database in WordPress

After repairing the database, the repair mode has to be switched off, for security reasons, as anybody can access it and tamper with the database.

Now, try refreshing your site and clear the browser cache. The database connection error would be gone now and the site would load fine.

Database repairs can be done from the MySQL backend or via PhpMyAdmin with the ‘Repair Table’ option for the database tables.

To summarize..

Database and file changes should be done with utmost caution, as a silly mistake can lead to a crashed website and business downtime.

Always make sure that the backup of the WordPress database and files are taken before making any changes, as a pro-active safety measure.

There are many WordPress plugins such as caching plugins, that are aimed at optimizing the WordPress sites. But, if not installed without properly validating them, these plugins can end up crashing the site.

WordPress database errors can also happen due to other reasons such as incorrect ‘siteurl’ setting in the database or insufficient permissions for the data files.

If nothing works, you would have to restore the website files and databases from the recently available backups, and test that the site is working fine.

At Bobcares, our 24/7 monitoring, optimization and HA solutions helps us to ensure that our customers’ websites are not affected by database errors or downtime.

If you’d like to know how to manage your WordPress websites without errors or downtime, we’d be happy to talk to you.

Read: How to fix MySQL high CPU usage