Connections & Tunnel

In CH-UI, a connection represents one ClickHouse environment (dev, staging, prod, etc).

Each connection is attached to a tunnel token used by ch-ui connect.

Create a Connection

Option A: Console UI (Cloud)

If you're using CH-UI Cloud, create connections directly from the Console:

1. Open your org at console.ch-ui.com
2. Go to Connections
3. Click Add Connection and enter a name
4. Copy the tunnel token immediately — it's shown only once
5. Setup instructions with the ch-ui connect command are provided

Token management from the Console:

• Regenerate: creates a new token, old one is invalidated instantly
• Delete: permanently removes the connection

Admin or owner role required. Connection count is limited by your org plan.

Option B: CLI (Self-Hosted)

Run on the CH-UI server host (where ch-ui.db lives):

ch-ui tunnel create --name "Production EU"
ch-ui tunnel list
ch-ui tunnel show <connection-id>

Copy token and setup command from tunnel show.

Optional UI path (Pro/Admin): create/manage connections in Admin.

Note: local first-run URL fixes are not done in Admin; use startup flags (--clickhouse-url, --connection-name) or Can't login?.

Option C: API (Self-Hosted)

curl -X POST http://localhost:3488/api/connections \
  -H "Content-Type: application/json" \
  -H "Cookie: chui_session=..." \
  -d '{"name":"Production EU"}'

Start Connector

ch-ui connect \
  --url wss://ch-ui.yourcompany.com/connect \
  --key cht_your_token \
  --clickhouse-url http://127.0.0.1:8123

Validate Connectivity

• Check connection online status in ch-ui tunnel list (or in Admin if Pro-enabled).
• Run Test Connection with ClickHouse credentials.
• Login using that connection in CH-UI.

Tunnel Key Management (CLI)

Run these commands on the CH-UI server host (the VM where ch-ui.db lives):

# Create a connection + key
ch-ui tunnel create --name "vm1-clickhouse"

# List all tunnel connections
ch-ui tunnel list

# Show full token + setup commands for one connection
ch-ui tunnel show <connection-id>

# Rotate token (old token becomes invalid immediately)
ch-ui tunnel rotate <connection-id>

# Delete a tunnel connection
ch-ui tunnel delete <connection-id>

Useful flags

Token Operations

For a connection you can:

• Get token
• Regenerate token
• Revoke by deleting connection

Regenerate if token leakage is suspected.

Multi-Environment Pattern

Use one connection per environment:

• dev
• staging
• production

This keeps sessions, governance state, and audit logs scoped cleanly by environment.