SSH Tunneling

SSH tunneling routes your database connection through an encrypted tunnel to reach servers that aren’t directly accessible from your Mac. TablePro manages the tunnel lifecycle, including keep-alive and auto-reconnect.

If you connect to multiple databases through the same SSH server, you can save your SSH configuration as a reusable profile. See SSH Profiles.

How SSH Tunneling Works

TablePro opens an SSH connection to your jump server
A local port (e.g., 60000) forwards through the tunnel
All traffic between your Mac and the SSH server is encrypted
The SSH server connects to the database on your behalf

When to Use SSH Tunneling

Database in private network
Database accepts local connections only
Need to encrypt database connection
Access via bastion/jump host

Setting Up

Open connection form, toggle SSH Tunnel ON, enter SSH server details and auth, click Test Connection.

SSH Configuration Options

SSH Server Settings

Field	Description	Default
SSH Host	SSH server hostname or IP	-
SSH Port	SSH server port	`22`
SSH User	SSH username	-

Authentication Methods

TablePro supports three SSH authentication methods:

Password
Private Key
SSH Agent

Simple password authentication:

Field	Description
SSH Pass	Your SSH password

Password authentication is less secure than key-based authentication. Use SSH keys for production servers.

Key-based authentication (more secure):

Field	Description
Key File	Path to your private key (e.g., `~/.ssh/id_rsa`)
Passphrase	Key passphrase (if encrypted)

Click Browse to select your private key file. TablePro looks in ~/.ssh/ by default.

Delegates signing to an SSH agent process (1Password, Secretive, macOS ssh-agent). Keys stay in the agent and are never read by TablePro.

Field	Description
Agent Socket	Dropdown with `SSH_AUTH_SOCK`, `1Password`, or `Custom Path`

SSH_AUTH_SOCK: Uses the system SSH_AUTH_SOCK environment variable.
1Password: Uses 1Password’s default socket path, ~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock.
Custom Path: Shows a text field so you can enter another agent socket path.

1Password also documents ~/.1password/agent.sock as an easier alias to type, but that shortcut only works if you created it yourself. TablePro’s 1Password option uses the default path in ~/Library/Group Containers/....

Two-Factor Authentication (TOTP)

If your SSH server requires two-factor authentication via PAM (e.g., google-authenticator, duo_unix), TablePro can handle TOTP (Time-based One-Time Password) codes during login. The TOTP option appears under Two-Factor Authentication when you select Password or Keyboard Interactive as your auth method.

Auto Generate
Prompt at Connect

TablePro generates the TOTP code automatically at connect time using a secret you provide. No need to open an authenticator app.

Field	Description
TOTP Secret	Your base32-encoded secret (the same key you used when setting up your authenticator app)
Algorithm	Hash algorithm: SHA1 (default), SHA256, or SHA512
Digits	Code length: 6 (default) or 8
Period	Code rotation interval: 30 seconds (default) or 60 seconds

The TOTP secret is the base32 string you got when first enrolling in 2FA. If you only have a QR code, most authenticator apps let you view the underlying secret.

Setup steps:

In the SSH tab of your connection settings, select Password or Keyboard Interactive as the auth method
Under Two-Factor Authentication, choose your TOTP mode
For Auto Generate: paste your base32-encoded TOTP secret

TOTP works with common PAM configurations including google-authenticator, duo_unix, and similar modules.

Host Key Verification

TablePro verifies SSH host keys to protect against man-in-the-middle attacks. On first connection to a server, you’ll see the server’s fingerprint and can choose to trust it. The key is then stored locally. If a previously trusted server’s host key changes, TablePro shows a warning. This could mean the server was reinstalled, or it could indicate a security issue. You can choose to accept the new key or abort the connection.

Using SSH Config

If you have entries in ~/.ssh/config, TablePro reads them automatically:

TablePro reads your SSH config on launch
Select a host from the SSH Host dropdown
Settings are auto-filled from your config

Example SSH config entry:

# ~/.ssh/config
Host production-jump
    HostName jump.example.com
    User deploy
    Port 22
    IdentityFile ~/.ssh/production_key

This appears as “production-jump” in the SSH Host dropdown.

Database Connection Settings

When using SSH tunneling, the database host is relative to the SSH server:

Field	Value	Description
Host	`localhost` or `127.0.0.1`	Database is on the SSH server itself
Host	`db.internal`	Database is on internal network
Port	`3306`, `5432`, etc.	Database port (unchanged)

The database host should be what the SSH server uses to reach the database, not what your Mac would use.

Common Scenarios

Database on SSH Server

The database runs on the same machine as your SSH server:

SSH Host:       jump.example.com
SSH User:       deploy

