When should this skill be used?

When adding a service, sidecar, or container that reads or writes ClickHouse, adding a new ClickHouseUser, or hand-building a ClickHouse pool or client for a custom timeout or setting.

Authenticating to ClickHouse

SkillDatabases & data

Authenticating to ClickHouse with a rotating token is a skill that guides an AI agent through setting up ClickHouse authentication for a new or changed service using the short-lived ch-podauth ServiceAccount token instead of a static password. It covers the token-aware default paths, choosing the user shape, and wiring the deploy side in the charts repo.

Use Authenticating to ClickHouse in Claude, ChatGPT or Ahel Desktop

Free. Sign in, add Authenticating to ClickHouse and connect your AI. About a minute.

Claude ChatGPT Ahel Desktop

Also: Claude Code · Cursor · Codex

Then ask your AI: use the Authenticating to ClickHouse skill

Details

Instructions available. Your AI can read the instructions. Execution depends on the setup they require.

Account requirements not reviewed. Check the skill instructions before use; ahel provides instructions and does not run this skill.

No other account needed.

Have an agent that can load skills and access the relevant codebase, including posthog/clickhouse/client/AGENTS.md.

Authenticating to ClickHouseStart free

What your AI can do with it

Walks through authenticating a service to ClickHouse with the rotating ch-podauth
Shows the token-aware default paths: sync_execute with ch_user and the async get_client
Helps choose between a deployment-default user and a new ClickHouseUser enum member
Explains that hand-built pools must pass credential_provider or they silently fall back
Warns that tokens must be read per connection, not cached at startup
Points to the deploy-side wiring in the charts repo and the connect-app-to-clickhouse

Getting started

Have an agent that can load skills and access the relevant codebase, including posthog/clickhouse/client/AGENTS.md.
Add the authenticating-to-clickhouse skill so the agent can use it as the entry point.
Ask the agent to set up authentication for the service, sidecar, container, or ClickHouseUser you are adding.
Follow the agent's guidance on wiring the username env and the deploy side in the charts repo.

What this skill tells your AI

The instructions your AI receives, as published by posthog/posthog in .agents/skills/authenticating-to-clickhouse/SKILL.md and read by ahel’s review.

A service authenticates to ClickHouse with a short-lived ServiceAccount token, validated by the ch-podauth bridge, not a static password. The token rotates, so the client reads it on each use. Read posthog/clickhouse/client/AGENTS.md for the full recipe and the traps. This skill is the entry point.

Use it when adding a new service or ClickHouse user, or when building or changing a ClickHouse pool or client by hand. Converting an already-deployed user off a static password is a ClickHouse-team operation and is out of scope.

Do

Use the token-aware default paths: sync_execute(..., ch_user=...) for pooled queries, or the async get_client in posthog/temporal/common/clickhouse.py for HTTP. Both read the token on each use.
Choose the user shape: deployment-default (the pod's default user is the service) or a new ClickHouseUser enum member. Wire the username env, or the user silently authenticates as the default user.
Wire the deploy side in the charts repo. The connect-app-to-clickhouse skill mounts the token and sets CLICKHOUSE_<USER>_PASSWORD_FILE.

Do not

Pass your own sync_client to sync_execute, or build a pool or client by hand, without keeping it token-aware. A native pool must carry credential_provider; an HTTP or one-shot client resolves the token per call instead. A pool that skips this silently stays on the static password. posthog/clickhouse/client/AGENTS.md has both shapes.
Read the credential once at startup, in any language. The token rotates, so read the token file on each connection or request.

Signals

GitHub stars: 40k
Forks: 3k
Last commit: Sep 2026

Others that do the same job

authenticating-to-clickhouse
Skill · posthog

Questions

When should this skill be used?: When adding a service, sidecar, or container that reads or writes ClickHouse, adding a new ClickHouseUser, or hand-building a ClickHouse pool or client for a custom timeout or setting.
Can it convert an already-deployed user off a static password?: No. Converting an already-deployed user off a static password is a ClickHouse-team operation and is out of scope for this skill.

Advanced

Item type: skill
Key: authenticating-to-clickhouse
Source: github.com/posthog/posthog

github.com/posthog/posthog