From 2a65d59b94735d7a1c56d1ef272c656aa2ad78a1 Mon Sep 17 00:00:00 2001 From: sdairs Date: Wed, 16 Sep 2026 12:18:08 +0100 Subject: [PATCH 1/2] docs: keep the root README focused on CLI behavior (#974) --- AGENTS.md | 10 +++++++--- README.md | 6 +----- crates/clickhouse-cloud-api/AGENTS.md | 4 ++++ crates/clickhouse-cloud-api/README.md | 11 +++++++++-- 4 files changed, 21 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8ea1f75b..85b6e662 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,8 @@ `CLAUDE.md` is a symlink to this file. Edit `AGENTS.md`; never replace the symlink. clickhousectl (`chctl`) is the CLI for ClickHouse and Postgres, local and in ClickHouse Cloud. Use `--help` to -learn the current command surface. `README.md` is the user-facing doc; do not duplicate it here. +learn the current command surface. Root `README.md` documents the CLI; the API library has its own README. +Do not duplicate user-facing documentation here. ## Commands @@ -16,7 +17,7 @@ learn the current command surface. `README.md` is the user-facing doc; do not du If `deprecated-fields` changed, also `cargo check --workspace --all-features`. **Done** means: `cargo fmt --all`; both clippy configurations clean; tests pass for every crate touched; -classifier mappings updated if a file was added or renamed; `README.md` updated for user-visible behaviour; +classifier mappings updated if a file was added or renamed; the relevant README updated for user-visible behaviour; work on a branch, with an associated issue and a PR. ## Workspace @@ -172,5 +173,8 @@ Use `cargo add` with the latest version and an explicit crate, e.g. `cargo add - ## Git workflow and documentation - Branch per feature/issue and use the PR workflow. PRs should have an associated issue. -- PRs should include `README.md` updates for functionality or behaviour users and developers must understand. +- Root `README.md` sections document `clickhousectl` CLI capabilities and behaviour. Update them only for + functionality exposed through the CLI. API-library-only changes (including OpenAPI drift remediation) belong + in `crates/clickhouse-cloud-api/README.md`; do not add Rust methods, models, migration notes, or analyzer + changes to the root README. A library-only PR does not require a root README change. - Keep `AGENTS.md` up to date when development practice changes materially. diff --git a/README.md b/README.md index dc347697..61d03ec1 100644 --- a/README.md +++ b/README.md @@ -997,9 +997,7 @@ Upgrade-window days are numeric: `0` is Sunday, `1` Monday, through `6` Saturday Pass `--allowed-origins` on first creation or to change browser access (`'*'` explicitly allows every origin). Use `--replace-open-api-keys` with `--open-api-key` to deliberately replace the entire authorized-key list. The command reads the existing configuration before updating; a failed or incomplete read prevents changes to unknown fields. Avoid concurrent changes to the same query endpoint. -The Rust API client's `ServiceClickhouseSettingsPatchRequest` uses a map of setting names to JSON values, and `ServiceClickhouseSettingsPatchResponse.settings` returns the applied map. The published OpenAPI now describes both fields as nonempty objects with string or integer values. Use `ServiceClickhouseSettingsPatchRequest` and `ServiceClickhouseSettingValue` for typed requests; the default JSON-value map remains source-compatible with existing callers. Explicit `ServiceClickhouseSettingsPatchRequest` callers remain supported: encoded objects are validated and serialized as objects before sending. - -`ServiceClickhouseSetting.value` is `Option`: the published contract permits strings and integers. The response aliases `ServiceClickhouseSettingValueResponse` and `ServiceClickhouseSettingsMapResponse` retain arbitrary JSON to tolerate future response types. Values retain their JSON types; missing and null values remain absent. `cloud service settings get` and `list` preserve these types in `--json` output; human output displays string values without JSON quotes and numeric values as numbers. +`cloud service settings get` and `list` preserve setting values' JSON types in `--json` output; missing and null values are omitted. Human output displays string values without JSON quotes and numeric values as numbers. `service settings schema` discovers the setting names and accepted types for a service. `settings set` changes only the names supplied: repeat `--setting NAME=JSON_VALUE`, or pass a JSON object such as `{"compatibility":"24.8","enable_analyzer":1}` with `--settings-file` (`-` reads stdin). String values in `--setting` must retain their JSON quotes. The CLI sends settings as a JSON object and preserves each accepted value's JSON type. Numeric literals must be integers from -9223372036854775808 to 18446744073709551615; overflow, decimal and exponent literals are rejected before networking to prevent rounding. Use JSON strings for decimal or exponent values when the setting accepts them. A settings file contains the map itself, not a `{ "settings": ... }` request wrapper; malformed or empty input fails before any network request. Unknown setting names are sent to the API for validation. `settings unset` is idempotent and resets one setting to its platform default; it does not assign JSON `null`. @@ -2895,8 +2893,6 @@ Creation and version creation each request a new upload URL, stream the ZIP arch All three list commands expose `--cursor` and `--limit` (1–100) and retain pagination in JSON output. Detail and list output tolerate missing fields and new response status values. -The UDF API request models preserve `deterministic` and nullable `memoryLimitMib` in both executable variants, including version creation. The OpenAPI analyzer checks inline union payload fields and request requiredness; its report format is version 5. - ## CLI help checks `cargo test -p clickhousectl --bin clickhousectl cli::tests::` checks clap's full command tree, diff --git a/crates/clickhouse-cloud-api/AGENTS.md b/crates/clickhouse-cloud-api/AGENTS.md index dbc2eb1d..39b42f56 100644 --- a/crates/clickhouse-cloud-api/AGENTS.md +++ b/crates/clickhouse-cloud-api/AGENTS.md @@ -3,6 +3,10 @@ Read with the root `AGENTS.md` (commands, workspace rules, CI gates). This file covers the published API library and the private drift analyzer, which are always edited together. +Document library capabilities, Rust caller migrations, and analyzer changes in this crate's `README.md`. +OpenAPI drift remediation alone does not require a root `README.md` update: its feature sections describe +CLI capabilities and behaviour, so update them only when a change is exposed through `clickhousectl`. + ## Layout - `src/client.rs` — `Client` and shared HTTP machinery; endpoint methods live in private per-domain `src/client/*.rs`. diff --git a/crates/clickhouse-cloud-api/README.md b/crates/clickhouse-cloud-api/README.md index f614ba8f..efc9f73a 100644 --- a/crates/clickhouse-cloud-api/README.md +++ b/crates/clickhouse-cloud-api/README.md @@ -10,7 +10,7 @@ BigQuery and Pub/Sub source models now distinguish service-account and workload- `ServiceProfile` now represents the profile discovery response (`profile`, `cpu_cores`, `memory_gi`); the former `Service.profile` value enum is named `ServiceProfileName`. Dynamic profile names remain lossless through its `Unknown(String)` variant. -ClickStack models now include alert channel lists, 30-second alert intervals, query-timeout errors, chart formulas and series limits, dashboard variables and broadcast filters, service-version expressions, and typed SQL/variable saved-filter unions. New formula and saved-filter response/request pairs support explicit fallible write-back through `TryFrom`; absent nested required fields return their wire names. UDF responses include `deterministic`. +ClickStack models now include alert channel lists, 30-second alert intervals, query-timeout errors, chart formulas and series limits, dashboard variables and broadcast filters, service-version expressions, and typed SQL/variable saved-filter unions. New formula and saved-filter response/request pairs support explicit fallible write-back through `TryFrom`; absent nested required fields return their wire names. UDF responses include `deterministic`. UDF request models preserve `deterministic` and nullable `memoryLimitMib` in both executable variants, including version creation. The current alert request schemas have no `required` array or optional marker on either `channel` or `channels`, so both fields remain strict in the Rust request models. This mirrors the documented requiredness policy; it does not establish whether the server accepts a channels-only request. Supply the channel list explicitly rather than relying on the empty `Default` value (the API specifies 1–10 channels). @@ -20,6 +20,12 @@ Kinesis source format enums now include `Protobuf`. Set `ClickPipePostKinesisSou The beta Query API endpoint management methods are `query_api_endpoint_create`, `query_api_endpoint_get`, `query_api_endpoint_list`, `query_api_endpoint_update`, and `query_api_endpoint_delete`. Create and update take `PublicQueryApiEndpointRequest`; list accepts an optional cursor and limit (1–100) and returns `items` with `pagination.next_cursor`. User-owned endpoints can be listed and read, but cannot be updated or deleted through this API. +### ClickHouse settings models + +`ServiceClickhouseSettingsPatchRequest` uses a map of setting names to JSON values, and `ServiceClickhouseSettingsPatchResponse.settings` returns the applied map. The published OpenAPI now describes both fields as nonempty objects with string or integer values. Use `ServiceClickhouseSettingsPatchRequest` and `ServiceClickhouseSettingValue` for typed requests; the default JSON-value map remains source-compatible with existing callers. Explicit `ServiceClickhouseSettingsPatchRequest` callers remain supported: encoded objects are validated and serialized as objects before sending. + +`ServiceClickhouseSetting.value` is `Option`: the published contract permits strings and integers. The response aliases `ServiceClickhouseSettingValueResponse` and `ServiceClickhouseSettingsMapResponse` retain arbitrary JSON to tolerate future response types. Values retain their JSON types; missing and null values remain absent. + ## Development ### Structure @@ -122,7 +128,8 @@ the module trees rooted at `client.rs`, `models.rs`, and `meta.rs`, including private per-domain files. That same analyzer powers the scheduled live-spec issue, so operation, model, field, optionality, beta, deprecation, enum, snapshot, and stale-exemption findings share one implementation. The single -ignored test runs the same report against the live spec. +ignored test runs the same report against the live spec. The analyzer also checks +inline union payload fields and request requiredness. ### Optionality exemptions From de34792c8fa3168dbff19040a028f0335d8e84e5 Mon Sep 17 00:00:00 2001 From: sdairs Date: Thu, 17 Sep 2026 17:14:44 +0100 Subject: [PATCH 2/2] chore: refresh PR #975 stack mergeability All 58 direct and cumulative stack merges succeed, but GitHub retains an unknown result and a test-merge ref from older branch heads. Trigger a fresh calculation without changing the source tree.