Database Host:  localhost
Database Port:  3306

Database on Internal Network

The database is on a different server, only accessible from the SSH server:

SSH Host:       jump.example.com
SSH User:       deploy

Database Host:  db.internal.example.com
Database Port:  5432

AWS RDS via Bastion

Connecting to RDS through an EC2 bastion host:

SSH Host:       bastion.example.com
SSH User:       ec2-user
Key File:       ~/.ssh/aws-key.pem

Database Host:  mydb.abc123.us-east-1.rds.amazonaws.com
Database Port:  5432

Multi-Jump SSH (ProxyJump)

When a database server sits behind multiple bastion hosts, TablePro can chain SSH hops using OpenSSH’s -J (ProxyJump) flag. A single ssh process handles all intermediate jumps.

Setting Up Multi-Jump

Open the connection form and switch to the SSH Tunnel tab
Enable SSH and configure the final SSH server (the one that can reach the database)
Expand the Jump Hosts section below the authentication settings
Click Add Jump Host and fill in each intermediate bastion host in order
Hosts are connected in sequence: first jump host is reached from your Mac, each subsequent host is reached through the previous one

Jump Host Settings

Each jump host has:

Field	Description
Host	Hostname or IP of the jump host
Port	SSH port (default `22`)
Username	SSH username for this hop
Auth Method	Private Key or SSH Agent (password auth is not supported for jump hosts)
Key File	Path to private key (if using Private Key auth)

Example: Two Bastion Hosts

Jump Host 1:    [email protected]:22    (SSH Agent)
Jump Host 2:    [email protected]:2222     (Private Key)

SSH Server:     [email protected]:22
Database Host:  db.internal:5432

This produces the equivalent of:

ssh -J [email protected]:22,[email protected]:2222 [email protected]

SSH Config Integration

TablePro reads ProxyJump directives from ~/.ssh/config. When you select a config host that has ProxyJump set, the jump hosts are auto-filled.

# ~/.ssh/config
Host production-db
    HostName final-ssh.internal
    User deploy
    ProxyJump [email protected],[email protected]:2222

Jump hosts only support Private Key and SSH Agent authentication. Password authentication is not available for intermediate hops because OpenSSH’s -J flag does not support interactive password prompts for jump hosts.

SSH Key Setup

Generating SSH Keys

If you don’t have SSH keys:

# Generate a new key pair
ssh-keygen -t ed25519 -C "[email protected]"

# Or use RSA for broader compatibility
ssh-keygen -t rsa -b 4096 -C "[email protected]"

Key Locations

Default key locations on macOS:

Key Type	Private Key	Public Key
Ed25519	`~/.ssh/id_ed25519`	`~/.ssh/id_ed25519.pub`
RSA	`~/.ssh/id_rsa`	`~/.ssh/id_rsa.pub`
ECDSA	`~/.ssh/id_ecdsa`	`~/.ssh/id_ecdsa.pub`

Adding Key to Server

Copy your public key to the SSH server:

# Using ssh-copy-id
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server

# Or manually
cat ~/.ssh/id_ed25519.pub | ssh user@server "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Key Permissions

SSH keys must have correct permissions:

# Fix permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/id_*.pub
chmod 644 ~/.ssh/config

Import from URL

Import SSH tunnel connections from a URL instead of filling in each field. TablePro supports +ssh URL schemes that encode both SSH and database credentials in a single string. For the full URL specification, see Connection URL Reference. Format:

scheme+ssh://ssh_user@ssh_host:ssh_port/db_user:db_password@db_host/db_name?name=MyConnection&usePrivateKey=true

Supported schemes: mysql+ssh, postgresql+ssh, postgres+ssh, mariadb+ssh Example:

mysql+ssh://[email protected]:1234/database_user:[email protected]/database_name?name=FlashPanel&usePrivateKey=true

This fills in:

SSH Host: 123.123.123.123, SSH Port: 1234, SSH User: root
Database Host: 127.0.0.1, Database User: database_user, Database: database_name
Connection Name: FlashPanel, Auth Method: Private Key

Query parameters:

Parameter	Description
`name`	Sets the connection name
`usePrivateKey`	Set to `true` to select Private Key authentication
`useSSHAgent`	Set to `true` to select SSH Agent authentication
`agentSocket`	Optional SSH agent socket path override (for example, `~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock`)

To import, open New Connection, click Import from URL, and paste the URL.

This format is compatible with TablePlus SSH connection URLs, so you can paste URLs directly when migrating.

Troubleshooting

If you use SSH profiles, click Test Connection in the profile editor to verify SSH connectivity independently from the database connection. This helps isolate whether the problem is SSH or database-level.

Connection Refused

