Connect to MongoDB over an SSH tunnel

Why use an SSH tunnel?

MongoDB typically listens on port 27017. In production you rarely want that port reachable from the public internet. Instead, you place MongoDB on a private subnet accessible only from a bastion (jump) host that accepts SSH on port 22. Your local client then connects to the bastion over SSH, and the bastion forwards traffic to MongoDB — the database never sees a direct connection from your laptop.

The result is encrypted transit (SSH) without having to open firewall rules or expose MongoDB's port to the world.

What you need before you start

• The bastion host address (hostname or IP) and its SSH port (usually 22).
• A username on the bastion (for example, ubuntu or ec2-user).
• Either an SSH private key (RSA, Ed25519, ECDSA — passphrase-protected keys are supported) or a password for the bastion user.
• The MongoDB host and port as seen from the bastion — often localhost:27017 if MongoDB runs on the same machine, or a private DNS name like mongo-primary.internal:27017.

Setting up the connection in MQLens

Open MQLens and click New Connection. Fill in the MongoDB host and port using the address that is reachable from the bastion, not from your laptop. For example, if MongoDB runs on the same EC2 instance as your bastion, use localhost and port 27017.

Scroll down to the SSH Tunnel section and toggle it on. You will see the following fields:

• SSH Host / Port — the public address of your bastion and its SSH port.
• SSH Username — the username on the bastion server.
• Authentication method — choose Private Key to browse for a .pem or .key file, or choose Password to type it inline (stored encrypted in the keychain).
• Private key passphrase — if your key is passphrase-protected, enter it here; MQLens never stores it in plaintext.

Add your MongoDB credentials (username, password, auth database) in the Authentication section as usual. TLS settings also work in combination with SSH tunneling — you can run TLS over the tunnel if your server requires it.

Using the staged Test Connection to debug

Before saving, click Test Connection. MQLens runs the connection in distinct, named phases and reports the outcome of each one:

1. Parse — validates that the URI and all form fields are syntactically correct.
2. DNS — resolves the bastion hostname to an IP address. A failure here usually means a typo or a VPN that is not active.
3. Connect — opens the TCP connection to the bastion on its SSH port and completes the SSH handshake. Failures here are typically firewall rules or a wrong port number.
4. Ping — sends a MongoDB hello (ping) command through the forwarded tunnel. A failure at this stage with the previous steps passing means the tunnel is working but MongoDB is not reachable at the host:port you specified.

This staged output lets you isolate the failure immediately rather than guessing at a generic "connection refused" message. Once all four phases turn green, save the connection. MQLens will re-establish the SSH tunnel automatically on every reconnect.

SOCKS5 proxy as an alternative

If your team uses a SOCKS5 proxy (for example, established with ssh -D 1080 user@bastion), MQLens supports that too. Switch the proxy type to SOCKS5, point it at 127.0.0.1:1080, and leave the SSH tunnel fields empty. The Test Connection phases work identically for proxy connections.