Websites
Connecting to Your Database Remotely
Where to find your database credentials, why direct remote connections on port 3306 are refused, and how to connect a desktop tool through an SSH tunnel instead.
Every KapsuleHost web hosting site with a database gets its own database, its own database user, and credentials you can read at any time. What you cannot do is connect to it directly across the internet, and that is deliberate. This guide covers the credentials, the two supported ways in, and how to set up the tunnel that desktop database tools need.
Finding Your Credentials
Go to Websites, click the site, then Files, then Database.
The page shows five things:
| Field | Value |
|---|---|
| Host | 127.0.0.1 |
| Port | 3306 |
| Database | your database name |
| Username | your database user |
| Password | masked, with a reveal button and a copy button |
The password is not a one-time reveal. You can come back and read it whenever you need it, so there is no need to store it separately.
The database server is MariaDB 10.11, which is MySQL-compatible. That matters in one practical way: a dump exported from a recent MySQL server can contain collations that MariaDB does not recognise, and the import will fail with an "unknown collation" error. If that happens, re-export using a widely compatible collation such as utf8mb4_unicode_ci, or search and replace it in the dump file before importing.
Why the Host Is 127.0.0.1
127.0.0.1 means "this machine". The database server only listens on the machine's own internal interface, and port 3306 is not open to the internet at the firewall either. There is no setting in the panel to open it, and there is no IP allowlist for it.
That is not an oversight. An internet-facing database port is one of the most reliably exploited things in hosting: it is scanned constantly, it leaks version information to anyone who connects, and a single weak password loses you the entire site. Keeping it closed removes that whole category of risk.
So a connection string using your site's public IP address and port 3306 will always fail, from anywhere, on every plan. There are two supported ways in instead.
Option 1: phpMyAdmin in the Browser
Easiest for a quick look, an edit, or a small import or export.
On the Database page, click Open phpMyAdmin. You are signed straight in with your site's own credentials and you see only your own databases.
The link that does this is deliberately short-lived, and it fails in ways that look like errors but are not:
- It expires in 60 seconds. Click it as soon as it appears.
- It works once. Going back and reloading will not work; generate a new one.
- It must be opened from the same browser and the same network you requested it from. If you copy the link to another device, or your connection changes address part way through, it is refused.
If you see "This link has already been used" or a message about an IP mismatch, that is the protection working. Go back to the Database page and click the button again.
For working with phpMyAdmin itself, see Using phpMyAdmin.
Option 2: An SSH Tunnel for Desktop Tools
If you want to use a desktop client, this is the supported path. The tunnel opens an encrypted connection to the server and forwards a port on your own machine through it, so your client connects to what looks like a local database.
What You Need First
An SSH key on the site. Password authentication is not accepted, so this step is not optional.
- Go to Websites, the site, Files, then SSH Keys.
- Either paste the public key you already use, or generate a new key pair from the panel.
- Note the username shown on that page. It is your site's system user, and it is what you connect as.
If you generate a key in the panel, the private key is shown once and never again. Save it immediately, and keep it somewhere only you can read.
You will also receive an email whenever a key is added to your site. That is intentional. If one arrives and it was not you, revoke it from that page straight away and read If Your Site Is Hacked.
See Adding SSH Keys for the full walkthrough.
An SFTP account created on the SFTP tab will not work for a tunnel. Those accounts are file transfer only, with no shell and no port forwarding. Tunnelling requires the site's own SSH user with a key. See SFTP Access.
Opening the Tunnel
From a terminal on your own machine:
ssh -N -L 3307:127.0.0.1:3306 your-ssh-user@cp1-kapsule.kapsulehost.com
Replace your-ssh-user with the username from the SSH Keys page. Breaking that down:
-Nmeans do not run a command, just hold the tunnel open.-L 3307:127.0.0.1:3306forwards port 3307 on your machine to port 3306 on the server.- Port 3307 is used rather than 3306 so it does not clash with a database you may have running locally.
The command prints nothing when it works. That is correct. Leave the terminal window open for as long as you need the connection, and press Ctrl+C to close it.
Connecting Your Client
With the tunnel open, point your database tool at:
| Setting | Value |
|---|---|
| Host | 127.0.0.1 |
| Port | 3307 |
| Username | the database username from the Database page |
| Password | the database password from the Database page |
| Database | your database name |
Note the split: the SSH username is your site's system user, and the database username is a different one from the Database page. Mixing those two up is by far the most common mistake here.
Most desktop clients also have a built-in "connect over SSH tunnel" option, which does exactly the above without a separate terminal. Fill in the SSH host cp1-kapsule.kapsulehost.com, port 22, your SSH username, and your private key file, then the database fields as above.
See Database SSH Tunnel for client-by-client setup.
Command Line on the Server
If you are comfortable in a terminal, you do not need a tunnel at all. Connect over SSH and work on the server directly:
ssh your-ssh-user@cp1-kapsule.kapsulehost.com
mysqldump -u DBUSER -p DBNAME > backup.sql
This is much faster than pulling a large database through a tunnel, and it is the right way to take a manual dump before a risky change. For WordPress specifically, WP-CLI is usually better still.
Troubleshooting
"Connection refused" on port 3306 from your own machine. Expected. See above. Use a tunnel.
The tunnel command asks for a password. Your key is not being offered or is not installed. Check the key is on the SSH Keys page and add -i /path/to/your/private/key to the command.
"Permission denied (publickey)". Wrong username, or the wrong key. The username is the one on the SSH Keys page, not your Kapsule login email.
"Address already in use" for port 3307. A tunnel is already open, or something else is using that port. Close the other one, or pick a different local port such as 3308.
The tunnel opens but the client cannot connect. Confirm your client is pointed at 127.0.0.1 and your chosen local port, not at your domain.
"Access denied for user". Database credentials, not SSH. Reveal and copy them again from the Database page.
"Unknown collation" on import. Covered above. Re-export with a compatible collation.
Anything you do in a database client happens immediately and cannot be undone. There is no confirmation step and no recycle bin. Take a backup before you run anything that writes. See Taking a Backup.