SSH Tunneling

SSH tunneling allows you to securely connect to databases on remote servers that aren’t directly accessible from your Mac. TablePro creates an encrypted tunnel through an SSH server to reach your database.

How SSH Tunneling Works

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

When to Use SSH Tunneling

Database server is in a private network
Database server only accepts local connections
You need to encrypt connections to the database
You want to access databases through a bastion/jump host

Setting Up SSH Tunneling

Create or Edit Connection

Open the connection form for your database

Enable SSH Tunnel

Toggle the SSH Tunnel switch to ON

Configure SSH Settings

Enter your SSH server details and authentication

Test and Connect

Click Test Connection to verify the tunnel works

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 two SSH authentication methods:

Password
Private Key

Simple password authentication:

Field	Description
SSH Pass	Your SSH password

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

More secure key-based authentication:

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.

Using SSH Config

If you have entries in your ~/.ssh/config file, TablePro can use them:

TablePro reads your SSH config automatically
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

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

Troubleshooting

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 SSH tunnel connects but 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 includes keep-alive settings to prevent tunnel drops:

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 Considerations

Best Practices

Use key-based authentication instead of passwords
Use Ed25519 or RSA keys with 4096+ bits
Protect your private keys with a passphrase
Limit SSH access to specific users/IPs on the server
Use a dedicated jump host rather than direct database access

What Gets Encrypted

Data	Encrypted
SSH connection	Yes
Database credentials	Yes (through tunnel)
Query data	Yes (through tunnel)
Local stored passwords	Yes (macOS Keychain)

What to Avoid

Don’t share private keys
Don’t use password authentication on production servers
Don’t store SSH passwords in plain text
Don’t expose database ports directly to the internet

Advanced: SSH Agent

If you use SSH Agent for key management:

Add your key to the agent:
```
ssh-add ~/.ssh/id_ed25519
```
TablePro can use keys from SSH Agent automatically
You won’t need to enter passphrases repeatedly

Next Steps

MySQL Connection

MySQL-specific settings and features

PostgreSQL Connection

PostgreSQL-specific settings and features

Connection Management

Managing all your connections

Keyboard Shortcuts

Speed up your workflow

Getting Started

Database Connections

Features

Customization

SSH Tunneling

SSH Tunneling

How SSH Tunneling Works

When to Use SSH Tunneling

Setting Up SSH Tunneling

SSH Configuration Options

SSH Server Settings

Authentication Methods

Using SSH Config

Database Connection Settings

Common Scenarios

Database on SSH Server

Database on Internal Network

AWS RDS via Bastion

SSH Key Setup

Generating SSH Keys

Key Locations

Adding Key to Server

Key Permissions

Troubleshooting

Connection Refused

Authentication Failed

Private Key Errors

Tunnel Established but Database Fails

Tunnel Drops Periodically

Security Considerations

Best Practices

What Gets Encrypted

What to Avoid

Advanced: SSH Agent

Next Steps

MySQL Connection

PostgreSQL Connection

Connection Management

Keyboard Shortcuts

Getting Started

Database Connections

Features

Customization

​SSH Tunneling

​How SSH Tunneling Works

​When to Use SSH Tunneling

​Setting Up SSH Tunneling

​SSH Configuration Options

​SSH Server Settings

​Authentication Methods

​Using SSH Config

​Database Connection Settings

​Common Scenarios

​Database on SSH Server

​Database on Internal Network

​AWS RDS via Bastion

​SSH Key Setup

​Generating SSH Keys

​Key Locations

​Adding Key to Server

​Key Permissions

​Troubleshooting

​Connection Refused

​Authentication Failed

​Private Key Errors

​Tunnel Established but Database Fails

​Tunnel Drops Periodically

​Security Considerations

​Best Practices

​What Gets Encrypted

​What to Avoid

​Advanced: SSH Agent

​Next Steps

MySQL Connection

PostgreSQL Connection

Connection Management

Keyboard Shortcuts

SSH Tunneling

How SSH Tunneling Works

When to Use SSH Tunneling

Setting Up SSH Tunneling

SSH Configuration Options

SSH Server Settings

Authentication Methods

Using SSH Config

Database Connection Settings

Common Scenarios

Database on SSH Server

Database on Internal Network

AWS RDS via Bastion

SSH Key Setup

Generating SSH Keys

Key Locations

Adding Key to Server

Key Permissions

Troubleshooting

Connection Refused

Authentication Failed

Private Key Errors

Tunnel Established but Database Fails

Tunnel Drops Periodically

Security Considerations

Best Practices

What Gets Encrypted

What to Avoid

Advanced: SSH Agent

Next Steps