# How to connect to your MySQL database remotely

Connect a database client on your own computer (for example TablePlus, DBeaver or HeidiSQL) to a
MySQL database on your host. The recommended, secure way is an SSH tunnel.

## Why the database port is not open by default

For security, MySQL listens on `localhost` only (`mysql_bindaddress: "127.0.0.1"`), so the database
port is not reachable from the internet. Rather than exposing it, you forward it over your existing
SSH access - the connection is encrypted and uses your SSH key.

## Connect over an SSH tunnel (recommended)

1. Open a tunnel from a local port (here `3307`) to the database on the host:
   ```bash
   ssh -L 3307:127.0.0.1:3306 prod@web1.example.com
   ```
   Leave this session open while you work.
2. Point your client at the local end of the tunnel:

   | Setting | Value |
   | --- | --- |
   | Host | `127.0.0.1` |
   | Port | `3307` |
   | User | your database user (from [Credentials](../../platform/hosts/credentials.md)) |
   | Password | the database user's password |
   | Database | your database name, for example `prod_db` |

Many clients (TablePlus, DBeaver, HeidiSQL) can also create the SSH tunnel for you - choose "SSH" or
"connect over SSH" and give your SSH host and key; then set the database host to `127.0.0.1`.

## Opening the port instead (advanced)

If a tool genuinely cannot tunnel, you can widen the bind address and allow specific source IPs - but
this exposes the database, so prefer the tunnel.

- Set `mysql_bindaddress` to a non-local address in the host configuration (see
  [Configure MySQL](configure.md)).
- Allow only the exact source IP addresses on the host's **Security** tab
  ([Security](../../platform/hosts/security.md)). Adding an IP to the allow-list there also opens the otherwise
  blocked database port to it.
- Connect with a [least-privilege user](manage-database-users.md), never the application's main user.

> [!WARNING]
> Never open the database to `0.0.0.0` or a broad range. Expose it only to specific, trusted IP
> addresses, and use a dedicated read-only or limited user.

## Troubleshooting

- **Connection refused** - the tunnel is not open, or the client is pointing at the host instead of
  `127.0.0.1`.
- **Access denied** - wrong user/password, or the user is not allowed from your host (see
  [Create and manage database users](manage-database-users.md)).
- **Times out when opening the port directly** - the source IP is not on the allow-list, or
  `mysql_bindaddress` is still local. See [Database problems](../../troubleshooting/database-issues.md).

## Related

- [Configure MySQL](configure.md)
- [Create and manage database users](manage-database-users.md)
- [Import and export a database](import-export-database.md)
- [SSH access](../../platform/hosts/ssh.md)
- [Host Security tab](../../platform/hosts/security.md)