How a MariaDB Upgrade Took Down Every WordPress Site on the Server

A client messaged me on a Friday afternoon — the kind of message that makes your stomach drop. "All our sites are down." Not one WordPress site. Every single one on the server. Forty-seven sites, all returning the same white page: "Error establishing a database connection."

The server was a WHM/cPanel box running MariaDB 10.5. The hosting company had pushed a MariaDB upgrade to 10.11 during a maintenance window. MariaDB was running. MySQL connections from the command line worked fine. But every WordPress site was dead.

Here's what went wrong and how I fixed it.

The First Problem: Socket Path Mismatch

When WordPress uses localhost as DB_HOST in wp-config.php, PHP doesn't connect over TCP/IP. It uses a Unix socket — a file on the filesystem. The location of that socket file is the first thing that breaks during a MariaDB major version upgrade.

I checked where MariaDB was actually listening:

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

+---------------+---------------------------+
| Variable_name | Value                     |
+---------------+---------------------------+
| socket        | /var/lib/mysql/mysql.sock  |
+---------------+---------------------------+

That looked normal for cPanel. But PHP was looking elsewhere. I checked the PHP configuration:

php -i | grep mysql.default_socket

mysqli.default_socket => /var/run/mysqld/mysqld.sock

There it was. MariaDB 10.11 had placed the socket at /var/lib/mysql/mysql.sock, but PHP's compiled default still pointed to /var/run/mysqld/mysqld.sock. Before the upgrade, both paths had been symlinked or matched. After the upgrade, the symlink was gone.

The quick fix was to create the symlink:

mkdir -p /var/run/mysqld
ln -s /var/lib/mysql/mysql.sock /var/run/mysqld/mysqld.sock
chown mysql:mysql /var/run/mysqld

But that's a band-aid. The proper fix is to align the configurations. I added the socket path to /etc/my.cnf.d/server.cnf:

[mysqld]
socket=/var/lib/mysql/mysql.sock

[client]
socket=/var/lib/mysql/mysql.sock

And updated the PHP-FPM pool config to use the correct socket path by setting mysqli.default_socket in the relevant php.ini:

mysqli.default_socket = /var/lib/mysql/mysql.sock
pdo_mysql.default_socket = /var/lib/mysql/mysql.sock

After restarting PHP-FPM, about 30 of the 47 sites came back online. The remaining 17 had a different problem.

The Second Problem: Authentication Plugin Change

Starting with MariaDB 10.4, the default authentication method for the root user changed from mysql_native_password to unix_socket. This means the root database user authenticates based on the operating system user, not a password.

That's fine for command-line access as root. It's a problem for PHP running as the nobody or www-data user, which obviously isn't root.

