ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2), and its TCP cousin naming a host and port, means the client never reached a server. Nothing about passwords is involved yet; that is error 1045's territory. Error 2002 is purely “no one is there”: the MySQL service is stopped, it failed to start, it listens on a different socket or port than the client expects, or (for remote connections) the network path or bind address excludes the client.
systemctl status mysql (or mariadb), and if it is stopped or failed, read its error log (commonly /var/log/mysql/error.log) before restarting blindly; a server that failed on a full disk or a bad option will fail again the same way, and the log says which.my.cnf, PHP's mysqli.default_socket, the ORM's settings). Compare it with where the running server actually created its socket (the server's configuration and the same error log). A mismatch after an upgrade or a distribution change is a classic cause.mysql -h 127.0.0.1 -P 3306. Note that localhost in MySQL clients usually means “use the socket”, which is why 127.0.0.1 behaving differently is informative, not a contradiction.bind-address (a server bound to 127.0.0.1 cannot be reached from other machines at all) and the firewall or security group on port 3306.What is the difference between 2002 and 2003? Both are “cannot connect” client errors; 2002 is the common code for local socket failures (and is what many clients print for local TCP failures too), while 2003 (CR_CONN_HOST_ERROR) is the classic TCP variant. The troubleshooting is the same: server up, right address, right port, path open.
It broke after a server upgrade, why? Upgrades move sockets, change default paths, or the service fails to restart on a configuration option that was renamed or removed. The server error log from the upgrade moment records the exact complaint.
PHP says it, but the mysql command-line client connects fine, why? Different configuration sources: PHP has its own default socket settings (php.ini) that can point at a stale path while the command-line client reads the correct one. Align the PHP setting with the real socket path, or connect PHP via 127.0.0.1.