Home › Knowledgebase › KB-1296

Website error establishing a database connection

Summary

This guide helps you troubleshoot and resolve: Website error establishing a database connection. Follow the steps below to fix the issue.

Quick Tip: Need immediate assistance? 💻 Open a Ticket

Common Causes

An "Error establishing a database connection" means your website's application cannot communicate with its database. This typically occurs when login credentials are incorrect, the database server is unresponsive, or the database itself has become corrupted. Because your website relies on this connection to display content, process orders, and load administrative dashboards, this error usually results in the entire site becoming inaccessible.

Remember — If you host with us, you don't need to do this yourself — just Open a Ticket and our Brisbane team will get it sorted.
Before performing any database repair or modification steps, create a full backup of your database. Repair operations on corrupted tables can result in permanent data loss. Download a backup via your hosting control panel or use phpMyAdmin to export your database before proceeding.

Quick Fix Steps

  1. Verify your database credentials in your website's configuration file.
  2. Check that your database server is running and responding to requests.
  3. Verify the database server hostname format (localhost, IP address, or remote host).
  4. Repair the database using your hosting control panel tools.
  5. Confirm that your database user exists and has the correct permissions assigned.
  6. Check database disk space quota and connection limits.
  7. Restart the database service if you have server-level access.

Detailed Instructions

Verify Database Credentials

  1. Access your website files via FTP or your hosting control panel's file manager.
  2. Locate your website's configuration file. Common paths include:
    • wp-config.php for WordPress installations
    • configuration.php for Joomla
    • config.php for OpenCart or custom PHP applications
  3. Open the file and look for the database connection settings. You will typically find entries such as:
    • DB_NAME — the name of your database
    • DB_USER — the database username
    • DB_PASSWORD — the database password
    • DB_HOST — usually localhost, though some providers use a specific hostname or IP address
    • $table_prefix — for WordPress, verify this matches the actual prefix used in your database tables (commonly wp_)
  4. Log in to your hosting control panel and navigate to the Databases or MySQL Databases section.
  5. Confirm that the database name, username, and host match exactly what is listed in your configuration file.
  6. Verify that the database user exists in the control panel before assigning permissions. If the user does not exist, create it first.
  7. If the password does not match, reset the database user password in your control panel and update the configuration file with the new value.
  8. Save the configuration file and refresh your website in a browser.
Always download a backup copy of your configuration file before making changes. This allows you to restore the original settings if a typo causes further issues.

Verify Database Server Hostname Format

  1. Check the DB_HOST value in your configuration file.
  2. If your database is hosted on the same server as your website, localhost is typically correct.
  3. If your database is on a remote server, the value may be an IP address (e.g., 192.168.1.100) or a remote hostname (e.g., db.example.com).
  4. Confirm the correct hostname in your hosting control panel under MySQL Databases or Database Details.
  5. If you recently migrated your website, ensure you updated DB_HOST to match the new provider's requirements.

Check Database Server Status

  1. Log in to your hosting control panel.
  2. Open phpMyAdmin or the equivalent database management tool.
  3. Attempt to log in using your database username and password.
  4. If you cannot log in, the database server may be down or your credentials may be incorrect.
  5. If you can log in but cannot see your database, the database may have been deleted or the user may lack permission to access it.
  6. If you are on a VPS or dedicated server, use the command line to check the database service status. For example, on many Linux systems you can run systemctl status mysql or systemctl status mariadb.
Do not restart database services on a production server unless you are comfortable with server administration. An improper restart can cause data corruption or extended downtime.

Check Database Disk Space and Connection Limits

  1. Log in to your hosting control panel.
  2. Navigate to Server Information, Database Settings, or Account Usage.
  3. Check your database disk space quota. If you have reached your storage limit, the database may refuse new connections or writes.
  4. Check your maximum concurrent connection limit. If your site exceeds this limit, you may see "Too many connections" errors.
  5. If you are approaching or have exceeded these limits, optimise your database queries or contact your hosting provider about upgrading your plan.

Repair the Database

