> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-refactor-inspector-field-layout.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SOCKS Proxy

> Route a database connection through a SOCKS5 proxy, with remote DNS (socks5h) so the proxy resolves the database hostname

Leave the database's **Host** and **Port** on the General section exactly as they are. The proxy resolves that name and dials it from its own side. A hostname that exists only inside the private network works, and no DNS query for the database leaves your Mac.

<Frame caption="SOCKS Proxy selected on the Network section">
  <img className="block dark:hidden" src="https://mintcdn.com/ngquct-refactor-inspector-field-layout/GELZbb49dl8pWtXY/images/socks-proxy-pane.png?fit=max&auto=format&n=GELZbb49dl8pWtXY&q=85&s=12b9ad5b7958d556648edd939be832ab" alt="Proxy server host and port with a username and password below" width="900" height="720" data-path="images/socks-proxy-pane.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/ngquct-refactor-inspector-field-layout/GELZbb49dl8pWtXY/images/socks-proxy-pane-dark.png?fit=max&auto=format&n=GELZbb49dl8pWtXY&q=85&s=77c2d8e445061b8b9dca59a6b80767ed" alt="Proxy server host and port with a username and password below" width="900" height="720" data-path="images/socks-proxy-pane-dark.png" />
</Frame>

## How it works

```mermaid theme={null}
flowchart LR
    subgraph mac ["Your Mac"]
        Driver["Database driver<br>127.0.0.1:auto"]
        Relay["TablePro relay"]
    end

    subgraph proxy ["SOCKS5 Proxy"]
        SOCKS["proxy:1080"]
    end

    subgraph db ["Database Server"]
        Database["PostgreSQL<br>MySQL<br>db:5432"]
    end

    Driver -->|"loopback"| Relay -->|"SOCKS5"| SOCKS -->|"TCP"| Database
```

No helper binary is involved: the relay is part of the app. It listens on a free loopback port and carries each connection through the proxy. If the relay dies mid-session, the connection reconnects and rebuilds it, up to ten attempts with a widening delay.

## Setting up

<Steps>
  <Step title="Choose the transport">
    On the **Network** tab, set **Connect via** to **SOCKS Proxy**. A connection uses one transport, so choosing this one switches off whichever was selected before.
  </Step>

  <Step title="Enter the proxy address">
    **Host** and **Port** under **Proxy Server**, plus **Username** and **Password** if the proxy authenticates.
  </Step>

  <Step title="Test it">
    On **General**, click **Test Connection**.
  </Step>
</Steps>

It is offered for the drivers that support SSH tunneling; the [transport matrix](/connections/connection-form#which-drivers-get-which-transports) says which.

## Options

| Field        | What it is                                                           | Default |
| ------------ | -------------------------------------------------------------------- | ------- |
| **Host**     | The SOCKS5 proxy's address.                                          | -       |
| **Port**     | The proxy's port.                                                    | 1080    |
| **Username** | Only for a proxy that requires username and password authentication. | -       |
| **Password** | Stored in the macOS Keychain. Blank connects without authentication. | -       |

<Tip>
  An SSH dynamic port forward is a SOCKS5 proxy. Run `ssh -D 1080 user@bastion`, then set the host to `127.0.0.1` and the port to `1080`.
</Tip>

[SSL/TLS](/connections/ssl) still applies, with one unavoidable adjustment: the driver dials a loopback port that no server certificate names, so **Verify CA** and **Verify Identity** fall back to **Required** and certificate paths are dropped.

## Troubleshooting

### Timed out connecting through the SOCKS proxy

Fifteen seconds passed with no path to the database. The proxy did not answer, rejected the credentials, or could not reach the database. Check the proxy host and port, then that the database answers from the proxy's network.

### Local network permission prompt

On macOS 15 and later, a proxy on your local network (a `192.168.x.x` address) raises the one-time Local Network alert. Allow it, or the proxy stays unreachable. A loopback proxy such as `ssh -D` on `127.0.0.1` never triggers it.

### The database rejects the connection

The path works and the server refused you. The driver's own error is shown, exactly as on a direct connection: check credentials, SSL settings, and whether the database accepts connections from the proxy's address.