On this server, a few legacy sites were still configured to connect using the root MySQL user (don't do this, but it happens). After the upgrade, their password-based authentication stopped working entirely.

I checked the authentication method for affected users:

SELECT user, host, plugin FROM mysql.user WHERE user = 'root';

+------+-----------+-------------+
| user | host      | plugin      |
+------+-----------+-------------+
| root | localhost | unix_socket |
+------+-----------+-------------+

For the sites that genuinely needed root access (temporarily, while I created proper per-site users), I re-enabled password authentication:

ALTER USER 'root'@'localhost' IDENTIFIED VIA mysql_native_password USING PASSWORD('secure_password_here');
FLUSH PRIVILEGES;

But the real fix was creating dedicated database users for each WordPress site — which they should have had all along:

mysql -u root <<EOF
CREATE USER 'wp_sitename'@'localhost' IDENTIFIED BY 'strong_random_password';
GRANT ALL PRIVILEGES ON wp_sitename_db.* TO 'wp_sitename'@'localhost';
FLUSH PRIVILEGES;
EOF

Then updating each site's wp-config.php to use the new credentials. For 17 sites, I scripted it with a loop over the cPanel account list, but the principle is straightforward.

The Third Problem: Collation Warnings

Once the sites were back online, WordPress Site Health on several of them started showing warnings about database collation. MariaDB 10.6 renamed the utf8 character set to utf8mb3 to clarify the distinction from utf8mb4. By MariaDB 10.11, the old utf8_general_ci collation references were generating deprecation warnings.

WordPress handles this reasonably well — it added utf8mb3_bin and utf8mb3_general_ci to its list of safe collations. But some older tables still had the legacy collation explicitly set, causing warnings in the logs:

[Warning] '127.0.0.1' collation utf8_general_ci is a legacy collation

I converted the affected tables to utf8mb4 using WP-CLI across all sites:

wp db query "ALTER TABLE wp_options CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" --path=/home/account/public_html

For a bulk conversion of all tables on a site:

wp db query "SHOW TABLES;" --path=/home/account/public_html | tail -n +2 | while read table; do
  wp db query "ALTER TABLE $table CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" --path=/home/account/public_html
done

After converting, I ran a WordPress database update to ensure everything was consistent:

wp core update-db --path=/home/account/public_html

The Hidden Fourth Problem: SELinux

Three sites on a separate AlmaLinux 9 server with CloudPanel had the same MariaDB upgrade applied, but the socket fix didn't help. Connections to localhost were refused, but 127.0.0.1 worked fine.

The culprit was SELinux. After the MariaDB upgrade, the socket file was created with a different SELinux context. PHP-FPM (running under httpd_t) couldn't access a socket owned by unconfined_service_t.

I confirmed it by checking the audit log:

ausearch -m AVC -ts recent | grep mysql

type=AVC msg=audit(...): avc:  denied  { connectto } for  pid=12345 comm="php-fpm" path="/var/lib/mysql/mysql.sock" scontext=system_u:system_r:httpd_t:s0 tcontext=system_u:system_r:unconfined_service_t:s0 tclass=unix_stream_socket permissive=0

The fix was to restore the correct SELinux context on the socket:

semanage fcontext -a -t mysqld_var_run_t "/var/lib/mysql/mysql.sock"
restorecon -v /var/lib/mysql/mysql.sock

And to make sure MariaDB's systemd service was running under the correct SELinux domain:

systemctl daemon-reexec
systemctl restart mariadb

The Pre-Upgrade Checklist I Now Use

After this incident, I built a checklist that I run before every MariaDB upgrade on any server I manage:

1. Record the current socket path: mysql -u root -e "SHOW VARIABLES LIKE 'socket';"
2. Record PHP's expected socket: php -i | grep mysql.default_socket
3. Dump all user authentication methods: SELECT user, host, plugin FROM mysql.user;
4. Check for legacy collations: SELECT table_name, table_collation FROM information_schema.tables WHERE table_schema NOT IN ('mysql','information_schema','performance_schema') AND table_collation LIKE 'utf8_%';
5. Full database dump: mysqldump --all-databases --routines --triggers > /root/pre-upgrade-$(date +%F).sql
6. Note the current MariaDB version: mysql -V
7. Check SELinux status: getenforce
8. Put all WordPress sites in maintenance mode: for dir in /home/*/public_html; do wp maintenance-mode activate --path="$dir" 2>/dev/null; done

After the upgrade, I reverse through the list — verify socket paths match, test a connection from PHP, check authentication works for each database user, and bring sites out of maintenance mode one by one.

MariaDB Version Support — Know Your Timeline

If you're still running MariaDB 10.5 or older, you're on borrowed time. MariaDB 10.5 reaches end of life in July 2026. The currently recommended minimum for WordPress hosting is MariaDB 10.6, and the latest LTS release is MariaDB 11.8.

The upgrade from 10.x to 11.x is a bigger jump than minor version bumps. Plan it, test it in staging, and don't let your hosting provider surprise you with it on a Friday afternoon.

The Takeaway

A MariaDB upgrade should be routine. But "routine" doesn't mean "safe to ignore." Socket paths change, authentication defaults shift, character sets get renamed, and SELinux policies break. Any one of these can take down every WordPress site on a server simultaneously.

The fix for each individual issue is straightforward — once you know what to look for. The hard part is diagnosing which of the four problems (or which combination) you're dealing with when all you see is "Error establishing a database connection" across 47 sites.

This is exactly the kind of invisible maintenance work that keeps WordPress sites running. If you'd rather not debug MariaDB socket paths on a Friday evening, I get it.

---

Stop Firefighting. Start Maintaining.

I manage 70+ WordPress sites for UK agencies and businesses. Whether you need ongoing maintenance, emergency support, or a one-off performance fix — I can help.

View Maintenance Plans → Get in Touch →