- Open the session manager, click New, keep the network type "MariaDB or MySQL (TCP/IP)", enter host, user, password and port 3306, then click Open.
- Defaults for a new MySQL session are user root and port 3306; the password is the field you almost always need to fill in.
- For a server reachable only over SSH, choose the "MariaDB or MySQL (SSH tunnel)" network type and fill in the SSH tunnel tab, using 127.0.0.1 as the MySQL host.
- TLS is set on the SSL tab: tick Use SSL, add key, certificate and CA files if needed, and pick a certificate verification level.
- On Windows the installer bundles libmariadb and several libmysql versions; on Linux the client library comes from your distribution.
HeidiSQL MySQL connection: step by step
HeidiSQL is a client, so you need a running MySQL or MariaDB server and an account on it. The help page describes the simplest case, a server on localhost (127.0.0.1), where most defaults are already set and you only add the password:
- Start HeidiSQL; the Session manager opens (later you can reopen it from File > Session manager).
- Click New to create a session and give it a name.
- On the Settings tab, set Network type to MariaDB or MySQL (TCP/IP).
- Enter Hostname / IP, User, Password and Port (3306 by default).
- Optionally list Databases separated by semicolons to limit the tree; if empty, HeidiSQL shows every database you can access.
- Click Save, then Open.
Other options on the Settings tab include Prompt for credentials (ask for user and password each time), Use Windows authentication (MySQL, MariaDB and SQL Server only) and Compressed client/server protocol, which the help page recommends only on slow networks or for large result sets.
| Network type | Use it for |
|---|---|
| MariaDB or MySQL (TCP/IP) | Direct connection to a host and port |
| MariaDB or MySQL (SSH tunnel) | A server reachable only through an SSH host |
| MariaDB or MySQL (named pipe) | A local Windows server listening on a named pipe |
| MySQL on RDS | Amazon RDS for MySQL (SSH tunnel also available) |
| ProxySQL Admin (Experimental) | The ProxySQL admin interface (default port 6032) |
Client library: libmariadb or libmysql
HeidiSQL needs a client library to talk to the server. The Library drop-down defaults to libmariadb.dll for MySQL-family sessions. The Windows installer ships all the libraries you may need, including libmariadb.dll, libmysql.dll, libmysql-8.4.0.dll and libmysql-9.4.0.dll, so you can switch to a MySQL client library if the default one does not suit your server. On Linux the version does not ship these libraries; install libmariadb-dev or libmysqlclient-dev from your distribution (the DEB package depends on one of them).
Connecting through an SSH tunnel
If MySQL listens only on the remote machine, choose the MariaDB or MySQL (SSH tunnel) network type and open the SSH tunnel tab. On Windows the installer places plink.exe in the program folder for you to select as the SSH executable; recent versions can also use Microsoft's OpenSSH ssh.exe. The help page gives these example settings:
- Settings tab: Hostname
127.0.0.1, your MySQL password, port 3306. - SSH tunnel tab: SSH host = your server name, port 22, your SSH user and password (or a Private key file), and a free Local port such as 3307.
The host on the Settings tab is used as the target of the tunnel's -L forwarding, so it must be the address of MySQL as seen from the SSH server. The help page explains that the error "Lost connection to MySQL server at 'reading initial communication packet'" is mostly caused by tunnelling to the server's public IP; use 127.0.0.1 in Settings and the remote address in the SSH host field. One security note from the source code: when you use OpenSSH rather than plink, HeidiSQL adds -o StrictHostKeyChecking=no, so the SSH host key is not checked.
Enabling SSL/TLS
The SSL tab applies to MySQL-family and PostgreSQL sessions. Tick Use SSL, then fill in what your server requires: SSL private key, SSL certificate, SSL CA certificate and SSL cipher. Certificate verification has three levels: No verification (insecure), Verify CA (insecure) and Verify CA and host name identity, which the dialog warns may fail with self-signed certificates and wildcard names. With a libmysql library HeidiSQL maps these to MySQL's preferred, verify-CA and verify-identity SSL modes. For a managed cloud server, download the provider's CA file and use the strictest level that works.
Common HeidiSQL MySQL connection problems
- Access denied. Wrong user, password or host permission on the MySQL side. A freshly installed server usually has a non-empty root password.
- Can't connect / connection refused. Check host, port and firewall; for remote servers consider the SSH tunnel type.
- Lost connection at 'reading initial communication packet' through SSH: use 127.0.0.1 as the Settings host, as above.
- Authentication plugin issues. Try another client library from the Library list; for servers that need it, the Advanced tab has Enable cleartext authentication (MySQL 5.5.47 and later), which sends the password in clear text and should only be used over SSL or SSH.
Our error library currently covers SQL Server errors; for those, see the SQL error library.
Frequently asked questions
What is the default port for a HeidiSQL MySQL connection?
3306 for MariaDB and MySQL sessions (6032 for ProxySQL Admin). Change it on the Settings tab if your server listens elsewhere.
How do I connect HeidiSQL to MySQL over SSH?
Choose the network type MariaDB or MySQL (SSH tunnel), set Hostname to 127.0.0.1 on the Settings tab, and enter the SSH host, port, user and password or key file on the SSH tunnel tab.
Can HeidiSQL connect to MariaDB?
Yes. MariaDB and MySQL share one network type, and the default client library on Windows is libmariadb.
Can I connect from the command line?
Yes. The help page documents switches such as -h, -u, -p and -P, and -d to open a saved session by name.
Does HeidiSQL support MySQL on Amazon RDS?
Yes, there is a "MySQL on RDS" network type, which can also use an SSH tunnel. See AWS RDS for the server side.
Sources
- HeidiSQL help: connecting to a server, SSH tunnel, command line
- HeidiSQL home page (features)
- HeidiSQL source: session manager form (connections.dfm)
- HeidiSQL source: session manager logic (connections.pas)
- HeidiSQL source: connection defaults and SSH command (dbconnection.pas)
- HeidiSQL Windows installer script (bundled libraries)
Checked 8 October 2026.
How we research tool guides: our editorial method. CodeWithSQL earns nothing from the vendors mentioned.