MySQL Workbench is a popular desktop tool for designing schemas, running queries and administering MySQL. The secure way to use it with a database on your VPS is “Standard TCP/IP over SSH”: Workbench connects to the server over SSH, then to MySQL on the server’s localhost. MySQL stays closed to the internet.

Why not just open port 3306?

Exposing MySQL publicly means every bot on the internet can try passwords against it and probe for vulnerabilities. With an SSH tunnel:

  • MySQL keeps listening only on 127.0.0.1;
  • authentication goes through your SSH keys first;
  • traffic is encrypted.

(For server-to-server access, see MySQL remote access.)

1. Prerequisites on the server

  • SSH access with a key — see SSH keys.
  • A MySQL user that can log in from localhost with a password. On Ubuntu, root uses socket authentication and won’t work from Workbench. Create a user:
CREATE USER 'alice'@'localhost' IDENTIFIED BY 'a-long-random-password';
GRANT ALL PRIVILEGES ON shop.* TO 'alice'@'localhost';

Also create it for 127.0.0.1 if your setup distinguishes TCP from socket connections:

CREATE USER 'alice'@'127.0.0.1' IDENTIFIED BY 'a-long-random-password';
GRANT ALL PRIVILEGES ON shop.* TO 'alice'@'127.0.0.1';

See MySQL users and privileges.

2. Create the connection in Workbench

Database → Manage Connections → New:

  • Connection Method: Standard TCP/IP over SSH
  • SSH Hostname: 203.0.113.10:22 (or your custom SSH port)
  • SSH Username: your Linux user
  • SSH Key File: path to your private key (OpenSSH format; Workbench may not accept PuTTY .ppk files — convert with PuTTYgen)
  • MySQL Hostname: 127.0.0.1
  • MySQL Server Port: 3306
  • Username: alice
  • Password: Store in Vault / Keychain

Click Test Connection.

Note that “MySQL Hostname” is resolved on the server — 127.0.0.1 means the server’s own MySQL.

3. Other clients, same idea

  • DBeaver: connection → Main tab (localhost:3306, user) + SSH tab (host, user, key).
  • HeidiSQL (Windows): Network type “MySQL (SSH tunnel)”, using plink or the built-in SSH.
  • TablePlus / Sequel Ace / DataGrip: “Over SSH” options in the connection dialog.

Or create the tunnel yourself and point any client at it:

ssh -N -L 3307:127.0.0.1:3306 [email protected]

Then connect the client to 127.0.0.1:3307. See SSH tunnels.

Troubleshooting

Failed to Connect to MySQL at 127.0.0.1:3306 through SSH tunnel … Authentication failed — the SSH part failed: wrong user, key not accepted, or a passphrase-protected key the tool can’t use. Test ssh user@host from a terminal first.

Access denied for user 'alice'@'localhost' — MySQL user/host mismatch or wrong password. Check SELECT user, host, plugin FROM mysql.user;. See error 1045.

Authentication plugin 'caching_sha2_password' cannot be loaded — an old client with MySQL 8. Update Workbench/the client; as a last resort, create the user with mysql_native_password (deprecated in 8.4).

Can't connect to MySQL server on '127.0.0.1' (111) — MySQL isn’t running or listens only on a socket (skip-networking). Check sudo ss -tlnp | grep 3306.

Workbench says the server version is unsupported — Workbench officially supports MySQL; with MariaDB, most features work but you’ll see warnings. DBeaver or HeidiSQL are good alternatives for MariaDB.

Connection drops after idle time — set SSH keepalives (ServerAliveInterval) in your SSH config, or in the client’s SSH settings.

Security tips

  • Use a database user with only the privileges you need for the task.
  • Don’t save passwords in tools on shared computers.
  • Keep MySQL bound to 127.0.0.1 — the tunnel makes remote access unnecessary.

Related: phpMyAdmin and Adminer for browser-based alternatives.

  • MySQL
  • MySQL Workbench
  • SSH