Fixing Database Connection Errors

Error Establishing a Database Connection

This is one of the most common WordPress errors. It means WordPress cannot connect to MariaDB. On BlitzPress, the database runs locally, so this is typically a credentials or service issue.

Step 1: Check MariaDB Service

Verify MariaDB is running:

sudo systemctl status mariadb
sudo systemctl start mariadb   # if stopped

If the service fails to start, check the MariaDB error log:

sudo tail -50 /var/log/mysql/error.log

Step 2: Verify wp-config.php Credentials

Open your site’s wp-config.php and verify these constants:

define( 'DB_NAME', 'your_database' );
define( 'DB_USER', 'your_user' );
define( 'DB_PASSWORD', 'your_password' );
define( 'DB_HOST', 'localhost' );

Test the credentials directly from the command line:

mysql -u your_user -p'your_password' your_database -e "SELECT 1;"

Step 3: Check User Permissions

If the user exists but lacks permissions, grant them:

sudo mysql -e "GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'localhost' IDENTIFIED BY 'your_password';"
sudo mysql -e "FLUSH PRIVILEGES;"

Step 4: Socket vs TCP Connection

On BlitzPress, MariaDB uses a Unix socket by default. If DB_HOST is set to localhost, PHP connects via socket. If set to 127.0.0.1, it uses TCP. Check the socket path:

mysql -e "SHOW VARIABLES LIKE 'socket';"

Ensure the socket file exists (typically /run/mysqld/mysqld.sock).

Step 5: Repair the Database

If tables are corrupted, use WP-CLI to repair:

sudo wp db repair --path=/home/YOUR_DOMAIN/public_html --allow-root

Or enable WordPress’s built-in repair tool by adding to wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then visit https://yourdomain.com/wp-admin/maint/repair.php. Remove the constant after repair.

Emergency: Reset Database Password

blitzpress db:password YOUR_DOMAIN NEW_PASSWORD

This updates both the MariaDB user and wp-config.php atomically.