Cannot connect to a fresh brew install of mysql from a client on the same host

When a fresh Homebrew MySQL installation fails to accept local connections, the issue is typically caused by the server binding exclusively to IPv6 or running under a different user context that restricts socket permissions. Verify the network configuration and ensure the client uses the correct Unix socket path located in /tmp or /usr/local/var/mysql.

Understanding the Localhost Binding Behavior

MySQL on macOS installations managed by Homebrew often defaults to binding to the loopback interface. However, modern versions may prioritize IPv6 addresses for localhost connections. If your client attempts to connect via 127.0.0.1 but the server is only listening on ::1, the connection will fail silently or with a timeout error. This discrepancy is common in environments where network stacks handle IPv4 and IPv6 differently. You must confirm which address family the server is actually accepting connections on before troubleshooting permission issues.

Checking Network Bindings

To determine if the server is listening correctly, you can inspect the active ports. Use the lsof command to list open files associated with the MySQL process. Specifically, look for entries related to TCP ports 3306. If you see IPv6 listed instead of IPv4, this confirms the binding preference. The output should show the server PID and the specific address it is bound to. This diagnostic step helps isolate whether the problem is network-level or authentication-related.

Verifying Socket Permissions and Paths

The most frequent cause of connection failures on a fresh install is an incorrect Unix socket path. MySQL clients default to looking for a socket file in /tmp/mysql.sock or /var/mysql/mysql.sock. Homebrew, however, often places this file in /tmp/mysql.sock or within the Cellar directory depending on the version. If the client cannot find the socket, it throws a "Can't connect to local MySQL server through socket" error. You need to locate the actual socket file created by the service.

1. Start the MySQL service using brew services start mysql.
2. Run ls -l /tmp/mysql.sock to check existence.
3. If missing, check /usr/local/var/mysql/ for any .sock files.
4. Specify the correct path in your client command using --socket.

This manual specification bypasses the default search path and forces the client to use the correct endpoint. It is a quick fix that validates whether the server is running and accessible at all.

Adjusting Client Configuration

You can make this change permanent by editing your my.cnf file. Add the [client] section and define the socket variable pointing to the correct location. This ensures that all future client commands, including those from scripts, use the right path without manual intervention. Without this configuration, every new terminal session might require explicit socket arguments.

Addressing User Context and Permissions

Homebrew runs services under your current user account by default, unlike system-wide installations that run as _mysql. This difference affects file permissions significantly. If you installed MySQL using a different user or switched accounts, the socket file might be owned by a user who lacks read/write access for the current shell. Additionally, firewall settings on macOS can block incoming connections even if they are local. While less common for localhost traffic, it is worth verifying that no security software is intercepting the loopback interface.

Restarting Services Correctly

After making changes to configuration files, you must restart the service for them to take effect. Use brew services restart mysql to apply new bindings or socket paths. Failure to restart often leads to confusion where the old configuration remains active. Always check the logs in /usr/local/var/mysql/ for errors during startup. These logs provide detailed information about why the server might have refused connections or failed to bind to the expected address.

Troubleshooting Authentication Issues

If the network and socket paths are correct, the next hurdle is authentication. Fresh installs often create a root user with auth_socket plugin, which allows login only via Unix socket and requires matching OS user credentials. If you try to connect with a password, it will fail because the socket method ignores passwords. Conversely, if you switch to password authentication, you must set a password first. Understanding this distinction prevents unnecessary network debugging when the issue is purely credential-based. Fixing Perl Dependency Error During MySQL Installation on Rocky Linux 9.4 in Oracle VirtualBox discusses similar installation pitfalls regarding dependencies, though on a different OS. While the platform differs, the principle of verifying installation integrity applies here as well. Ensuring that all underlying components are correctly configured prevents cascading failures.

Ensuring Service Persistence

A fresh install might not persist across reboots if not properly configured. Homebrew provides a launch agent setup that handles this automatically. Ensure that brew services start mysql was executed successfully. If the service stops unexpectedly, check the console logs for crash reports. Persistent connectivity requires the daemon to remain active and responsive to local requests. SQL Server Access Linux SQLCMD: Login Timeout Expired, TCP Provider: Error Code 0x2AF9 highlights timeout issues in database connections. Although unrelated to MySQL, the concept of timeouts applies when servers are unresponsive due to configuration errors. Recognizing timeout symptoms helps distinguish between network blocks and server-side failures.

Frequently Asked Questions

Why does my MySQL client fail with a timeout error?

This usually indicates that the server is not listening on the IP address your client is targeting. Check if MySQL is bound to IPv6 while your client uses IPv4, or verify that the service is actually running. Adjusting the bind-address in my.cnf can resolve this mismatch.

How do I find the correct Unix socket path?

Use the find command to search for *.sock files in your Homebrew prefix or /tmp. Alternatively, query the running MySQL instance using mysqladmin variables if you can connect via a known good path. The socket variable in the output reveals the exact location.

Can I connect using 127.0.0.1 instead of localhost?

Yes, specifying 127.0.0.1 forces TCP/IP connection rather than Unix socket usage. This bypasses socket permission issues but requires the server to listen on IPv4. Ensure skip-networking is not enabled in your configuration for this to work.

What causes auth_socket errors after a fresh install?

The root user is often configured to authenticate via the operating system user via socket. This means you cannot log in with a password unless you change the authentication plugin. Switching to mysql_native_password allows standard password-based logins for remote or scripted access.

Is it safe to disable the macOS firewall for MySQL?

Disabling the firewall entirely is not recommended for security reasons. Instead, configure specific exceptions for MySQL ports if remote access is needed. For local connections, the firewall rarely interferes unless third-party security software is present. Test connectivity with the firewall disabled temporarily to isolate the cause.