Roles¶

Dynamic roles (ephemeral credentials)¶

Dynamic roles create short-lived ClickHouse users on demand. Each lease produces a unique user that is automatically dropped when the lease expires or is revoked.

Creation statements¶

There is no built-in default: a dynamic role must always set creation_statements, since only the operator knows which database and role the new user should be granted.

Single node:

CREATE USER "{{username}}" IDENTIFIED WITH sha256_password BY '{{password}}';
GRANT analytics ON default.* TO "{{username}}";

With a cluster configured, ClickVault turns the same statements into:

CREATE USER "{{username}}" ON CLUSTER 'prod' IDENTIFIED WITH sha256_password BY '{{password}}';
GRANT ON CLUSTER 'prod' analytics ON default.* TO "{{username}}";

You write the single-node version; ClickVault inserts the ON CLUSTER clause at the position ClickHouse's grammar requires.

Revocation statements¶

If a role does not set revocation_statements, ClickVault falls back to:

DROP USER IF EXISTS "{{username}}";

Because DROP USER IF EXISTS does not error on a missing user, deleting a user that is already gone is not an error. This holds for custom statements too, as long as they also use IF EXISTS.

Static roles (managed rotation)¶

Static roles manage an existing long-lived ClickHouse user. Vault rotates the user's password on a configurable schedule.

Rotation statements¶

If a static role does not set rotation_statements, ClickVault falls back to:

ALTER USER "{{username}}" IDENTIFIED WITH sha256_password BY '{{password}}';

(With ON CLUSTER '<cluster>' inserted after the user name when a cluster is configured.)

Statement templates¶

Vault roles supply the actual SQL ClickVault runs, using these placeholders:

A raw statement string can contain multiple ;-separated statements; each one is templated and executed independently.

Security¶

ClickHouse DDL cannot be parameterized, so ClickVault substitutes the generated username and password into the statement as literal text. It rejects any value containing a single quote, double quote, backtick, backslash or control character; a user create/rotate will fail rather than run unsafe SQL.