Skip to content

Index

ClickVault

ClickVault

A HashiCorp Vault database secrets engine plugin for ClickHouse.

Go GitHub Release License

Full documentation  |  Source Code

ClickVault is a HashiCorp Vault database secrets engine plugin for ClickHouse. It lets Vault create short-lived, ephemeral ClickHouse users on demand (dynamic secrets) and rotate the password of long-lived ClickHouse users on a schedule (static roles), so applications and operators never handle a standing ClickHouse credential directly.

It implements the Vault database plugin SDK interface (sdk/database/dbplugin/v5) and registers itself with Vault as plugin type clickvault.

How it works

Vault's database secrets engine talks to ClickVault over the plugin RPC boundary and calls six methods:

Method Called when What ClickVault does
Initialize vault write database/config/<name> Parses the connection config, builds a ClickHouse connection, verifies the admin user holds the ACCESS MANAGEMENT privilege
NewUser A lease is requested against a dynamic role Generates a username from the template, runs creation_statements
UpdateUser A static role's rotation period elapses Runs rotation_statements to change the user's password
DeleteUser A dynamic secret's lease expires or is revoked Runs revocation_statements (defaults to DROP USER IF EXISTS)
Type Internal to Vault Returns "clickvault"
Close Plugin shutdown / reload Closes the ClickHouse connection

All SQL is built in one place, internal/clickvault/ddl.go. The rest of the plugin never constructs SQL strings itself. That file also handles single-node vs. clustered ClickHouse: if a cluster is configured, every generated statement gets ON CLUSTER '<cluster>' inserted at the grammatically correct position automatically.

Key features

  • Dynamic credentials - ephemeral ClickHouse users created on demand, automatically cleaned up
  • Static role rotation - scheduled password rotation for existing long-lived users
  • Cluster-aware DDL - automatic ON CLUSTER insertion for multi-node ClickHouse
  • SQL injection prevention - rejects values containing quotes, backticks, or control characters
  • Concurrency-safe - single sync.RWMutex protects the connection and config

Next steps

  • Follow the Quick Start to register the plugin and create your first role
  • Learn about Configuration options
  • Understand Roles for dynamic and static credentials
  • Explore the Architecture for implementation details