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

In UI:

1. Open Admin -> Connections.
2. Create connection (name only).
3. Copy token and setup command.

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 Admin.
• 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.