feat(local): rename local server to local clickhouse; add postgres list and local status (#1159) by sdairs · Pull Request #1169 · ClickHouse/clickhousectl

sdairs · 2026-10-30T14:39:28Z

Closes #1159. Stacked on #1166.

Summary

local server is now local clickhouse. It has a visible alias ch and a hidden alias server, so every existing local server … invocation still parses. local postgres gains a visible alias pg.
Engine-only commands (breaking). These now cover one engine only, per the decision recorded on Add local postgres list and rename local server to local clickhouse (ch) #1159:
- local clickhouse list and local clickhouse stop-all cover ClickHouse only, and never contact Docker. This applies through the server alias too.
- local postgres stop-all was already Postgres-only, and now skips the ClickHouse process scan.
New local postgres list [--json]: Postgres instances in this project.
New local status [--json]: every ClickHouse and Postgres instance in the project. This is the combined view local server list gave on main.
JSON shape is unchanged. status and postgres list return the same object server list --json returned (servers, total_servers, total_running_servers, project_scope, guidance), with the same entry fields.
Telemetry records the canonical name for every alias (local clickhouse …, local postgres …). A new unit test pins this. The recorded path changes from local server … to local clickhouse …, so any dashboards keyed on the old path need updating.
Engine-correct hints (third commit, from review):
- startup_exit and startup_timeout point at their own engine's list.
- Name-only errors (server_not_found, server_not_running, server_running, invalid_server_name) point at local status, because Postgres raises them too.
- The "already running" note on clickhouse start counts ClickHouse only.
- ch stop and ch remove with no name no longer need Docker.
- local status has a short agent-context block.

Release notes (breaking)

local server stop-all and local server list (hidden alias) now cover ClickHouse only. Use local status to see everything, and local postgres stop-all to stop Postgres.
The telemetry command path changes from local server … to local clickhouse ….

Docs

Updated:

README.md
docs/guides/local-development.md and docs/guides/user-defined-functions.md
docs/reference/automation.md and docs/reference/telemetry.md
the cli-help-text skill
the bug report template
scripts/test-postgres-integration.sh

Still to update, outside this repo:

the mono-repo CLI page (docs/concepts/features/interfaces/cli.mdx)
the infra-clickhouse and infra-postgres agent skills

Those still say local server and describe server list as including Postgres. The commands keep working through the alias, but the "includes Postgres" claim is now wrong.

Tests

Parsing: clap tests for every spelling (clickhouse, ch, server, postgres, pg), postgres list and status, with and without --json.
Help: a structural test that clickhouse, ch, pg and status appear in local --help, and server doesn't.
New tests/local_engine_lists_test.rs (no live Docker):
- clickhouse list and stop-all work with Docker unreachable and exclude Postgres.
- postgres list and status are tested against a wiremock Docker.
- Empty lists leave no project state.
Existing tests: expectations updated wherever the alias or the engine-only change affects them.
Gates: fmt, both clippy configurations, the --no-default-features check, cargo test -p clickhousectl and the Python classifier tests all pass.
One flaky test: local_postgres_client_input_test fails intermittently, and also does on the base commit (1 in 6 runs), so the flakiness predates this PR.
Not run: the updated scripts/test-postgres-integration.sh was only syntax-checked. It needs a local postgres:18-alpine image.

🤖 Generated with Claude Code

Note

Medium Risk
Breaking CLI semantics for combined list/stop-all and telemetry command paths, though hidden server alias preserves invocations; broad touch of error/JSON guidance increases regression risk for automation.

Overview
Renames the local ClickHouse command group from local server to local clickhouse, with visible alias ch and a hidden server alias so existing scripts keep working. local postgres gets a visible pg alias.

Splits listing and bulk-stop by engine (breaking vs the old combined local server list / stop-all behavior): local clickhouse list and clickhouse stop-all are ClickHouse-only and skip Docker; local postgres list is new; local status shows both engines in one view (replacing the old combined list). Server metadata recovery and listing can target one engine so ClickHouse lists do not call Docker and Postgres lists do not scan processes.

Updates user-facing guidance across errors, --json recovery commands, README/docs, and telemetry so paths read local clickhouse … and name-only server errors point at local status while startup failures point at the relevant engine’s list.

^{Reviewed by Cursor Bugbot for commit d3a0656. Bugbot is set up for automated code reviews on this repo. Configure here.}

cursor

Stale Bugbot comment from a previous run.

`local server` becomes `local clickhouse`, with the visible alias `ch`. `server` stays as a hidden alias, so existing scripts keep working. `local postgres` gains the visible alias `pg`. Help text, agent context blocks, error hints and guidance commands, and the docs now name `local clickhouse`. Telemetry already records the canonical command name for an alias; a unit test now pins that `server`, `clickhouse` and `ch` all record `local clickhouse ...` on both the successful and the failed-parse capture paths. BREAKING CHANGE: telemetry and JSON guidance record `local clickhouse` where they previously recorded `local server`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…local status (#1159) `local clickhouse list` and `local clickhouse stop-all` now cover ClickHouse only, and recover, check and stop only ClickHouse servers, so they never contact Docker. `local postgres stop-all` likewise recovers and checks only Postgres. New commands: - `local postgres list [--json]` lists the project's Postgres instances in the existing engine-aware list shape. - `local status [--json]` lists every ClickHouse server and Postgres instance in the project: the combined view `local server list` gave before, with the same table and the same JSON object (`servers`, `total_servers`, `total_running_servers`, `project_scope`, and `guidance` when empty). An empty list's hint and JSON guidance name the command that produced it; `postgres list` offers no `--global` hint, since global discovery finds only ClickHouse. BREAKING CHANGE: `local clickhouse list` (and `local server list`) no longer include Postgres instances, and `local clickhouse stop-all` no longer stops them. Use `local status` and `local postgres stop-all`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.

There are 4 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 909696b. Configure here.}

cursor · 2026-10-30T17:32:40Z

+                Err(_) if skip_entry_errors => continue,
+                Err(error) => return Err(error),
+            }
+        }


