diff --git a/AGENTS.md b/AGENTS.md index 02924c0c..ad506206 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 @@ -181,5 +182,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 fa1d3943..75405146 100644 --- a/README.md +++ b/README.md @@ -1029,9 +1029,7 @@ Upgrade-window days use `0` for Sunday, `1` for Monday, through `6` for 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 `--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`. diff --git a/crates/clickhouse-cloud-api/AGENTS.md b/crates/clickhouse-cloud-api/AGENTS.md index 84db346a..e94b4952 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 1f1b6c95..bf1b1a88 100644 --- a/crates/clickhouse-cloud-api/README.md +++ b/crates/clickhouse-cloud-api/README.md @@ -32,6 +32,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 @@ -134,7 +140,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