WordPress database connection error: diagnosis and solutions

Understand the message before changing WordPress

The message “Error establishing a database connection” appears when WordPress cannot establish the expected communication with its database. That database contains posts, accounts, and many settings, among other things. The failure does not automatically mean that those records were erased: an incorrect password or a temporarily unavailable service can produce the same screen.

Start by opening the home page, an internal page, and administration. Record the exact text of each response. A cached page may continue to display while administration fails; that does not prove that the database is working normally. Conversely, an error on just one screen may require a more targeted diagnosis than a general outage.

Record the last known change: migration, restore, MySQL account modification, hosting change, or traffic spike. An error appearing immediately after moving the site points first to configuration. An intermittent error without a recent change also warrants examining the database service and its limits.

The following steps concern an installation whose hosting you can administer. On a managed platform such as WordPress.com, pass your observations to support when files and the server are inaccessible. No plugin is required for this diagnosis.

Choose between three approaches

Approach 1 makes the WordPress configuration consistent with the access details provided by the host. It is suitable after a migration or credential change. Compare specific values, then correct only those with a confirmed discrepancy.

Approach 2 checks the availability of the MySQL or MariaDB service. It takes priority when configuration is unchanged, the error occurs intermittently, or several sites on the same hosting are affected. The fix often lies in the service, its capacity, or communication between servers.

Approach 3 concerns the database itself: the wrong database selected, an incomplete import, an inconsistent prefix, or a genuinely damaged table. It should not begin with a general repair. First establish what is missing or failing and identify the storage engine in use.

Keep a simple test record: time, address tested, change made, and result. Make one change at a time. Several simultaneous changes may make the message disappear without revealing which correction was necessary or which other function was affected.

Protect the data and current configuration

Locate the most recent backup containing both files and the database. Check its date, location, and whether it can be restored to a copy. A site-file archive may contain images and plugins without containing posts or orders stored in the database.

Also retain the current state if the host can take a snapshot. On an active site, useful records may have been created since the last healthy copy. Restoring yesterday’s entire database to correct one wrong credential would create a risk of loss unrelated to the actual cause.

Using the authenticated file manager or SFTP, download a copy of wp-config.php to a private local location before editing it. This file contains secrets: do not publish it in an open ticket, forum, or code repository. Do not leave a copy named .bak in the public directory either, because the server configuration may allow it to be downloaded.

If the database is inaccessible, do not conclude that a backup is impossible: the provider may have copies and tools that do not depend on WordPress working. Ask what it can preserve before a repair or restore. Do not erase the existing database to make room for a new installation.

Obtain technical details without exposing secrets

The general WordPress screen does not always include SQL details. With authorized hosting-panel access, consult private logs at the time of the refusal or ask support for the corresponding code and message. Do not enable public error display to obtain this information.

The codes below are documented reference points, not test results from your site. Record the MySQL or MariaDB version and actual context. When sharing an excerpt, mask sensitive usernames, hosts, and database names; retain exact values only for the authorized provider.

Approach 1: compare the four connection parameters

In the file manager or over SFTP, open the configuration file for the correct installation. Check the domain associated with that directory: the same account may contain several versions of the site. Find the four connection constants and compare them with the hosting information.

DB_NAME is the exact database name. It may include a provider-added prefix. DB_USER is the MySQL or MariaDB user authorized to access it; it is not your WordPress administrator username. DB_PASSWORD is that database user’s password. Finally, DB_HOST specifies the server to contact, possibly including a port or socket path depending on the environment.

Copy values from a reliable source in the customer panel. Do not infer them from the public domain. After a migration, the database name may look identical while having a different prefix, and the SQL server may be separate from the web server. A hosting-account password is not necessarily the SQL user’s password. cPanel does not reveal the existing SQL password. Use the private record already retained; its absence from the panel is not a reason to reset it without checking other applications that use it.

If values are loaded from environment variables or a provider-managed file, do not replace that logic with values written in several places. Have the actual source corrected. A second definition in wp-config.php does not guarantee that you replace the first and may produce a warning.

The lines below are entirely fictional: they are the four definitions to locate, not a complete wp-config.php file or values to use unchanged. Replace only the confirmed incorrect value in its existing definition. Retain the host, port, or socket supplied by hosting and never send the real secret in a public ticket.

