SSH Tunnel

Use an SSH tunnel when your database is in a private network reachable only via a bastion host.

Prerequisites

A Linux or macOS bastion host that has network access to the target database.
The database must be one of the supported types (PostgreSQL or MySQL). No other database types are supported through the SSH tunnel right now.

1. Create a dedicated SSH user

What: Create a dedicated SSH user on the bastion for Querio.

sudo adduser --disabled-password --gecos "" querio
sudo mkdir -p /home/querio/.ssh
sudo chmod 700 /home/querio/.ssh

2. Generate an SSH keypair

What: Generate an SSH keypair for Querio to use.

ssh-keygen -t ed25519 -C "querio-tunnel" -f querio_tunnel

This command produces two files: querio_tunnel (the private key, which you will give to Querio) and querio_tunnel.pub (the public key, which you will install on the bastion).

3. Authorize the public key

What: Add the public key to the bastion's authorized keys list.

sudo tee -a /home/querio/.ssh/authorized_keys < querio_tunnel.pub
sudo chown -R querio:querio /home/querio/.ssh
sudo chmod 600 /home/querio/.ssh/authorized_keys

Optional hardening: In /etc/ssh/sshd_config.d/querio.conf, you can restrict the user:

Match User querio
  AllowTcpForwarding yes
  PermitOpen <db-host>:<db-port>
  ForceCommand /usr/sbin/nologin
  X11Forwarding no

4. Allowlist Querio

What: Allow Querio's outbound IP on the bastion's firewall for SSH (typically port 22).

5. Create the database user

What: Create a dedicated database user and grant read-only access.

Depending on your database, follow the steps on the PostgreSQL or MySQL integration page. The SQL grants are identical, just executed against the database that lives behind the bastion.

Querio will ask for two groups of fields in the connection form:

SSH Tunnel:

SSH Host: The address of the bastion host (e.g. bastion.example.com).
SSH Port: The port the bastion is listening on (defaults to 22).
SSH Username: The dedicated SSH user (e.g. querio).
Private Key: The full PEM contents of the querio_tunnel file, including the -----BEGIN ... PRIVATE KEY----- and -----END ... PRIVATE KEY----- markers.
Destination Host: The database hostname as seen from the bastion (often localhost or a private IP).
Destination Port: The database port (e.g. 5432 for Postgres, 3306 for MySQL).

Database (behind tunnel):

Database Client: postgres or mysql.
Database Name: The target database name.
Database Username: The read-only database user.
Database Password: The password for the database user.
Database Schema: The schema to query (PostgreSQL only; defaults to public).

Troubleshooting

"permission denied (publickey)": Check the ownership and permissions of the /home/querio/.ssh/authorized_keys file.
"channel ... open failed: administratively prohibited": AllowTcpForwarding might be disabled, or PermitOpen in the sshd configuration excludes the target database host/port.
"connection refused" on the destination: The database isn't listening on the specified Destination Host:Destination Port from the bastion's perspective.

On this page