Omitted-name stop still hits Docker

High Severity

list_clickhouse_server_names_locked still lists every engine and runs Postgres liveness, so a nameless clickhouse stop or clickhouse remove contacts Docker. In a mixed project that fails with docker_unavailable instead of stopping or removing ClickHouse, even though list and stop-all already skip Docker.

Additional Locations (2)

crates/clickhousectl/src/local/mod.rs#L1045-L1053

crates/clickhousectl/src/local/mod.rs#L1150-L1158

^{Reviewed by Cursor Bugbot for commit 909696b. Configure here.}

cursor · 2026-10-30T17:32:40Z

 /// Best-effort count used only for the informational notice during start.
 pub(crate) fn advisory_running_server_count_locked(lock: &MetadataLock) -> usize {
-    list_all_servers_locked_inner(lock, true)
+    list_all_servers_locked_inner(lock, None, true)


Start note counts Postgres too

Medium Severity

advisory_running_server_count_locked still counts every engine, but the clickhouse start note now sends users to local clickhouse list, which is ClickHouse-only. A running Postgres instance inflates the count and will not appear in that list.

Additional Locations (1)

crates/clickhousectl/src/local/mod.rs#L613-L620

^{Reviewed by Cursor Bugbot for commit 909696b. Configure here.}

sdairs · 2026-10-30T18:04:37Z

Small follow-up: preserve Postgres visibility in JSON recovery hints (P3).

This is also covered by the existing inline finding. Confirmed on the current head, 909696bb.

For a stopped Postgres instance named app, chctl local postgres client app --json correctly returns server_not_running, but its error.command is clickhousectl local clickhouse list. Following that suggestion shows no Postgres instances, even though chctl local postgres list --json correctly shows app. The old local server list included both engines; the renamed ClickHouse-only list no longer does.

Suggested correction in crates/clickhousectl/src/local/output.rs:

Use clickhousectl local status for engine-agnostic errors such as ServerNotFound, ServerNotRunning, ServerAlreadyRunning, and InvalidServerName.
For StartupExit and StartupTimeout, use StartupKind to choose local postgres list or local clickhouse list.
Add focused regression coverage for the stopped-Postgres JSON hint and both startup engine variants.

This affects structured recovery advice, including output consumed by coding agents. The ordinary human error message and Postgres operations remain correct, so this is a small troubleshooting fix rather than a merge blocker.

…em (#1159) `local clickhouse list` no longer includes Postgres, so the `--json` recovery command for errors Postgres also raises sent callers to a list that could not show the instance. - `server_not_found`, `server_not_running`, `server_running` and `invalid_server_name` now point at `local status`. - `startup_exit` and `startup_timeout` pick `local clickhouse list` or `local postgres list` from the failing engine. Adds unit coverage for both mappings and a subprocess test that follows the hint for a stopped Postgres instance. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

sdairs · 2026-10-30T18:15:57Z

Resolved in d3a0656, as suggested:

Name-only errors (ServerNotFound, ServerNotRunning, ServerAlreadyRunning, InvalidServerName) now point at clickhousectl local status.
StartupExit and StartupTimeout use StartupKind to choose local clickhouse list or local postgres list.
Tests:
- A unit test covers all four name-only mappings, plus both startup variants for each engine.
- A new subprocess test, stopped_postgres_error_points_at_a_list_that_shows_it, uses a mocked Docker that reports app as stopped. It runs local postgres client app --json and gets server_not_running with command: clickhousectl local status. Then it runs that command and confirms app is listed.
- The server_running expectation in local_server_state_machine_test is updated to match.

The selection-required errors still point at local clickhouse list, because only clickhouse stop and clickhouse remove raise them. UdfServerIsPostgres also still points there, since the fix is to pick a ClickHouse server.

Gates: fmt, both clippy configurations, the --no-default-features check and cargo test -p clickhousectl all pass.

sdairs requested a review from iskakaushik as a code owner October 30, 2026 14:39

cursor Bot reviewed Oct 30, 2026

View reviewed changes

Comment thread crates/clickhousectl/src/local/mod.rs Resolved

Comment thread crates/clickhousectl/src/local/output.rs Resolved

sdairs mentioned this pull request Oct 30, 2026

docs(cli): pin subcommand order in --help (#1158) #1171

Open

sdairs and others added 2 commits October 30, 2026 16:39

sdairs force-pushed the claude/1159-local-clickhouse-rename branch from 90fbc5a to 909696b Compare October 30, 2026 17:27

sdairs added this pull request to stack #1153 October 30, 2026 17:28

cursor Bot reviewed Oct 30, 2026

View reviewed changes

Navigation Menu

Repository navigation

feat(local): rename local server to local clickhouse; add postgres list and local status (#1159) - #1169

feat(local): rename local server to local clickhouse; add postgres list and local status (#1159)#1169
sdairs wants to merge 3 commits into
claude/1077-readonly-no-project-statefrom
claude/1159-local-clickhouse-rename

sdairs commented Oct 30, 2026 •

edited by cursor Bot

Loading

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Oct 30, 2026

Uh oh!

cursor Bot Oct 30, 2026

Uh oh!

Uh oh!

sdairs commented Oct 30, 2026

Uh oh!

sdairs commented Oct 30, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

sdairs commented Oct 30, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Release notes (breaking)

Docs

Tests

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Oct 30, 2026

Choose a reason for hiding this comment

Omitted-name stop still hits Docker

Uh oh!

cursor Bot Oct 30, 2026

Choose a reason for hiding this comment

Start note counts Postgres too

Uh oh!

Uh oh!

sdairs commented Oct 30, 2026

Uh oh!

sdairs commented Oct 30, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

sdairs commented Oct 30, 2026 •

edited by cursor Bot

Loading

cursor Bot left a comment •

edited

Loading