[sdairs]

Closes #1156.

Summary

• Postgres handlers now go through CloudClient wrappers. Four handlers reuse wrappers that already existed (list, get, patch, state). Nine new wrappers cover the remaining call sites, and the local unwrap_api is gone. No handler calls client.api() any more.
• Missing services are reported consistently on by-id commands (the bug fix). postgres update's tag pre-fetch now goes through get_postgres_service, so a missing service gives "No such Postgres service", the resource_not_found JSON code and the list hint. No PATCH is sent.
  • Other by-id writes, and the certs and config get reads, can get a 400 that is a real validation error. On a 400/404 they send one confirming GET of the service, and report not-found only if that GET also rejects the ids. Otherwise the server's own error stands.
  • The extra GET is declared as a conditional permission on each affected command.
• The service query calls are wrapped too: run_service_query, run_service_query_bearer and configured_query_host in services.rs. They pass the raw library error and the unread response through, so query error classification and telemetry stages are unchanged.
• Docs: AGENTS.md and add-cli-command/references/cloud.md now name the query wrappers as the one deliberate raw-error exception, replacing the old "postgres.rs exception" note.

Commits

1. refactor(cli): route handlers through wrappers. No behaviour change.
2. fix(cli): by-id not-found reporting.
3. refactor(cli): wrap the service query calls, plus the docs updates.

Tests

New wiremock tests in tests/cli_request_shape_test.rs:

• update on a missing service, human and --json. No PATCH is sent.
• update --clear-tags on a missing service: PATCH, then the confirming GET, then not-found.
• config patch on a deleted service, human and --json.
• config patch getting a validation 400 while the service exists. The server's message is kept and the code stays http_4xx.

cargo fmt, both clippy configurations, cargo check --no-default-features and cargo test -p clickhousectl (2419 passed) were all run locally.

Not changed

Metrics, logs, slow-queries, prometheus and backup list. Their query parameters make a 400 ambiguous, and they weren't in the issue's scope.

🤖 Generated with Claude Code

---

Note

Medium Risk
Postgres error classification and the new latest.txt release path affect every cloud postgres by-id command and all update/install flows; changes are heavily wiremock-tested but a bad publish would block version discovery.

Overview
Cloud Postgres (#1156) moves every handler off direct client.api() calls onto CloudClient wrappers (including new ones for create/delete/certs/config/password/replica/restore/state). By-id subresource commands use convert_postgres_by_id_result: on 400/404 they issue a confirming service GET before mapping to “missing Postgres service,” so validation errors (e.g. config patch) keep the server message. Permissions add a CONFIRM_POSTGRES_SERVICE conditional on affected commands. services.rs wraps query calls in run_service_query{,_bearer} / configured_query_host while still returning raw library errors for streaming/classification.

Release & self-update: release.yml adds a publish-latest job that writes monotonic latest.txt to S3 and verifies the CDN; clickhousectl update, install.sh, and release docs now prefer that manifest (GitHub releases/latest redirect as fallback, not the rate-limited REST API).

clickhouse-cloud-api: OpenAPI snapshot adds ClickStack log eventNameExpression / severityNumberExpression, MongoDB table mapping mongoConfig.persistDeletedDocuments, plus tests and README notes. The CLI accepts mongoConfig in --table-mapping-json and documents it.

Agent/release reference docs are updated to match (Postgres as the wrapper pattern, query wrappers as the sole raw-error exception, latest.txt checklist).

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