Tunnels
Open a live, masked connection to a database through an agent with relay connect.
A tunnel is a live session established through an agent —
what you get when you run relay connect. Your database client talks to a local
port; the agent applies masking and policy
before returning results.
Connect
# One or more connections at once
relay connect pg-prod
relay connect pg-prod pg-stagingrelay connect opens a local TCP proxy per connection, and stays running until
you press Ctrl+C. It prints the address it's listening on, the upstream, and a
ready-to-use client command.
Each time your database client connects to that address, relay connect asks
the server for a tunnel. The server picks an online replica of one of the
connection's agents, and from
CLI 0.8.0 relay connect dials that replica. Two client connections can go
through different replicas.
The local listen port is assigned dynamically unless the connection defines a
fixed listen address, or you pass --port (single connection only). Read the
address relay connect prints rather than assuming a fixed port.
Status & disconnect
relay status # open tunnels: CONNECTION, USER, STARTED, LAST SEEN, SENT, RECEIVEDTo close a tunnel, stop relay connect with Ctrl+C. Nothing else holds a
tunnel open. relay disconnect is deprecated and does nothing.
Opening a tunnel requires an online replica with room in an agent you may use.
If there is none, relay connect prints the reason. See
Fix tunnel errors.
Open sessions
The control plane checks access when a tunnel opens. While the tunnel is open, the agent reports it to the control plane every 30 seconds, and the session ends in these cases:
- You lose access. The session ends at the next report.
- The connection's masking, audit, or policy rules change. Sessions that
opened under the old rules end. Reconnect your client to get a session under
the new rules.
relay connectkeeps listening. - The agent can't reach the control plane. Sessions end about 2 minutes after the last successful report. On an Agent Edition control plane that the agent doesn't trust, sessions don't end for this reason.
- The agent shuts down. Open tunnels get up to 25 seconds to finish, then the agent closes them. See Shutdown.
On an audited connection, the agent can also refuse single statements while it can't send audit events to the control plane. See Audit backpressure.