MySQL GUI clients: Workbench vs DBeaver vs HeidiSQL

For most people the answer is DBeaver Community: free, runs on Windows, macOS and Linux, handles MySQL 8.4 without fuss, and the same tool works for PostgreSQL and SQL Server later. HeidiSQL is the faster, lighter choice if you are on Windows and mostly browse and edit data. MySQL Workbench is Oracle's own tool and the one to pick when you want its schema modelling and visual query plans, at the price of being slower and fussier than the others. All three connect to a remote MySQL server with the same five details - host, port, user, password and database - and fail for the same few reasons, which this post covers along with the setup for each.

What you need before you open any client#

Every client asks for the same things. Collect them first:

Use the application user, or better a separate account made for humans, rather than root. A GUI makes it very easy to run DELETE against the wrong tab, and an account that can only touch the application database limits how much one wrong click can do. MySQL users and privileges shows how to make a read-only account for browsing, which is the right default for anyone who only needs to look.

Two server-side facts about MySQL 8.4 decide whether a client connects at all:

• Authentication. Accounts use caching_sha2_password. The older mysql_native_password plugin is disabled by default in 8.4. A client built on an old client library - roughly anything older than MySQL 8.0's - cannot authenticate and fails with Authentication plugin 'caching_sha2_password' cannot be loaded. Current versions of all three clients here support it.
• TLS. The server enables TLS by default with a certificate it generates itself. Clients can encrypt with it, but cannot verify it against a public certificate authority unless you give them the server's CA file.

Check the connection from a terminal first if you can. If mysql -h db.example.com -P 3306 -u app -p app works, the server and network are fine and any GUI problem is a client setting. Connecting to MySQL remotely goes through the command-line client and SSL modes in detail.

If you have no MySQL client installed, you can still test whether the port is reachable at all, which separates network problems from account problems before any GUI is involved:

# Windows PowerShellTest-NetConnection db.example.com -Port 3306# macOS and Linux$ nc -vz db.example.com 3306

TcpTestSucceeded : True on Windows, or succeeded / open from nc, means something is listening and your network lets you reach it. A timeout means a firewall is dropping the traffic - often an office or school network that blocks unusual outgoing ports - and no client setting will help. "Connection refused" means the host answered but nothing listens on that port, which almost always means the wrong port number. Once this test passes, any remaining failure is between the client and MySQL itself, and the error table further down covers those.

The three compared#

None of the three is wrong. The trade is breadth (DBeaver), speed (HeidiSQL) or MySQL-specific depth (Workbench). Many people end up with two: HeidiSQL or DBeaver for daily work and Workbench open for the occasional ER diagram or plan.

Connecting with DBeaver#

1. Click the plug icon with a plus (New Database Connection), choose MySQL, and click Next.
2. On the Main tab set Server Host, Port, Database, Username and Password. Leave Authentication as Database Native. Tick Save password only on a machine you trust.
3. Click Test Connection. The first time, DBeaver offers to download the MySQL JDBC driver (Connector/J); accept it.
4. Click Finish. The connection appears in the Database Navigator.

DBeaver uses the Java driver, not the MySQL C library, and that driver has one error everybody meets on MySQL 8: Public Key Retrieval is not allowed. With caching_sha2_password, a client logging in over an unencrypted connection needs the server's RSA public key to send the password safely, and Connector/J refuses to ask for it unless told to. Two fixes, on the Driver properties tab:

• Encrypt the connection: set useSSL to true (and requireSSL to true if you want to insist). The password then travels inside TLS and no key retrieval is needed. This is the better fix.
• Allow key retrieval: set allowPublicKeyRetrieval to true. It works, but a machine in the middle could hand you its own key, so prefer TLS across the internet.

useSSL=truerequireSSL=trueverifyServerCertificate=falseallowPublicKeyRetrieval=false

verifyServerCertificate=false encrypts without checking who answered, which is what you get against a self-generated server certificate. If you have the server's CA certificate, use the SSL tab instead to supply it and verify. The SSH tab tunnels the connection through a server you have shell access to, which is the way to reach a database that is not exposed to the internet.

Useful habits in DBeaver: set the connection type (Edit Connection, General) to Production for live databases, which colours the editor so you know where you are and can ask for confirmation before executing statements; Ctrl+Enter runs the statement under the cursor and Alt+X the whole script; and the result viewer fetches 200 rows at a time by default, so a fast-looking query may not have fetched everything.

Connecting with HeidiSQL#

1. Open the Session manager and click New, then name the session.
2. Set Network type to the MySQL or MariaDB TCP/IP option.
3. Fill in Hostname / IP, User, Password and Port. The Databases field takes a semicolon-separated list to show; leave it blank to see everything the user can access.
4. Click Open.

On the SSL tab, tick Use SSL to encrypt the session, and supply a CA certificate if you have one for verification. The Advanced tab includes the client library HeidiSQL loads. If a session fails with caching_sha2_password cannot be loaded, switch that library to a MySQL 8 or newer libmysql from the list - older bundled libraries predate the plugin - or update HeidiSQL itself.

