CloudLinux: database connection error when using "localhost" as the database host

Symptoms

Sites that use localhost as the database host will encounter database connection errors while switching to 127.0.0.1 allows for a successful connection.

Cause

Scripts will try to connect to the Unix socket if configured to connect to localhost. They try to connect to the network socket if configured to connect to 127.0.0.1 or another IP address. The socket a script connects to doesn't matter unless CageFS is used. CageFS restricts what resources users have access to. If CageFS isn't configured to allow access to the folder the mysql.sock file is in, scripts attempting to connect to the MySQL Unix socket will encounter connection errors.

Resolution

1. Access the server's command line as the 'root' user via SSH or "Terminal" in WHM.
2. Open /etc/my.cnf in your preferred text editor.

3. Ensure that the datadir and socket entries exist and have the correct values.

   CONFIG_TEXT: datadir=/var/lib/mysql
   socket=/var/lib/mysql/mysql.sock

   Note: Please note that the above values are the default values and must be replaced with the values specific to your server.

4. Save the changes and exit the text editor.

5. Restart the mysqld service if changes were made to /etc/my.cnf.

   # /usr/local/cpanel/scripts/restartsrv_mysql

6. Open /etc/cagefs/cagefs.mp in your preferred text editor.

7. Ensure that the /var/lib/mysql entry exists.

   Note: Please note that if the MySQL socket file is not in the default folder, replace the path /var/lib/mysql with the folder the socket file is located in.

8. Save the changes and exit the text editor.

9. Remount and update CageFS for all users.

   # cagefsctl -M

   # cagefsctl --force-update

Additional resources

CloudLinux OS components: CageFS

How to edit a file on command-line