MySQL localhost Over a VPN: It Still Means the Local Process

The application on the office server connects to MySQL at localhost, you copy that hostname into a desktop client, and the connection either fails or opens a different database. Nothing about the VPN changed the word's meaning: localhost still refers to whichever machine runs the client. The VPN moved packets, not interfaces. Decide which endpoint the laptop should reach before you touch a route.

Step 1: decide which endpoint the laptop should reach

Two designs are legitimate and they answer different questions. Direct access means the database listens on a private address the tunnel can reach, and the laptop connects to that address. Forwarded access means the database stays on loopback and an SSH session carries the port to your machine. Pick one deliberately, because mixing them produces a connection that works for the wrong reason.

For direct access, get the database host's own private name or address and its port from whoever runs it. The VPN gateway's address is not the database address unless they are the same machine. Then confirm the listener is actually bound to that interface, because a route to an interface does not create a listener on it.

Step 2: forward the port only if the listener stays local

If the database should remain loopback-only, forward it over SSH and bind the local end to loopback as well. The bind address on the left belongs to your laptop; the target on the right is interpreted from the SSH server's side, as the OpenSSH reference describes. Getting those two roles backwards is the usual reason a forward appears to work but connects to nothing.

ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:13306:127.0.0.1:3306 [email protected]
ss -ltn 'sport = :13306'

If SSH lands on a jump host rather than the database host, the right-hand loopback refers to the jump host, and the target has to change to an address that host can reach. ExitOnForwardFailure catches a failure to establish the forward, but it does not prove that later connections to the target succeed. Keep host-key checking on, and do not offer the forwarding port to your whole LAN by binding it to all interfaces.

Stop if the database must stay loopback-only and you cannot use SSH. Direct access is then the wrong design, not a configuration to force.

Step 3: force the client onto TCP

On Unix, a MySQL client given localhost selects a Unix socket by default, so changing only the port can leave it looking for a socket that has nothing to do with your forward. Use the explicit TCP protocol and the loopback address to make the client open a connection to your forwarding port.

mysql --protocol=TCP --host=127.0.0.1 --port=13306 --user=DB_USER --password

The password option without a value prompts instead of putting the secret in the command line, which is the habit worth keeping. Other tools have their own switch for the same distinction, and some drivers treat localhost specially as well. Check what your client does rather than assuming the flag carried over. The database account also needs a grant that matches the source the server sees, which is the forwarding host rather than your laptop.

Stop if the tool cannot be forced onto TCP. Then use a different client, or use direct access to the private listener.

Step 4: prove which endpoint you actually reached

Ask the server what it thinks the connection is. The hostname, port and socket variables tell you whether you arrived over TCP and which listener answered, and the connection list shows the source address the server recorded. That evidence is more useful than another route change.

mysql --protocol=TCP -h 127.0.0.1 -P 13306 -u DB_USER -p -e "SELECT @@hostname, @@port, @@socket"

Record which endpoint you attempted: a local Unix socket, your forwarding port or the private listener. Those three failures have different fixes, and changing the VPN route while the client is still talking to the wrong localhost is wasted effort. Keep SSH authentication and database authentication separate in the notes as well, because a failure in one looks like a failure in the other from a desktop client. Then remove the forward when you are done with it.

The checklist ends when you can name the endpoint, the client protocol, the source address the server saw and the grant that allowed it. Four facts, and the next connection problem takes minutes instead of an afternoon.