ClickHouse / ClickHouse/clickhousectl
Remove misleading Postgres promote and switchover wait flags
- 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
The flags and role polling exist; their removal is a product-policy change recorded in this issue, not a regression in an open PR. The root AGENTS.md does not independently state a universal no-wait policy. Do not retain the same dual-primary note unchanged: #839 explicitly challenges it. A service isPrimary bit is not necessarily proof of an internal HA node switchover, so replacement verification guidance must match the operation.
---
## 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: design alignment.
Project decision: the CLI does not grow `--wait` flags. It targets agents, which poll `get` in a shell loop rather than use a `--wait`, so convergence polling built into the CLI is not worth its surface. PR #627 (merged 2026-09-01, fixes #604) added `--wait [--wait-timeout SECONDS]` to `promote` and `switchover` as the only way to confirm a role change, because the state endpoint returns 200 whether or not anything happens.
The QA sweep also showed the flag cannot do its job for the case it exists for: on an HA pair the standby has no service ID, so the target's `isPrimary` never flips and `switchover --wait` times out after 120 s even with `haType=async`. Without `--wait` the command exits 0 having done nothing.
Scope:
- Remove `--wait` and `--wait-timeout` from both commands and the polling code in `postgres.rs` (`wait_target`, the budget mapping, tests in `cli_request_shape_test.rs`).
- Keep the promote stderr note about the dual-primary window.
- Replace the README `--wait` paragraph with a one-liner: confirm with `cloud postgres get | jq .isPrimary` / `postgres list --filter isPrimary=true`.
- Leave `local postgres start --wait-timeout` alone: it bounds readiness before credentials are printed, not convergence.
Related: the API-side fix (reject switchover with no standby) is tracked in #835.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start in postgres.rs, including wait_target and its budget mapping, then inspect the related tests in cli_request_shape_test.rs and the README --wait paragraph. Confirm the promote dual-primary note remains, leave local postgres start --wait-timeout unchanged, and verify the command shapes, tests, and documentation no longer describe the removed flags.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- postgresql, rust
- Domain
- cli, databases
- Issue type
- Refactor
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100