Symptoms: “Connection refused” when testing SSH tunnel Causes and Solutions:

SSH server not running

# Test SSH connection directly
ssh -v user@server

Wrong port
- Verify SSH port (some servers use non-standard ports)
- Check with server administrator
Firewall blocking connection
- Ensure port 22 (or custom port) is open
- Check both local and server firewalls

Authentication Failed

Symptoms: “SSH authentication failed” or “Permission denied” For Password Authentication:

Verify username and password
Check if password auth is enabled on server
Try connecting via terminal: ssh user@server

For Key Authentication:

Verify key file path is correct
Check key permissions (chmod 600)
Ensure public key is in server’s authorized_keys
Verify passphrase (if key is encrypted)
Try connecting via terminal:
```
ssh -i ~/.ssh/your_key user@server
```

Private Key Errors

“Private key file not found”:

Verify the path exists
Use the Browse button to select the file

“Private key file is not readable”:

chmod 600 ~/.ssh/your_key

“Wrong passphrase”:

Re-enter the passphrase
Test key manually: ssh-keygen -y -f ~/.ssh/your_key

Tunnel Established but Database Fails

If the SSH tunnel connects but the database connection fails:

Verify database host is correct (relative to SSH server)

# From SSH server, test database connection
ssh user@server "mysql -h localhost -u dbuser -p"

Check database port
- Ensure port matches the database server’s actual port
Verify database credentials
- Username/password might be different from SSH credentials

Tunnel Drops Periodically

TablePro uses keep-alive settings to maintain tunnels:

ServerAliveInterval=60: send keep-alive every 60 seconds
ServerAliveCountMax=3: disconnect after 3 missed responses

If tunnels still drop:

Check network stability
Verify server’s ClientAliveInterval setting
Check for idle timeout settings on firewalls

Security Best Practices

Use key-based authentication with Ed25519 or RSA 4096+ bits, protect keys with a passphrase, and never expose database ports directly to the internet. SSH Agent (1Password, Secretive, or ssh-agent) keeps private keys in a separate process. Use it instead of storing passphrases.

Getting Started

Database Connections

Features

Customization

SSH Tunneling

SSH Tunneling

How SSH Tunneling Works

When to Use SSH Tunneling

Setting Up

SSH Configuration Options

SSH Server Settings

Authentication Methods

Two-Factor Authentication (TOTP)

Host Key Verification

Using SSH Config

Database Connection Settings

Common Scenarios

Database on SSH Server

Database on Internal Network

AWS RDS via Bastion

Multi-Jump SSH (ProxyJump)

Setting Up Multi-Jump

Jump Host Settings

Example: Two Bastion Hosts

SSH Config Integration

SSH Key Setup

Generating SSH Keys

Key Locations

Adding Key to Server

Key Permissions

Import from URL

Troubleshooting

Connection Refused

Authentication Failed

Private Key Errors

Tunnel Established but Database Fails

Tunnel Drops Periodically

Security Best Practices

Getting Started

Database Connections

Features

Customization

​SSH Tunneling

​How SSH Tunneling Works

​When to Use SSH Tunneling

​Setting Up

​SSH Configuration Options

​SSH Server Settings

​Authentication Methods

​Two-Factor Authentication (TOTP)

​Host Key Verification

​Using SSH Config

​Database Connection Settings

​Common Scenarios

​Database on SSH Server

​Database on Internal Network

​AWS RDS via Bastion

​Multi-Jump SSH (ProxyJump)

​Setting Up Multi-Jump

​Jump Host Settings

​Example: Two Bastion Hosts

​SSH Config Integration

​SSH Key Setup

​Generating SSH Keys

​Key Locations

​Adding Key to Server

​Key Permissions

​Import from URL

​Troubleshooting

​Connection Refused

​Authentication Failed

​Private Key Errors

​Tunnel Established but Database Fails

​Tunnel Drops Periodically

​Security Best Practices

SSH Tunneling

How SSH Tunneling Works

When to Use SSH Tunneling

Setting Up

SSH Configuration Options

SSH Server Settings

Authentication Methods

Two-Factor Authentication (TOTP)

Host Key Verification

Using SSH Config

Database Connection Settings

Common Scenarios

Database on SSH Server

Database on Internal Network

AWS RDS via Bastion

Multi-Jump SSH (ProxyJump)

Setting Up Multi-Jump

Jump Host Settings

Example: Two Bastion Hosts

SSH Config Integration

SSH Key Setup

Generating SSH Keys

Key Locations

Adding Key to Server

Key Permissions

Import from URL

Troubleshooting

Connection Refused

Authentication Failed

Private Key Errors

Tunnel Established but Database Fails

Tunnel Drops Periodically

Security Best Practices