// STRYKE-CLICKHOUSE — CLICKHOUSE CLIENT FOR STRYKE // QUERY + INSERT + DDL + INTROSPECTION

Install

s add github.com/MenkeTechnologies/stryke-clickhouse

On first use Clickhouse, stryke dlopens the cdylib in-process and registers every clickhouse__* export.

Quick start

use Clickhouse

var %conn
$conn{url} = "http://127.0.0.1:8123"

Clickhouse::create_table("events", columns => "ts DateTime, user UInt64, kind String", order_by => "(ts, user)", %conn)
Clickhouse::insert("events", [{ ts => "2026-06-20 12:00:00", user => 1, kind => "click" }], %conn)

p Clickhouse::count("events", %conn)
p Clickhouse::query_value("SELECT uniqExact(user) FROM events", %conn)
val @rows = Clickhouse::query_rows("SELECT kind, count() c FROM events GROUP BY kind", %conn)

Connecting

Connection params come from the %conn opts hash on every call (or $CLICKHOUSE_URL when neither url nor host is given).

Connection params can be passed inline per call or kept in a hash and splatted into every call:

var %conn
$conn{host}     = "ch.internal"
$conn{port}     = 8123
$conn{tls}      = 0
$conn{username} = "reader"
$conn{password} = $ENV{CH_PASS}
$conn{database} = "analytics"

p Clickhouse::ping(%conn)
val @rows = Clickhouse::query_rows("SELECT now()", %conn)

When neither url nor host is present, the client falls back to the $CLICKHOUSE_URL environment variable, so a script can run unchanged across hosts:

export CLICKHOUSE_URL="https://default:secret@ch.example.com:8443/analytics"
s run report.stk     # no %conn needed

A ureq::Agent (HTTP keep-alive pool) is cached per (base_url, auth, database) tuple for the life of the stryke process, so repeated calls to the same target reuse the underlying connection. The database rides on the query string as ?database=, and credentials travel as HTTP Basic (default user default, empty password).

API surface

43 functions in the Clickhouse namespace. Every call (except the pure helpers) takes the trailing %opts connection hash. query returns the full result object; query_rows / query_row / query_value peel off the array / first row / first scalar. exec is for statements that return no rows.

Reference — liveness

Reference — query & write

Reference — introspection

Reference — DDL

Reference — pure helpers

These take no connection and are unit-tested in-crate, so they validate in CI with no server present. Use them to build SQL safely.

Examples

Safe parameterization with the escape helper:

val $name = Clickhouse::escape($user_input)
val @hits = Clickhouse::query_rows("SELECT * FROM events WHERE kind = '$name'", %conn)

Build an IN (…) list and a LIKE pattern without hand-escaping:

val $ids = Clickhouse::format_in_list([1, 2, 3])          # (1, 2, 3)
val @rows = Clickhouse::query_rows("SELECT * FROM events WHERE user IN $ids", %conn)

val $needle = Clickhouse::escape_like($q)
val @found = Clickhouse::query_rows("SELECT * FROM events WHERE kind LIKE '%$needle%'", %conn)

Introspect storage and schema:

p Clickhouse::table_exists("events", %conn)
val @cols = Clickhouse::columns("events", %conn)
val $usage = Clickhouse::disk_usage("events", %conn)
p $usage->{compression_ratio}

for val $proc (Clickhouse::processes(%conn)) {
    p "$proc->{query_id}: $proc->{elapsed}s"
}

DDL and lightweight delete:

Clickhouse::add_column("events", "session", "String", default => "''", %conn)
Clickhouse::optimize("events", final => 1, %conn)
Clickhouse::delete_where("events", "kind = 'spam'", %conn)
Clickhouse::rename_table("events", "events_old", %conn)

Redact a URL before logging it:

p Clickhouse::redact_url("https://user:pw@ch.example.com:8443")   # https://***@ch.example.com:8443

Build & test

make debug       # cargo build
make test        # cargo test, then `s test t/`
make install     # s pkg install -g .

cargo test runs the in-crate unit tests (string/identifier escaping, URL parse/redact, connection key, result extraction) with no server required. t/test_stryke_clickhouse_surface.stk pins the wrapper surface and exercises the pure helpers; t/test_clickhouse.stk runs end-to-end DDL + insert + query against a live server (needs $CLICKHOUSE_URL or 127.0.0.1:8123) and short-circuits when none answers.

Why a package, not a builtin

The HTTP + TLS transport (ureq, rustls) ships once, on demand, as an opt-in package — stryke core is never linked against it. On first use Clickhouse, stryke dlopens the cdylib in-process and registers every clickhouse__* export. The cdylib caches a ureq::Agent keep-alive pool per (base_url, auth, database), so repeated queries reuse the connection.

Sibling packages

Part of the stryke package family. Browse the others via the MenkeTechnologiesMeta umbrella repo:

• stryke-arrow — Apache Arrow / Parquet / Feather
• stryke-aws — S3, DynamoDB, SQS, Lambda, STS
• stryke-azure — Blob, Queues, Cosmos DB, Key Vault, Entra
• stryke-demo — live demos for every connector
• stryke-docker — Docker daemon API
• stryke-duckdb — embedded DuckDB SQL engine
• stryke-email — email + campaign client
• stryke-fleet — parallel expect/PTY automation
• stryke-gcp — Cloud Storage, Pub/Sub, Secret Manager, BigQuery, Firestore
• stryke-grpc — reflection-based gRPC client
• stryke-gui — mouse / keyboard / screen / clipboard automation
• stryke-k8s — Kubernetes
• stryke-kafka — Apache Kafka
• stryke-mcpd — MCP servers without a runtime
• stryke-mongo — MongoDB
• stryke-mssql — Microsoft SQL Server
• stryke-mysql — MySQL / MariaDB
• stryke-neo4j — Neo4j graph (Bolt)
• stryke-office — Office docs / PDF / images
• stryke-parquet — Parquet file inspector
• stryke-polars — Polars + ndarray + linalg + FFT
• stryke-postgres — PostgreSQL
• stryke-redis — Redis / Valkey
• stryke-scrape — web scraping / crawling
• stryke-scylla — ScyllaDB / Cassandra
• stryke-search — Elasticsearch / OpenSearch
• stryke-selenium — browser automation (WebDriver)
• stryke-spark — Spark Connect (no JVM)
• stryke-utils — pure-stryke utility belt
• stryke-zmq — ZeroMQ messaging