MySQL Workbench is a graphical client for working with databases that saves time when typing every SQL query by hand in a terminal is not appealing. This article explains what the program is, how to connect it to a remote database on a VDS, and what to do when the connection window does not open.
What MySQL Workbench is
MySQL Workbench is the official graphical tool for designing databases, writing SQL queries, and administering MySQL and MariaDB servers. Instead of a text console, the user sees a list of tables, can edit rows in a spreadsheet-like view, and build diagrams of relations between tables with a mouse rather than describing foreign keys by hand.
The program works as an ordinary desktop client on the user's computer and opens a connection to the database server the same way any application does: over the network, to the MySQL server's port. The database itself stays on the server — Workbench only displays and changes the data remotely.
Connection methods Workbench supports
Before the first connection it is worth deciding on the way to reach the server.
- Direct TCP connection — Workbench reaches the open MySQL port on the server directly.
- Connection over an SSH tunnel — traffic to the database travels through an encrypted channel, and the MySQL port is not exposed outside.
- Local socket — used only when Workbench runs on the same server as the database.
- Saved connection file — connection parameters are imported from a saved settings file.
Comparing connection methods by security
For remote access a tunnel is safer than an exposed port, and it is worth knowing this before setting anything up.
| Method | Port exposed | Encryption | When it fits |
|---|---|---|---|
| direct TCP connection | port 3306 open | depends on server SSL settings | trusted internal network |
| SSH tunnel | only port 22 open | all traffic encrypted by SSH | connecting from any location |
| local socket | nothing exposed | not needed, traffic never leaves the server | working right on the server |
| VPN into the server network | MySQL port closed to the internet | encryption at the VPN layer | office or team infrastructure |
Detailed recommendations for closing port 3306 to outside connections are given in the article about MySQL security on a VPS.
How to set up a connection over an SSH tunnel
The most common working scenario is connecting to a remote database without exposing the MySQL port outside.
# In Workbench: New Connection
# Connection Method: Standard TCP/IP over SSH
# SSH Hostname: your-server.example.com, SSH Username: your-login
# MySQL Hostname: 127.0.0.1, MySQL Server Port: 3306In this mode Workbench first opens an ordinary SSH connection to the server, then lays a separate channel inside it to the local MySQL port on that same server. From the outside only the open SSH port is visible, and the database port stays unreachable for direct connections from the internet.
What to do when Workbench will not open or connect
- Check that the mysqld process is actually running on the server, not just listening for connections locally.
- Make sure the database user has permission to connect from the needed host, not only from localhost.
- Check the firewall rule on the server: port 3306 or 22 must be open for the client's IP address.
- If the Workbench window itself will not launch on the computer, check the application logs and try reinstalling the connector drivers.
- For a one-off connection test, use the console mysql client with the same parameters — it quickly shows whether the problem is in the network or in Workbench itself.
The correct privileges for the user that will connect through Workbench are described in the article about MySQL user privileges, and general principles for protecting MariaDB and MySQL are in the article about MariaDB and MySQL security.
Frequently asked questions
What is MySQL Workbench and how does it differ from phpMyAdmin?
MySQL Workbench is a desktop application installed on the user's computer, while phpMyAdmin is a web interface that runs through a browser and is installed on the server. The capabilities are largely similar, but Workbench is more convenient for designing schemas and working without constant access to a web panel.
Why is MySQL Workbench not opening after installation?
The most common cause is a conflict between library versions on the computer or a corrupted settings file from a previous installation. Reinstalling the program while removing the old configuration folder, or launching it from a terminal to see the error text in the console, usually helps.
Can a database be reached without SSH access to the server?
Yes, if the server has the MySQL port open outside and the database user is allowed to connect from the client's IP address, but that option is less secure than a tunnel. For a one-off task it is acceptable if access is limited in advance to a specific IP address in the firewall settings.