Connect MySQL Workbench to a Remote Server (over SSH or Direct)

This article is a localized edition of the Japanese original. Read the Japanese original

MySQL Workbench is the GUI administration tool published by MySQL. You install it on your own PC, connect to MySQL on a server, and use it to run SQL, design tables, manage users and more.

This article explains how to connect Workbench to MySQL on a rental server or VPS. There are two connection methods, and they differ greatly in how safe they are.

If you can log in to the server over SSH, choose the SSH method. You avoid exposing the MySQL port to the internet.

The server side was tested as of November 2026 on Ubuntu 24.04 with its standard MySQL 8.0 package. Workbench field names follow the official MySQL Workbench Manual.

Step 1: Install Workbench

Get the installer for your OS from the official MySQL download page (https://dev.mysql.com/downloads/workbench/). As of November 2026 the latest version is 26.10.0, with packages for Windows, macOS, Debian-based Linux and others. The Windows version requires the .NET Framework and the Visual C++ Redistributable (listed on the download page).

Workbench is an app for your own PC. You do not need to install it on the server you connect to.

Step 2 (recommended): Connect over SSH

Preparing the server

First confirm in a terminal that you can log in to the server over SSH.

ssh username@server-address

After logging in over SSH, Workbench connects to MySQL at 127.0.0.1 from inside the server. So create the MySQL user as a "connection from within the server."

sudo mysql

CREATE USER 'wbuser'@'localhost' IDENTIFIED BY 'strong-password';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP ON wpdb.* TO 'wbuser'@'localhost';

Replace wpdb with the database you want to work on, and grant only the privileges your work needs. In our test with MySQL 8.0 on Ubuntu 24.04, a TCP connection to 127.0.0.1 (the same thing Workbench does) was authenticated as the 'wbuser'@'localhost' account. If localhost does not match in your environment, create a 'wbuser'@'127.0.0.1' account. Privileges are explained in detail in MySQL users and privileges.

Settings in Workbench

1. On the Workbench home screen, click the "+" next to "MySQL Connections" to open "Setup New Connection."
2. Give it a recognizable name in "Connection Name."
3. Under "Connection Method," choose Standard TCP/IP over SSH.
4. Fill in the "Parameters" tab as follows.

1. Click "Test Connection," and when the success message appears, save with "OK."

The first time you connect to a server, a dialog asks you to confirm the SSH host key fingerprint. Accept it only after checking that it matches the value shown by running ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the server.

Two notes about SSH keys:

• PuTTY-format (.ppk) keys cannot be used as is. Convert them to OpenSSH format with PuTTYgen before specifying them (this is stated in the official manual).
• If your key has a passphrase, you are asked for it when connecting.

How SSH port forwarding works is explained in How to use SSH port forwarding (tunnels).

Step 3: Connect directly over TCP/IP (when SSH is not available)

Use this method when SSH is not an option, or when you connect to MySQL directly inside a corporate network. Over the internet, it assumes you can restrict access to a fixed source IP.

Make MySQL accept external connections

MySQL 8.0 on Ubuntu accepts connections only from 127.0.0.1 by default.

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

[mysqld]
# Change from 127.0.0.1 to the server's IP (or all interfaces, 0.0.0.0)
bind-address = 0.0.0.0

sudo systemctl restart mysql
sudo ss -tlnp | grep 3306

If it is listening on 0.0.0.0:3306, the change worked. For MariaDB, the configuration file is /etc/mysql/mariadb.conf.d/50-server.cnf.

Create a user limited to your source address

CREATE USER 'wbuser'@'203.0.113.10' IDENTIFIED BY 'strong-password';
GRANT SELECT, INSERT, UPDATE, DELETE ON wpdb.* TO 'wbuser'@'203.0.113.10';

Replace 203.0.113.10 with the public IP you connect from. Avoid using '%' (anywhere) as the host.

The following syntax, common in older guides, is a syntax error (ERROR 1064) in MySQL 8.0 and later.

-- Does not work in MySQL 8.0 and later (syntax up to 5.7)
GRANT ALL PRIVILEGES ON *.* TO 'user'@'%' IDENTIFIED BY 'password' WITH GRANT OPTION;

Split user creation (CREATE USER) and privilege grants (GRANT) into separate statements. Privileges changed with GRANT or CREATE USER take effect immediately, so FLUSH PRIVILEGES is unnecessary. Avoid giving a remote-access user all privileges on all databases plus WITH GRANT OPTION.

Restrict the source address in the firewall

sudo ufw allow from 203.0.113.10 to any port 3306 proto tcp
sudo ufw status

Do not use sudo ufw allow 3306, which opens port 3306 to everyone. On cloud VPSes, you may need the same restriction in the firewall outside the server (security groups and the like). For IP rules in UFW, see How to allow or deny specific IPs with UFW.

Settings in Workbench

Set "Connection Method" to Standard TCP/IP, enter the server address in "Hostname," 3306 in "Port," and the user you created in "Username."

On the "SSL" tab, "Use SSL" defaults to "If available" (encrypt if possible, otherwise connect unencrypted). For a direct connection over the internet, set it to "Require" so that it refuses to connect without encryption. MySQL 8.0 on Ubuntu creates a self-signed certificate by default, so "Require" works. To also verify the server certificate with "Require and Verify CA" or "Require and Verify Identity," prepare the CA certificate and specify it in "SSL CA File."

Troubleshooting

For server-side connection settings, see also Configuring MySQL for remote connections.

Summary

• If you can log in to the server over SSH, set Connection Method to Standard TCP/IP over SSH and MySQL Hostname to 127.0.0.1. There is no need to open port 3306 to the outside.
• For a direct connection, combine a changed bind-address, a user limited to your source IP, a firewall IP restriction, and SSL set to "Require."
• MySQL 8.0 and later do not accept GRANT … IDENTIFIED BY. Split it into CREATE USER and GRANT, and grant only the privileges you need.

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)