Required access: the correct installation’s file and reliable SQL-account records. Expected result: the four values actually loaded match this database and user. If a syntax error appears after editing, restore the private file copy; do not create another definition to compensate.

1. Open the confirmed installation’s wp-config.php in your text editor after making its private copy.
2. Locate the four existing definitions and compare their values with reliable records for this installation without changing the constant names.
3. Correct only the value proven wrong; do not replace managed environment logic or add duplicates. Preserve the syntax and necessary escaping.

define( 'DB_NAME', 'NOM_BASE_CONFIRME' );
define( 'DB_USER', 'UTILISATEUR_SQL_CONFIRME' );
define( 'DB_PASSWORD', 'SECRET_CONFIRME_A_SAISIR_EN_PRIVE' );
define( 'DB_HOST', 'HOTE_PORT_OU_SOCKET_FOURNI' );

Access denied: distinguish authentication from database permissions

Code 1045 with Access denied points toward SQL-account authentication: check the user, its allowed origin, and the secret actually transmitted. using password: YES means that a password was sent, not that it was correct; NO means that no password was sent in that attempt.

Code 1044, naming a database to which access was denied, points more toward that account’s permissions on the database. Have the association checked in the hosting panel before rotating a password. These messages justify neither replacing the account with root nor creating a global SQL administrator. Confirm the configuration actually loaded before the targeted correction below.

Correct the confirmed value and check the account’s permissions

Change only the parameter whose error you have confirmed. Preserve the existing PHP syntax: quotation marks, comma, and semicolon. Use a plain-text editor without typographic quotation marks. If the secret contains characters requiring escaping in the PHP string, have the value correctly represented rather than removing those characters from the password.

Save, then open administration and a public page. If a new syntax error appears, immediately restore the file copy and recheck the edit. A PHP error introduced during troubleshooting is separate from the original connection failure.

In the database-management panel, also check that the user is associated with the selected database and has the permissions WordPress requires. An account can exist without being authorized on that database. Request a correction limited to the relevant installation; it does not need administrative rights over every database on the server.

Do not reset the SQL password without checking which sites or services use it. If it is shared, they must be updated in a coordinated way. Rotation may be justified, but its scope must be known. Otherwise you risk repairing one site by cutting off another site’s connection.

Associate the correct user with the database in cPanel

If the association is genuinely missing in cPanel, the procedure below uses the two names you already verified, including any prefixes. Required access: database management for this account. You do not need to recreate the database, recreate the user, or change a shared account’s password to repair this association.

Expected result: WordPress reads the correct database and can save the planned draft. To roll back an unjustified change, restore only the privilege checkboxes you recorded. If a newly added association should not exist, remove only that association after confirmation; delete neither the database nor the SQL account.

1. In cPanel, open Manage My Databases. In older versions, the section may be called MySQL Databases. Under Current Databases, record the existing association and permissions for the target pair.
2. If the association is missing, go to Add User To Database. Select the exact SQL user and database confirmed in the configuration, then Add.
3. On the privileges screen, choose the permissions required for this database alone. For a database dedicated to a standard WordPress installation, the installation documentation specifies All Privileges on that database; this does not mean global server privileges.
4. Click Make Changes. If the association already existed, instead open its user under Current Databases and correct only the wrong privileges, saving in the same way.
5. Revisit administration and a known page, then perform the appropriate write test described at the end of the guide. If it fails, keep the exact message and undo only the unjustified change before investigating another cause.

Do not change DB_HOST at random

The values localhost and 127.0.0.1 are not interchangeable in every environment. Depending on the system and client, the first may use a local socket while the second forces a TCP connection. The port, socket path, and account permissions may therefore change the result.

Use the address supplied by the host for this installation. If the database is on a remote server, also ask which web server is authorized to connect. A migration may have changed the connection’s origin without updating the corresponding permissions.

Do not open the SQL service to every address as a test. Have the network route and expected-origin authorization checked. If the provider supplies a new value, record the old one, apply the correction, and repeat the same test. An example that worked on a forum is not a universal value to copy into your configuration.

Unreachable host: examine the route before the password

In MySQL clients, 2002 can concern a failed local socket connection and 2003 a failed connection to the server. With 2005, start by having the hostname and its resolution—translation into a network address—checked. Wording may vary with the PHP client.

