What you will need
- cPanel login details for the hosting account.
- Access to File Manager or SFTP.
- The database name, or permission to inspect the account's databases.
- About 10 to 15 minutes.
Important: Download a copy of wp-config.php before editing it. If the site is already down, a bad edit makes diagnosis harder.
Step 1: Find wp-config.php
- In cPanel, open Files then File Manager.
- Open the directory containing
wp-load.php. This is usuallypublic_html, or a subdirectory such aspublic_html/blog. - If the file is not there, check one level above the WordPress directory. WordPress looks there as a fallback, and some managed setups keep the configuration outside the web root.
Do not edit the file through the WordPress theme or plugin editor. If the database is unreachable, you cannot reach that editor anyway, and a mistake there can take down the admin area.
Step 2: Read the four database constants
Open wp-config.php and locate this block:
define( 'DB_NAME', 'example_wp' );
define( 'DB_USER', 'example_wpuser' );
define( 'DB_PASSWORD', 'your-password' );
define( 'DB_HOST', 'localhost' );
Here is what each value must match:
| Constant | What it means | Where to verify it |
|---|---|---|
DB_NAME |
The full database name, including any account prefix | cPanel Current Databases |
DB_USER |
The full database username, including any account prefix | cPanel Current Users and Privileged Users |
DB_PASSWORD |
The password for that database user | Not displayed by cPanel; reset it if unknown |
DB_HOST |
The database server address | Usually localhost; check Remote MySQL Host if shown |
Copy the values exactly. Letter case and prefixes matter.
Step 3: Match the values in cPanel
- In cPanel, open Databases then MySQL Databases.
- In cPanel version 120 and later, this interface is named Manage My Databases. The fields are the same.
- In the Current Databases table, find the WordPress database and note its exact name.
- In the same row, check the Privileged Users column. The WordPress user must appear there.
- In Current Users, confirm the username exists and note its exact spelling.
cPanel commonly prefixes both names with the hosting account username. A site whose configuration says wp may actually use example_wp. The prefix is part of the real name and must be present in wp-config.php.
Step 4: Confirm the correct DB_HOST
On most cPanel accounts, DB_HOST is localhost. Some hosting setups use a separate database server, and cPanel then shows a Remote MySQL Host section with the address to use.
Use the value SysopHost provides for your plan. Do not replace localhost with an IP address from a tutorial, and do not add a port unless the provider specifies one. Some configurations accept localhost:3306 or a socket path such as localhost:/path/to/mysql.sock; if SysopHost gave you that format, use it exactly.
Step 5: If the password is unknown
- In MySQL Databases, scroll to Current Users.
- Click Change Password next to the WordPress database user.
- Generate a strong password and store it in a password manager.
- Click Change Password to confirm.
- Update
DB_PASSWORDinwp-config.phpimmediately.
Warning: changing the password affects every application that uses that database user. If another site, staging copy, or custom script shares the user, it will also stop connecting until its configuration is updated. If possible, give each WordPress installation its own database user.
Step 6: If the user is not attached to the database
- In MySQL Databases, find Add User To Database.
- Select the WordPress user and the WordPress database.
- Click Add.
- Select ALL PRIVILEGES.
- Click Make Changes.
Note: cPanel's documentation advises against creating databases or database users in phpMyAdmin. phpMyAdmin does not update cPanel's database map, which can cause backups and restores to fail. Use the cPanel database interfaces for creation and privilege changes; use phpMyAdmin only to inspect or edit table data.
Step 7: Edit wp-config.php correctly
Replace only the values inside the existing quotes. Keep the structure and punctuation intact:
define( 'DB_NAME', 'example_wp' );
define( 'DB_USER', 'example_wpuser' );
define( 'DB_PASSWORD', 'N3w-Str0ng-Passw0rd' );
define( 'DB_HOST', 'localhost' );
Rules that prevent most editing mistakes:
- Use straight single quotes, not curly quotes copied from a word processor.
- End every statement with a semicolon.
- Do not add spaces or blank lines before the opening PHP tag.
- Do not change
$table_prefixunless you know the database uses a different prefix. A wrong prefix usually makes WordPress behave as if it is not installed, rather than producing a connection error. - If the password contains a single quote or a backslash, escape it as
\'or\\. The simpler option is to reset the password to one without quotes or backslashes.
Step 8: Save the file and set permissions
- Save the file in File Manager.
- Set permissions to
600or640. Do not use777. - Delete any temporary copy from the web root. Keep your downloaded backup on your computer instead.
Step 9: Test the connection
Reload the site. If it loads, log in to /wp-admin and confirm that pages and settings are intact.
If the site still fails, enable temporary debugging as described in "How to Fix Error Establishing a Database Connection in WordPress" and read the exact error. If it says Access denied, recheck the username, password, and the user's privileges. If it says Unknown database, recheck the full database name.
On plans with SSH and WP-CLI, you can confirm the file's credentials directly:
cd /home/example/public_html
wp db query "SELECT 1;"
Run this as the account user, not as root.
If something goes wrong
Restore the copy of wp-config.php you downloaded in Step 1, then reload the site. If the site returns to the original error, the configuration edit was not the cause. Do not repeatedly overwrite the file with different guesses; return to the diagnostic sequence in the main troubleshooting article.
Security considerations
- Store database passwords in a password manager, not in a ticket, note, or chat.
- Use a separate database user for each WordPress site.
- Grant ALL PRIVILEGES only on that site's own database, not on other databases in the account.
- Keep
wp-config.phpat600or640. - If a password has been exposed, change it and update the configuration immediately.
Related articles
- How to Fix "Error Establishing a Database Connection" in WordPress
- How to Back Up and Restore a WordPress Database
- How to Take a Full cPanel Backup (and Restore It)
- cPanel Tutorial for Beginners
- WordPress Security Hardening Checklist
Contact SysopHost support if the database itself is missing, if the database user cannot be created, or if changing the password would affect other applications on the account and you need help coordinating the change. Include the database name, the exact error message, and the steps you have already completed. Do not include the password.