Provisioning ClickHouse Users

This runbook explains how to provision a ClickHouse user for a workspace which wants to use the v2 analytics API.

Prerequisites

• ctrl-worker running with UNKEY_CLICKHOUSE_ADMIN_URL configured
• Restate accessible

Provisioning a New User

Call the ConfigureUser endpoint via Restate:

curl -X POST "http://restate:8080/hydra.v1.ClickhouseUserService/ws_abc123/ConfigureUser" \
  -H "Content-Type: application/json" \
  -d '{}'

That's it. The workflow will:

1. Generate a secure password
2. Encrypt it via Vault
3. Store credentials in MySQL
4. Create the ClickHouse user with row-level security

Customizing Quotas

Override the defaults by passing quota parameters:

curl -X POST "http://restate:8080/hydra.v1.ClickhouseUserService/ws_abc123/ConfigureUser" \
  -H "Content-Type: application/json" \
  -d '{
    "max_queries_per_window": 500,
    "max_query_execution_time": 60
  }'

Updating an Existing User

Same endpoint. The workflow detects the user exists and updates quotas while preserving the password.

curl -X POST "http://restate:8080/hydra.v1.ClickhouseUserService/ws_abc123/ConfigureUser" \
  -H "Content-Type: application/json" \
  -d '{
    "max_queries_per_window": 2000
  }'

Via Restate UI (Local)

1. Open Restate UI (http://localhost:8080/ui in dev)
2. Find hydra.v1.ClickhouseUserService
3. Enter the workspace ID as the key
4. Call ConfigureUser

Via Restate Cloud (Production)

1. Go to cloud.restate.dev/accounts
2. Login with Google Auth → select unkey team
3. Get your API key:
   • From AWS Secrets Manager, or
   • Create one in Restate Cloud → Developers → API Keys

Via UI

1. Find hydra.v1.ClickhouseUserService and click Playground
2. Enter your API key in the Auth section
3. Set key to the workspace ID in Parameters
4. Click Send API Request

Via curl

curl -X POST "https://<environment-id>.env.<region>.restate.cloud:8080/hydra.v1.ClickhouseUserService/ws_abc123/ConfigureUser" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{}'

Find <environment-id> and <region> in your Restate Cloud dashboard.

What Gets Created

For workspace ws_abc123, the workflow creates:

• User: ws_abc123 with encrypted password
• Row policies: One per table, filtering to workspace_id = 'ws_abc123' and retention window
• Quota: Rate limits on queries and execution time
• Settings profile: Memory and result size limits

Troubleshooting

"Service not found"

The ClickhouseUserService is optional. Check:

• UNKEY_CLICKHOUSE_ADMIN_URL is set in ctrl-worker
• ctrl-worker logs for connection errors

"Quota exceeded" errors for user

Re-run ConfigureUser with higher quota values.

Password issues

If a user can't authenticate, their ClickHouse password may be out of sync with MySQL. Delete from both and re-run the workflow:

-- ClickHouse
DROP USER IF EXISTS ws_abc123;

-- MySQL
DELETE FROM clickhouse_workspace_settings WHERE workspace_id = 'ws_abc123';

Then call ConfigureUser again to generate fresh credentials.