Websites
Connecting To Your Database Over an SSH Tunnel
Your site's MySQL server only listens on the server's own loopback address, so a desktop tool such as TablePlus, Sequel Ace, DBeaver or MySQL Workbench cannot dial it directly. An SSH tunnel gives those tools a local port that is forwarded to the database, which is how you get a proper GUI onto your data without opening MySQL to the internet.
Why a Tunnel Is Needed
Open Websites, click the site, then Files, then Database. The Connection details card shows the host as 127.0.0.1 and the port as 3306. That is not a placeholder: the database genuinely only accepts connections from the machine it runs on. Nothing on the public internet can reach port 3306, which removes an entire class of attack.
An SSH tunnel closes that gap safely. Your SSH client opens a port on your laptop, encrypts everything you send to it, and hands it to the database from inside the server, exactly as if a local process had connected.
What You Need First
A tunnel is an SSH connection, so you need an SSH key registered against the site before any of this works. Follow Adding SSH Keys To a Site first, then come back here.
Collect four things:
- SSH host, port and username, from Files, then SSH Keys, in the Connection details card.
- Database name, username and password, from Files, then Database. Click the eye icon to reveal the password and the copy icon to put it on your clipboard.
If the Database tab says No database provisioned for this site type, this site does not have one. Static sites and some Node.js sites are created without a database.
Opening the Tunnel From a Terminal
The general shape is: forward a local port to 127.0.0.1:3306 on the far side of the SSH connection.
ssh -N -L 3307:127.0.0.1:3306 <ssh-username>@<ssh-host> -p <ssh-port>
-L 3307:127.0.0.1:3306opens port 3307 on your machine and forwards it to port 3306 on the server's loopback interface.-Nsays do not run a shell, just hold the tunnel open.- Add
-i /path/to/keyif the key for this site is not your default one.
Leave that terminal window running. While it is open, 127.0.0.1:3307 on your laptop is the site's database.
Use 3307 locally rather than 3306. If you have MySQL or MariaDB installed on your own machine it is already using 3306, and the tunnel will fail to bind with an "address already in use" error. Any free local port works.
Pointing Your Database Client At the Tunnel
In your GUI client, create a plain MySQL connection with these values:
| Field | Value |
|---|---|
| Host | 127.0.0.1 |
| Port | 3307 (whichever local port you forwarded) |
| User | The Username from the Database tab |
| Password | The Password from the Database tab |
| Database | The Database name from the Database tab |
Do not put the SSH host in the Host field. As far as the client is concerned it is talking to a database on your own machine.
Clients With a Built-In SSH Tab
TablePlus, Sequel Ace, DBeaver and MySQL Workbench can all manage the tunnel themselves, which saves keeping a terminal open. Fill in two groups of fields:
- SSH section: host, port, username and private key file from the SSH Keys page.
- Database section: host
127.0.0.1, port3306, plus the database name, user and password from the Database tab.
When the client makes the tunnel, use 3306 in the database section rather than your local forwarded port. The client is connecting from the server's point of view, so it sees the real port.
Using phpMyAdmin Instead
If you only need a quick look at a table, you do not need a tunnel at all. The Database tab has a phpMyAdmin card with an Open phpMyAdmin button. It signs you in through KPanel, so there is no separate password to remember, and it opens in a new tab already pointed at this site's database.
phpMyAdmin is the faster option for browsing, running a one-off query, or checking a value. A desktop client over a tunnel is better for large exports, schema work, and anything you want to script. See Using phpMyAdmin for the browser route.
Running Queries and Dumps Through the Tunnel
With the tunnel open, the standard command line tools work as normal, pointed at your local forwarded port:
mysql -h 127.0.0.1 -P 3307 -u <db-user> -p <db-name>
mysqldump -h 127.0.0.1 -P 3307 -u <db-user> -p <db-name> > backup.sql
A manual dump is a convenience copy, not a backup strategy. It is only as fresh as the moment you ran it, and it lives on whatever laptop you ran it from. Kapsule already takes automatic daily backups of the site, retained for 30 days. See Taking a Backup before you rely on a local .sql file.
Troubleshooting
"Address already in use" when opening the tunnel. Something on your machine is already on that local port. Pick another one, for example -L 3399:127.0.0.1:3306, and change the port in your client to match.
"Connection refused" from the database client. The tunnel is not up. Check that the SSH terminal is still running and has not printed an error, and that the port in your client matches the local port in the -L argument.
SSH connects but the client still times out. Confirm you forwarded to 127.0.0.1:3306 and not to the public hostname. Forwarding to the public name asks the server to reach the database over the internet, which is exactly what is blocked.
"Access denied for user". The SSH login succeeded but the MySQL credentials are wrong. Copy the username and password again from the Database tab using the copy icons rather than retyping them, and check you are connecting to the right database name.
Permission denied (publickey) before you even reach MySQL. That is the SSH layer, not the database. Work through the troubleshooting section in Adding SSH Keys To a Site.
Where To Go Next
- Uploading Files With SFTP uses the same SSH credentials for file transfer.
- Using phpMyAdmin for browser-based database work.
- Restoring From a Backup if a query has gone further than you meant it to.