Repairing corrupted tables may result in data loss. Ensure you have a current backup before proceeding. On large databases, repair operations may take several minutes or longer. Do not interrupt the process once started.
  1. Log in to your hosting control panel and open phpMyAdmin.
  2. Select your website's database from the left-hand menu.
  3. Select all tables, or select the tables that are reporting errors.
  4. From the With selected: dropdown menu, choose Repair table.
  5. Alternatively, if you use WordPress, you can enable automatic repair by adding the following line to your wp-config.php file: define('WP_ALLOW_REPAIR', true);
  6. Visit yourdomain.com/wp-admin/maint/repair.php in your browser, replacing yourdomain.com with your actual domain name, and click Repair Database.
  7. Once the repair is complete, remove the repair line from your wp-config.php file to prevent unauthorised access to the repair script.

Test Database Connection Independently

  1. Create a new file named db-test.php in your website's root directory.
  2. Add the following code, replacing the placeholder values with your actual database details:
    <?php
    $host = 'localhost';
    $user = 'your_database_user';
    $pass = 'your_database_password';
    $dbname = 'your_database_name';
    
    $conn = new mysqli($host, $user, $pass, $dbname);
    
    if ($conn->connect_error) {
        die('Connection failed: ' . $conn->connect_error);
    }
    echo 'Connected successfully';
    $conn->close();
    ?>
  3. Visit yourdomain.com/db-test.php in your browser, replacing yourdomain.com with your actual domain.
  4. If the script fails, the issue is with your database credentials or server connectivity, not your website application.
  5. Delete db-test.php after testing to prevent unauthorised access.

Verify Database User Permissions

  1. In your hosting control panel, open the MySQL Databases section.
  2. Confirm the database user exists. If not, create the user first.
  3. Locate the user assigned to your database under Current Databases.
  4. Click Add User to Database or Manage Privileges.
  5. Ensure the user has all necessary privileges, including SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, and INDEX.
  6. Click Make Changes or Save to apply the permissions.
  7. Test your website again.

Check DNS and Network Connectivity to Database Server

  1. If your database is hosted on a remote server, verify that you can reach the database host from your web server.
  2. Flush your local DNS cache if you recently changed database host details.
  3. On a VPS or dedicated server, test connectivity using ping or telnet to the database host and port (default MySQL port is 3306).
  4. Check your firewall settings to ensure the database port is not blocked.
  5. If you cannot reach the database server, contact your hosting provider to verify network access.

Troubleshooting

Database Does Not Exist After Migration or Restore

  1. Log in to your hosting control panel and open MySQL Databases.
  2. Check whether your database appears in the list of current databases.
  3. If the database is missing, it may not have been migrated or restored correctly.
  4. Restore the database from a backup using phpMyAdmin or your control panel's restore tool.
  5. After restoring, verify that the database user is assigned to the database with the correct permissions.
  6. Update your configuration file if the database name or username changed during the restore process.

Error Started After a Plugin or Extension Update

  1. Access your site files via FTP or file manager.
  2. Navigate to your plugins or extensions directory. For WordPress, this is typically wp-content/plugins/.
  3. Rename the folder of the recently updated plugin to something like plugin-name-disabled.
  4. Refresh your website to see if the error clears.
  5. If the site loads, the plugin is incompatible with your current database version or configuration. Contact the plugin developer or restore a backup from before the update.

Error Started After a Script Version Change

  1. Confirm that your website application version is compatible with your database server version.
  2. Some newer applications require MySQL 5.7 or 8.0, while older scripts may only work with MySQL 5.6 or earlier.
  3. Check your hosting control panel for the database server version under Server Information or Database Settings.
  4. If there is a version mismatch, you may need to update your website application or contact your hosting provider about database server options.

Database Connection Drops Intermittently

  1. Check your website's error logs for messages such as "Too many connections" or "MySQL server has gone away."
  2. If you see "Too many connections," your site may be exceeding the database connection limit imposed by your hosting plan.
  3. Optimise your website's database queries or upgrade your hosting plan to allow more concurrent connections.
  4. Ensure that persistent connections are not enabled in your application configuration unless specifically required.
If you are unable to verify or reset your database credentials, contact your hosting provider for assistance. They can confirm the correct database details and reset user passwords on your behalf.
Remember — If you host with us, you don't need to do this yourself — just Open a Ticket and our Brisbane team will get it sorted.

Still Having Issues?

Need more help? If the issue persists after trying these steps, please open a support ticket and our team will assist you.

💻 Open a Ticket