MySQL Workbench requires an SSH key in OpenSSH format to authenticate with remote database servers. PuTTY uses its own proprietary .ppk format, which is incompatible with the standard SSH client libraries used by Workbench. You must convert your existing PuTTY private key into the OpenSSH format using the command-line tool provided with PuTTY.
The conversion process involves locating the
puttygen.exe utility within your PuTTY installation directory and running a specific command to transform the key file. This operation does not require you to regenerate the key or modify your server configuration; it simply changes the container format so that MySQL Workbench can read and use it for secure connections.
Locating the Conversion Tool
Before you can begin the conversion, you need to find the correct executable on your Windows machine. The tool required is called
puttygen, which stands for PuTTY Key Generator. This tool is typically installed alongside the main PuTTY application.
By default, the program is located in the
C:\Program Files\PuTTY\ directory. If you installed PuTTY in a custom location, navigate to that folder instead. You are looking specifically for
puttygen.exe. If you cannot find this file, ensure that you have the full suite of PuTTY tools installed, as sometimes only the basic
plink.exe or
putty.exe components are selected during a minimal installation.
Executing the Conversion Command
The most reliable method to convert the key is via the Command Prompt or PowerShell. Graphical interfaces can sometimes be confusing regarding path handling, so using the command line ensures accuracy.
Open your terminal and navigate to the directory containing your
.ppk file if it is not already there. Then, execute the following command structure:
puttygen.exe "C:\Path\To\Your\Key.ppk" -O private-openssh -o "C:\Path\To\New\Key.pem"
Replace the paths with your actual file locations. The argument
-O private-openssh specifies the output format as OpenSSH compatible private key. The
-o flag defines the output filename. It is common practice to save the new key with a
.pem or
.key extension to distinguish it from the original PuTTY format.
If you encounter permission errors, ensure you are running the command prompt with appropriate access to write to the destination folder. The resulting file will be a plain text file containing the private key in the standard OpenSSH format.
Configuring MySQL Workbench
Once you have successfully generated the OpenSSH formatted key, you need to update your connection settings in MySQL Workbench. Open the application and go to the
Database menu, then select
Manage Connections.
Select the connection profile that connects to your remote Linux MySQL server. Click on the
Connection tab. In the
SSH section, locate the field labeled
Private Key File. By default, this might be empty or pointing to an old key.
Click the browse button next to the Private Key File field and navigate to the new
.pem or
.key file you created in the previous step. Ensure that the
Use SSH Tunneling checkbox is enabled. This tells Workbench to route the MySQL traffic through the SSH tunnel established by the key authentication.
After selecting the key, click
Test Connection. Workbench will attempt to log in to the remote host using the new key format. If successful, you will see a confirmation message indicating that the connection was established.
Troubleshooting Common Issues
Sometimes the conversion works, but the connection still fails. There are a few critical checks to perform if you do not get immediate success.
First, verify the permissions of the new key file on your local Windows machine. While less strict than Linux, some SSH implementations may reject keys that are world-readable. Right-click the file, go to Properties, and ensure that only your user account has full control.
Second, check the username. In MySQL Workbench, under the
General tab, ensure the
Username field matches the Linux user account associated with the SSH key. A mismatch here will cause authentication to fail even if the key is correct.
Third, consider encryption algorithms. Older versions of OpenSSH may not support certain key types. If your original PuTTY key was generated with a very old algorithm, you might need to specify the type explicitly during conversion, though the default command usually handles modern standards correctly.
For more complex network issues, such as timeouts or routing problems, you might want to review related troubleshooting guides. For instance, if you are using WSL or Vagrant environments, connectivity issues can stem from host networking configurations rather than key formats. You can explore solutions for these scenarios in our guide on
Troubleshooting SSH WSL Machine: Can't Connect to Localhost or check
Vagrant Fails to Connect to SSH on Linux Host, Works Fine on Windows Host if you are dealing with virtualized environments.
Verifying the Key Content
You can visually inspect the converted key to ensure it looks correct. Open the new
.pem file in a text editor like Notepad. It should start with
-----BEGIN OPENSSH PRIVATE KEY----- and end with
-----END OPENSSH PRIVATE KEY-----.
If it starts with
-----BEGIN RSA PRIVATE KEY-----, the conversion did not produce the OpenSSH format required by newer versions of MySQL Workbench. In this case, repeat the conversion command and double-check the
-O parameter. The OpenSSH format is distinct from the traditional PEM/RSA format and is necessary for compatibility with modern SSH clients integrated into database tools.
Frequently Asked Questions
Can I use the graphical Puttygen interface instead of the command line?
Yes, you can open
puttygen.exe directly, load your
.ppk file, and select
Conversions >
Export OpenSSH key from the menu. However, the command line is often faster for batch operations and avoids GUI dialog errors.
Do I need to reinstall PuTTY after converting the key?
No, the conversion creates a new file without modifying your existing PuTTY installation or registry entries. Your original
.ppk file remains unchanged and usable for other applications like standard PuTTY sessions.
What if my MySQL server requires root login via SSH?
Most secure Linux distributions disable root SSH login by default. You should create a dedicated user for database administration and use that username in MySQL Workbench. If root is absolutely required, you must enable it in
/etc/ssh/sshd_config on the server, which is generally discouraged for security reasons.
Why does MySQL Workbench still ask for a password after I set the key?
This usually indicates that the key is not loaded correctly or the passphrase is missing. If your private key was protected with a passphrase when created, you must enter that passphrase in the Workbench dialog box. Alternatively, check if the key file path contains spaces and ensure it is properly quoted in any scripts you might be using.
Is the converted key safe to share?
Never share your private key file. Anyone with access to the
.pem or
.key file can authenticate as the associated user on the remote server. Treat it with the same security precautions as your original
.ppk file.