ClickHouse / ClickHouse/clickhousectl

Clarify ClickPipe state-command acknowledgments and prerequisites

Open
#842 0 comments 0 reactions 0 assignees View on GitHub
bug cloud
Dominant language
Rust
Stars
74
Forks
5
Avg merge
2d 11h
Merged PRs (30d)
196

Description

## Validated scope and current-PR plan — 2026-09-11

This section records the QA review and the current decision to finalize existing PRs without opening new PRs. It supersedes the proposed routing/fix suggestions in the original report below; the original observations are retained. Central plan: #757.

### Disposition

Deferred from this existing-PR finalization pass. Keep the issue open; no new PR is requested now. This is not a resolution, a severity downgrade, or a waiver of release acceptance.

### Validation and corrections

Current confirmation splices the raw verb; help describes an incomplete state model. Improve acknowledgement wording and source-kind preconditions. The same state immediately after an asynchronous request is not proof of a no-op; do not warn/fail solely on response equality. Terminal-state behavior needs a verified API rule.

---

## Original QA report

Found in the 2026-09-11 QA sweep of the combined PR stack at [`d2c37f81`](https://github.com/ClickHouse/clickhousectl/commit/d2c37f814fff53fe68d636e34103e2d0550bf84d), top PR #823, installed release build (package version still 0.4.2). Reproduced behaviour only; no implementation included.

Severity: medium; on the three most-used verbs.

`clickpipe --help` CONTEXT: "`start` only works on a Stopped or Failed pipe; `stop` works from any state." Observed:

```sh
clickhousectl cloud clickpipe stop "$SVC" "$CDC_PIPE" # already Paused
# Error: BAD_REQUEST: … ClickPipe is already stopped (stop is not universal)
clickhousectl cloud clickpipe get "$SVC" "$CDC_PIPE" --json | jq -r .state # Paused, not "Stopped"
clickhousectl cloud clickpipe start "$SVC" "$S3_PIPE" # state Completed
# ClickPipe qa-cp-s3 start (state: Completed) exit 0 (silent no-op on an excluded state)
```

`ClickPipeState` has 15 variants (`Paused`, `Pausing`, `Setup`, `Snapshot`, `Modifying`, `Resync`, `Degraded`, …); the help acknowledges two.

The confirmation is `println!("ClickPipe {} {} (state: {})", name, command, state)` — it splices the raw subcommand verb ("ClickPipe X stop", "ClickPipe X resync") and shows the state from the API's immediate response, which is usually the *pre-transition* state, so "stop (state: Completed)" reads as though nothing happened.

Suggested: replace the CONTEXT sentence with something true ("`stop` fails on an already-stopped pipe; a stopped CDC pipe reports Paused"); per-verb wording ("Stopping ClickPipe X (state: Pausing)"); warn (or exit non-zero) when the returned state equals the pre-call state on a terminal pipe.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the `clickpipe --help` state guidance, the `ClickPipeState` handling, and the confirmation built by `println!("ClickPipe {} {} (state: {})", name, command, state)`. Verify the API rules for each state transition and terminal state, then confirm that help and acknowledgments describe the actual result rather than the immediate pre-transition state.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.