A refused connection or timeout does not prove the password is wrong. A wrong port, different socket, network filtering, or stopped service require separate checks. Have the route tested from the web server, not just from your computer. Do not automatically change the host to localhost or open the port to the Internet.

Approach 2: check the service and database availability

Check incidents announced by the host and service status in the customer account. If several installations on the same account fail simultaneously, tell support. This points toward a shared resource but does not remove the need to check whether they actually use the same database server.

Try opening the database through the host’s tool. If phpMyAdmin cannot reach the server, retain its message and the time. If phpMyAdmin works, remain cautious: it may use another account or network route than WordPress. Success therefore does not prove that the application’s four parameters are correct.

Ask the provider to test the connection from the web server using the site’s SQL user, without transmitting the secret in a public message. An authenticated customer account should normally let the provider identify the installation. The technical result distinguishes access denied, an unreachable host, an unknown database, or a reached limit.

On a server you administer, start with service logs and available resources. A restart may temporarily restore availability without explaining why the failure returns. Avoid repeated restarts during a restore or important processing. Preserve incident traces before any operation that would make them harder to interpret.

Interrupted connection: do not immediately conclude that the server stopped

MySQL codes 2006 or 2013 may indicate a lost connection. They do not prove that the server remains unavailable: an expired connection, network incident, restart, or query size may call for different checks. Have the time, current operation, and service logs correlated.

After an interrupted import or business operation, check what has already been saved before starting again. An error does not guarantee that no write occurred; another blind attempt may create duplicates.

If the error appears only at certain times

Compare failure times with scheduled tasks: backups, imports, synchronizations, report generation, or order processing. An error during every import may indicate concentrated load. It does not automatically prove that the import plugin is faulty; volume and available resources also matter.

MySQL code 1040, accompanied by Too many connections, points to the global connection limit. Code 1203 concerns the user account’s simultaneous connections: the server may still accept other accounts. Have the effective limit and processes occupying connections checked before raising it. Increasing a ceiling without examining memory and load can move the problem elsewhere; do not request a globally privileged SQL account to bypass the limit.

If you started a nonessential task that coincides with the failure, stop it through its normal mechanism where supported, then observe the result. Do not randomly kill database processes on a production store. An ongoing action may be writing data whose consistency must be preserved.

After the correction, observe the site during the time window when the error occurred. A working page at a quiet time does not validate a load-related failure. Record the time and result of this check without turning one successful test into a guarantee of permanent availability.

Unknown database: check the server and name before restoring

Code 1049 with Unknown database means that the server reached does not recognize the requested name. It does not prove that all your data has disappeared: after a migration, you may be reaching the wrong server or using an old name without its hosting prefix.

Compare DB_NAME and DB_HOST with the panel’s records, then have the database’s existence on that server confirmed. Do not create an empty database with the same name merely to remove the message. If the database exists but tables are missing, continue below: that is a different diagnosis.

Approach 3: check the correct database, tables, and prefix

After a migration, open the selected database in the host’s tool and inspect the table list. Check that the import actually took place and finished without errors. A created but empty database does not contain your site, even if its name matches the configuration file.

Then compare the prefix declared in $table_prefix with the site’s table prefix. An inconsistent prefix can prevent WordPress from finding the intended installation. If an installation wizard appears even though the site already had content, do not immediately run it. It may indicate the wrong database, wrong prefix, or an incomplete import.

When several groups of tables exist, do not simply choose the one with the most rows. Identify the intended copy using the migration context, site addresses, and known data. An old group may contain many posts while missing the most recent orders. Have that choice confirmed before changing the prefix or importing again.

If the database is correct but a table is missing, reread the import report. Creation may have failed because of a size limit, permission, or incompatibility. Reimporting the entire backup over a database used in the meantime may overwrite valid data. Prefer reproducing the import in a test database to understand what fails.

Check tables with WP-CLI when appropriate

If you have WP-CLI and authorized SSH access, the command below uses wp-config.php parameters and an available mysqlcheck or mariadb-check utility to check the database. Change to the correct installation’s directory. Without a further selection, it examines every table in DB_NAME, not only tables using the WordPress prefix: run it only on a dedicated database or isolated copy whose scope is confirmed. If the database is shared, have the administrator choose a check limited to the relevant tables.

This check is not a repair and may place load on or lock tables depending on their engine and condition. For a large database, active store, or suspected corruption, have the host choose the timing and method, ideally on a copy. Do not run it repeatedly to monitor availability.

