Quick Start¶

Prerequisites¶

Go 1.26+
A running ClickHouse instance
A running Vault instance (dev mode is fine for testing)

Build the plugin¶

make build              # bin/clickvault, current OS/arch
make build-linux-amd64  # bin/clickvault-linux-amd64
make sha256             # builds linux/amd64 and prints its sha256sum

Register with Vault¶

Build the plugin, register it with Vault's plugin catalog, then configure a connection and roles. The scripts/setup_vault.sh script automates all of this against a dev Vault server:

export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=<token with access to sys/plugins and the database engine>
export CLICKHOUSE_VAULT_ADMIN_PASSWORD=<password for ClickHouse admin user>

./scripts/setup_vault.sh

Manual setup¶

If you prefer to do it step by step:

SHA256=$(sha256sum bin/clickvault-linux-amd64 | awk '{print $1}')

vault secrets enable database

vault plugin register \
  -sha256="$SHA256" \
  database clickvault

vault write database/config/pos-clickhouse \
  plugin_name=clickvault \
  connection_url="clickhouse://clickhouse:9000" \
  username="vault_admin" \
  password="$CLICKHOUSE_VAULT_ADMIN_PASSWORD" \
  cluster=""

Create a dynamic role¶

vault write database/roles/pos-analytics-dynamic \
  db_name=pos-clickhouse \
  creation_statements='CREATE USER "{{username}}" IDENTIFIED WITH sha256_password BY '"'"'{{password}}'"'"'; GRANT analytics ON default.* TO "{{username}}";' \
  default_ttl="24h" \
  max_ttl="48h" \
  password_policy="clickhouse-password-policy"

Read a lease with vault read database/creds/pos-analytics-dynamic. Vault creates a new ClickHouse user for that lease and drops it automatically when the lease expires or is revoked.

Create a static role¶

vault write database/static-roles/pos-service-account \
  db_name=pos-clickhouse \
  username="pos_service" \
  rotation_period="72h" \
  password_policy="clickhouse-password-policy"

The ClickHouse user pos_service must already exist. Vault rotates its password every 72 hours and hands out the current password with vault read database/static-creds/pos-service-account.