ClickHouse / ClickHouse/clickhousectl

Remove misleading Postgres promote and switchover wait flags

Open
#834 0 comments 0 reactions 0 assignees View on GitHub
cloud documentation enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.