Read the full message. A connection failure means that the check could not examine the tables; it does not prove that they are damaged. A table reported in error then requires analysis specific to its engine. A satisfactory result does not guarantee that business data, relationships between plugins, and all expected content are present.

wp db check

Repair only when the diagnosis justifies it

Check the tables’ engine type in the administration tool or ask support. Procedures based on REPAIR TABLE do not apply to every engine. In particular, an InnoDB table cannot be repaired with this classic command. Repeating an unsupported action does not turn its result into a repair.

WordPress has a native repair page that can be temporarily enabled with WP_ALLOW_REPAIR. It does not fix an incorrect SQL password or an inaccessible server. Reserve it for a situation where the connection works and diagnosis has confirmed that an operation supported by the engine is relevant. Retain a backup or snapshot before any repair write. The native page iterates through the tables WordPress supplies to it; its screen does not simply let you select one table. If diagnosis calls for one table only, prefer a targeted intervention by the database administrator.

When enabled, this page can be used without signing in to administration. Have hosting protect its access during the intervention or work on an isolated copy. In that context, temporarily add define( 'WP_ALLOW_REPAIR', true ); to configuration before WordPress loads, open the relevant site’s /wp-admin/maint/repair.php path, and choose the intended repair. Optimization is not necessary merely to try to restore a connection.

Retain the result, remove the temporary constant immediately, then check that the function is no longer accessible in that state. If an InnoDB table is genuinely damaged, request a recovery procedure suited to the server and version. Do not randomly apply forced-recovery mode or commands found for another engine.

If a restore becomes necessary

A restore should address an identified absence or corruption. Check the copy’s date and the data that would be lost by returning to that point. For a store, account for orders, payments, stock, and accounts created since then. An old copy may bring the home page online while making commercial information inconsistent.

First request a restore in a separate environment. Check the expected content and consistency with files: media, themes, and plugin versions must correspond to a usable state. A database restored alongside very different component versions may require additional processing. This copy must have its own database and protected access; disable its emails, payments, and external automations before visiting it.

Then prepare the move to production with a method for preserving recent data. That method depends on the site; manually copying a few rows is not a universal procedure for orders linked across several tables. Keep the pre-intervention state until all checks are complete.

If the problem was limited to an incorrect parameter, a restore adds nothing over a targeted correction. Restored access should come with an explanation of the cause so the same failure is not repeated during the next migration.

Verify normal operation has returned

Open administration and a few public pages as a signed-out visitor. Check an old item and a recent one to ensure you are using the correct database. If you have a test copy, check that production is not accidentally pointing to it and that the two environments do not unintentionally share writes.

Then perform a small write operation appropriate to the site, such as saving a clearly identified test draft. A database accessible for reading but lacking proper write permissions may display pages while preventing edits. For a store, use the intended test workflows without triggering a real payment solely for this check.

Inspect logs at the times of these tests and remove temporary diagnostic or repair settings. If secrets were published during troubleshooting, arrange their replacement in a coordinated way. Hiding a screenshot afterward does not guarantee that exposed values were not copied.

A cleanup or optimization plugin replaces none of these steps. When WordPress cannot access its database, that tool may also be unable to run. Hosting tools, configuration, and server diagnostics form the main procedure. The right outcome is a site that reads and saves the expected data, with an identified cause and documented correction.

A professional TCP connection check without changing the database

If the provider confirms a TCP connection and supplies the MySQL client, an authorized administrator can test from the web server using the same SQL account. Adapt the confirmed host, port, user, and database name separately. The secret is requested after launch; do not append it after --password in the command. For a remote database, retain the TLS parameters required by hosting; this example does not replace them.

The expected result is a row with connexion_ok equal to 1. That confirms this connection and this small read, not write permissions or the presence of all WordPress tables. A refusal provides a code to compare with the earlier branches. If WordPress uses a socket, do not convert its configuration to TCP to match this example: have its actual route tested.

The query changes no application data. The client nevertheless loads its own settings; success in the terminal does not prove that PHP uses the same account, TLS configuration, or network context. The final check remains the site returning and the planned draft being saved.

mysql --protocol=TCP --host=HOTE_CONFIRME --port=3306 --user=UTILISATEUR_CONFIRME --password --database=BASE_CONFIRMEE --execute="SELECT 1 AS connexion_ok;"