cockroachdb / cockroachdb/cockroach

settings: validation bounds (Min/Max) are not surfaced in docs or SHOW CLUSTER SETTING

Open
#172,035 3 comments 0 reactions 0 assignees View on GitHub
A-configurability branch-master branch-release-26.3 C-enhancement O-agent O-qa T-db-server
Dominant language
Go
Stars
32.5k
Forks
4.1k
PR merge metrics
PR metrics pending

Description

**Describe the problem**

Many cluster settings have validation bounds — `ByteSizeWithMinimum`,
`ByteSizeWithMaximum`, `IntWithMinimum`, `NonNegativeIntWithMaximum`,
`FloatWithMinimum`, `DurationWithMinimum`, etc. — but those bounds are
captured inside opaque `validateFn` closures and are not exposed
anywhere the user can see them.

Concretely:

- The generated docs at
[`docs/generated/settings/settings.html`](https://github.com/cockroachdb/cockroach/blob/master/docs/generated/settings/settings.html)
list `Setting`, `Type`, `Default`, `Description`, and `Supported Deployments` —
no min/max column.
- `SHOW CLUSTER SETTING ` returns only the current value.
- `SHOW ALL CLUSTER SETTINGS` (and the underlying
`crdb_internal.cluster_settings`) returns the description but not the
bounds.
- The `/_admin/v1/settings` HTTP API likewise omits the bounds.

A user only discovers the bounds when they try to set an out-of-range
value and see a validation error.

**Examples of affected settings**

I sampled 7 byte-size settings with bounds; **none** mention their
bounds in the description:

| Setting | Min | Max |
|---|---|---|
| `kv.snapshot_rebalance.max_rate` | `minSnapshotRate` | — |
| `kv.range.range_size_hard_cap` | 64 MiB | — |
| `kv.raft.command.max_size` | 4 MiB | — |
| `kv.bulk_sst.sync_size` | 128 KiB | — |
| `changefeed.kafka.max_request_size` | `KafkaMaxRequestSizeMin` | `KafkaMaxRequestSizeLimit` |
| `sql.stmt_diagnostics.bundle_chunk_size` | 16 B | — |
| `sql.conn.max_read_buffer_message_size` | 16 KiB | — |
| `sql.status.active_query_text.max_bytes` (new in 26.3) | 1000 B | 64 KiB |

The same gap exists for `int`, `float`, and `duration` settings with
bounds.

**To Reproduce**

```sql
> SHOW CLUSTER SETTING sql.status.active_query_text.max_bytes;
sql.status.active_query_text.max_bytes
------------------------------------------
16 KiB

> SELECT description FROM [SHOW ALL CLUSTER SETTINGS]
WHERE variable = 'sql.status.active_query_text.max_bytes';

description
---------------
maximum length in bytes of the active and last-active SQL text retained
per session and surfaced by SHOW CLUSTER QUERIES, SHOW CLUSTER SESSIONS,
and the corresponding crdb_internal virtual tables; longer text is
truncated with a trailing ellipsis. Larger values increase the memory
used to serialize sessions and the size of the responses.

-- Nothing tells the user that values <1000 B or >64 KiB are rejected:
> SET CLUSTER SETTING sql.status.active_query_text.max_bytes = '128KiB';
ERROR: cannot be set to a value larger than 64 KiB
```

**Expected behavior**

Bounds should be discoverable without trial-and-error. Concretely:

1. Expose validation bounds as a structured field on the setting (not
only in a closure) so they're programmatically accessible. Today
they live inside `validateFn` in
[`pkg/settings/byte_size.go:86-104`](https://github.com/cockroachdb/cockroach/blob/master/pkg/settings/byte_size.go#L86-L104),
[`pkg/settings/int.go`](https://github.com/cockroachdb/cockroach/blob/master/pkg/settings/int.go),
[`pkg/settings/float.go`](https://github.com/cockroachdb/cockroach/blob/master/pkg/settings/float.go),
and
[`pkg/settings/duration.go`](https://github.com/cockroachdb/cockroach/blob/master/pkg/settings/duration.go).
2. Have the docs generator
([`pkg/cli/gen.go`](https://github.com/cockroachdb/cockroach/blob/master/pkg/cli/gen.go))
surface bounds — either as new columns in `settings.html` /
`settings-for-tenants.txt` or appended to the description.
3. Have `SHOW ALL CLUSTER SETTINGS`,
`crdb_internal.cluster_settings`, and the `/_admin/v1/settings`
HTTP API surface bounds the same way.

**Environment**

- CockroachDB v26.3.0-beta.2-dev (also reproduces on master).

**Additional context**

Discovered while QA-testing the new
`sql.status.active_query_text.max_bytes` setting in 26.3. That
setting accepts sub-KiB precision in `[1000 B, 64 KiB]`, which is a
relatively narrow range, but users have no way to discover it without
hitting an error.

Jira issue: CRDB-65177

Contributor guide

Open the contributing guide

Research direction

Start by reading the structured setting and validation implementations in pkg/settings/byte_size.go, pkg/settings/int.go, pkg/settings/float.go, and pkg/settings/duration.go, then trace the docs generator in pkg/cli/gen.go. Check how SHOW ALL CLUSTER SETTINGS, crdb_internal.cluster_settings, and /_admin/v1/settings expose metadata; done means bounds are programmatically available and surfaced consistently across the documented outputs and APIs.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, sql
Domain
backend-api-design, databases, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.