What's new in clickhousectl v0.4.0

ClickHouse released clickhousectl v0.4.0, adding horizontal autoscaling for Cloud services, ClickPipe schema discovery, finer control over ClickPipe ingestion, partial updates for Postgres configs, and opt-out anonymous usage telemetry. The update introduces new CLI flags such as --min-replicas, --max-replicas, --autoscaling-mode horizontal, --skip-initial-load, --start-after, and --server-id, and moves OAuth tokens to a global location at ~/.clickhouse/tokens.json.

clickhousectl https://github.com/ClickHouse/clickhousectl is the CLI for ClickHouse, local and cloud, built to help both humans and AI agents develop with ClickHouse. v0.3.0 https://clickhouse.com/blog/clickhousectl-v0-3-0 brought agent-aware defaults, OAuth querying for Cloud, and custom local server configs. v0.4.0 adds horizontal autoscaling for Cloud services, ClickPipe schema discovery, finer control over ClickPipe ingestion, and opt-out anonymous usage telemetry. If you already have it installed, update in place: 1clickhousectl update If not, install it using your favorite method below: 1curl https://clickhouse.com/cli | sh 2pip install clickhousectl 3uv tool install clickhousectl 4npm i -g clickhousectl 5cargo install clickhousectl Horizontal autoscaling for Cloud services ClickHouse Cloud services have two autoscaling modes: vertical a fixed replica count with variable memory per replica and horizontal fixed memory per replica with a variable replica count . v0.4.0 exposes horizontal autoscaling on service create and service scale : 1clickhousectl cloud service create --name my-service \ 2 --min-replicas 2 --max-replicas 8 --autoscaling-mode horizontal 3 4clickhousectl cloud service scale <service-id \ 5 --min-replicas 2 --max-replicas 8 --autoscaling-mode horizontal The horizontal flags are mutually exclusive with the vertical ones --num-replicas , --min-replica-memory-gb / --max-replica-memory-gb as a variable range , and the CLI rejects --min-replicas without --max-replicas before making any network call. Horizontal autoscaling requires the org-level feature to be enabled. ClickPipe schema discovery beta clickpipe schema-discover probes a Kafka or Kinesis source and returns the inferred fields and types without creating a pipe. Use it to preview the --column definitions before you create the pipe for real. It takes the same source connection flags as the corresponding create subcommand, minus the destination options: 1clickhousectl cloud clickpipe schema-discover <service-id kafka \ 2 --brokers 'broker:9092' --topics events \ 3 --format JSONEachRow \ 4 --auth SCRAM-SHA-256 --username user --password pass Note that schema-discover requires an API key and does not support a read-only OAuth login. Finer control over ClickPipe ingestion Object storage pipes with continuous ingestion get two new controls: --skip-initial-load skips the initial snapshot and only ingests new objects, and --start-after resumes ingestion after a specific object key: 1clickhousectl cloud clickpipe create object-storage <service-id \ 2 --name my-s3-continuous-pipe \ 3 --source-url 'https://bucket.s3.us-east-1.amazonaws.com/data/ ' \ 4 --format JSONEachRow \ 5 --continuous \ 6 --queue-url 'https://sqs.us-east-1.amazonaws.com/123/my-queue' \ 7 --start-after obj-key-001 \ 8 --database default --table events \ 9 --column "event id:Int64" --column "name:String" --skip-initial-load only applies when --queue-url is set, and it's mutually exclusive with --start-after . MySQL CDC pipes can now set the replication server ID with --server-id , useful when multiple pipes read from the same MySQL instance or to avoid colliding with existing replicas: 1clickhousectl cloud clickpipe create mysql <service-id \ 2 --name my-mysql-pipe \ 3 --host mysql.example.com \ 4 --username root --password pass \ 5 --table-mapping "mydb.users:mydb users" \ 6 --server-id 4242 Partial updates for Postgres configs cloud postgres config patch now applies true partial updates. Pass only the settings you want to change and everything else in the config keeps its current value: 1clickhousectl cloud postgres config patch <pg-id --set max connections=500 Global OAuth tokens OAuth tokens from cloud auth login now live globally at ~/.clickhouse/tokens.json , alongside your versions and configs. Existing project-local token files are migrated automatically on first use. OAuth remains read-only . API key credentials credentials.json stay project-local. Use API keys for destructive permissions on a per-org / per-project level. Safer local server lifecycle local server stop <name is now idempotent, matching docker stop and systemctl stop . Stopping a server that exists but isn't running succeeds with exit code 0 instead of erroring. Unknown names still fail, so typos surface. --json output gains an already stopped field so scripts can tell a real stop from a no-op. local remove <version now refuses to delete a version that a running server is using. Previously it deleted the binary out from under the server and reported success. It fails with the server names listed, and --force stops them first: 1clickhousectl local remove 26.5 2 Error: Version 26.5 is in use by running server s : default. 3 Stop them first, or pass --force. 4 5clickhousectl local remove 26.5 --force 6 Stopped server 'default' 7 Removed 26.5 --config is now the primary flag for local server start --config-file still works as a hidden alias , and stop-all flushes its progress output immediately, so it no longer looks frozen during the graceful-kill wait. Anonymous usage telemetry v0.4.0 adds anonymous usage telemetry to help us understand which commands matter. Each event contains: the command path, the names of flags passed never values, never positional arguments , the exit code, the CLI version, OS and architecture, whether it ran in CI, and whether it ran under a detected coding agent. There is no install ID and no fingerprinting . The first run of clickhousectl prints a one-time telemetry notice and sends no telemetry, giving you the opportunity to opt-out before anything is sent. Opting out works any of these ways: 1 Persistently, per machine 2clickhousectl telemetry disable 3 4 Check the current state 5clickhousectl telemetry status 6 7 Per environment/shell https://consoledonottrack.com 8export DO NOT TRACK=1 To see exactly what would be sent without sending it, set CHCTL TELEMETRY DEBUG=1 . You can compile telemetry out entirely with cargo build --no-default-features . Full details are in the telemetry docs https://clickhouse.com/docs/interfaces/cli telemetry . Running server in one command On a fresh install you can now start a server without setting a default or specifying a version and it will automatically install the latest master build of ClickHouse. 1clickhousectl local server start clickhousectl also now records the etag of an installed master build. If the build hasn't moved, the installed binary is reused on successive installs: 1clickhousectl local install latest 2 first run: downloads master 3clickhousectl local install latest 4 latest is up to date master build unchanged ; using 26.7.1.1 Better update visibility clickhousectl looks for an available update when you run a command, caches the result, and does not look again for 24 hours. The "update available" message is now more present on successive commands to encourage more frequent updating. Running clickhousectl update updates the binary, and clears the cache.