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 (CLI-first)

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?.

Via API:

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.