What HeidiSQL is good at is speed: it opens instantly, edits grid data in place, and its Tools menu has Export database as SQL, which writes a dump of chosen tables or databases to a file, another server, or the clipboard. For a large database a real mysqldump is still the safer backup - see mysqldump backup and restore - but for copying a few tables between servers HeidiSQL is hard to beat.

HeidiSQL is primarily a Windows program. People run it on Linux and macOS under Wine with mixed results; on those systems, use DBeaver.

Connecting with MySQL Workbench#

1. On the home screen, click the plus beside MySQL Connections.
2. Give it a Connection Name, keep Connection Method as Standard (TCP/IP).
3. Set Hostname, Port and Username. Click Store in Vault (Windows, macOS) or Store in Keychain (Linux) to save the password.
4. Optionally set Default Schema to your database.
5. On the SSL tab, the Use SSL setting has five values: No, If available, Require, Require and Verify CA, Require and Verify Identity. Against a remote server with a self-generated certificate, use Require; with the CA file, use Require and Verify CA.
6. Click Test Connection, then OK.

Workbench has three defaults worth knowing before they surprise you:

All three live under Edit, Preferences, SQL Editor (and SQL Execution for row limits). Safe Updates is worth keeping on - error 1175 has saved many tables. The read timeout is the one to raise if you run long reports or ALTER TABLEs from Workbench; the query was fine, Workbench simply stopped waiting.

Where Workbench earns its place: Visual Explain draws the execution plan of a query with costs, which is a good way to learn to read plans (see MySQL indexes and EXPLAIN); Database, Reverse Engineer builds an ER diagram from a live schema; and the Users and Privileges screen is a readable view of grants. Its Data Export runs a bundled mysqldump, which must be at least as new as the server - a mismatch warning there is worth heeding.

Some Workbench releases show a warning about an incompatible or non-standard server version when they connect to a newer server than they were tested with. It is a warning; you can continue, and day-to-day querying works.

The errors that stop every client#

The client changes; the causes do not.

Error 2003 versus 1045 is the most useful distinction in that table. 2003 means you never reached MySQL - a network problem. 1045 means MySQL answered and said no - an account problem. The account side is explained in MySQL users and privileges: MySQL identifies an account by user name and client host together, so 'app'@'localhost' cannot log in from your laptop however correct its password is.

Working safely from a GUI#

A graphical client changes the risk, not just the convenience. A few habits prevent most accidents:

• Separate connections for production and everything else, named and coloured differently. Most "I ran it on the wrong database" stories involve two tabs that looked the same.
• Mind autocommit. All three clients default to autocommit, but all three let you switch to manual commit. In manual mode, every UPDATE you run holds its row locks until you click Commit - and the application waits behind you. A forgotten uncommitted edit in a GUI is a classic cause of lock wait timeouts; MySQL transactions, locking and deadlocks shows how to find one.
• Grid edits are SQL. Editing a cell and saving runs an UPDATE with a WHERE built from the primary key. On a table without a primary key, some clients build the WHERE from every column, and a duplicate row means one edit changes two rows. Give every table a primary key.
• Big result sets live in your machine's memory. SELECT * FROM events on fifty million rows can freeze the client long before the server minds. Add a LIMIT while exploring.
• Close what you are not using. Each open tab may hold a connection, and idle GUI sessions count against max_connections like anything else.

Other clients worth knowing#

The three above are not the only options:

• mysql and MySQL Shell (`mysqlsh`) - the command-line clients. Always available, scriptable, and the reference for whether a connection problem is the server's or the GUI's.
• Sequel Ace - free, open source, macOS only, MySQL and MariaDB. The natural choice on a Mac if you find DBeaver heavy.
• TablePlus - native, fast, multi-database, commercial with a limited free version.
• DataGrip - JetBrains' paid database IDE, with the best SQL completion of the lot. Also built into their other IDEs as the database tool window.
• Beekeeper Studio - open-source, cross-platform, simple; a commercial edition adds features.
• phpMyAdmin and Adminer - web-based, running on a PHP host. Useful when you cannot install anything locally; they connect from the web server, not your machine. The phpMyAdmin import and export guide covers the import side.

FAQ#

Can I use MySQL Workbench with MariaDB?

It often connects, but Workbench is built for MySQL and some screens misreport or break on MariaDB as the two have diverged. HeidiSQL and DBeaver treat MariaDB as a first-class target. For a MySQL 8.4 server, all three are fine.

Why does the client connect from home but not from the office?

Either the office network blocks outgoing connections to the port, or the database account or a firewall only allows certain addresses. Error 2003 suggests the network; error 1045 or 1130 with the office address in it suggests the account's host pattern.

Is it safe to save the password in the client?

On your own encrypted machine, reasonably. Workbench stores it in the operating system's keychain; DBeaver and HeidiSQL store it in their own configuration, which is less protected. For production, consider not saving it, or using a read-only account for the saved connection.

Do I need TLS if I connect over the internet?

Yes. Without it, every query and result crosses the network in plain text, and on older authentication paths so can credentials. All three clients support TLS; turning it on is one setting.

Which client is best for importing a large SQL dump?

None of them. GUI imports load the file through the client and are slow or fail on dumps over a few hundred megabytes. Use the command-line client: mysql -h host -P port -u user -p dbname < dump.sql.