cockroachdb / cockroachdb/cockroach
settings: validation bounds (Min/Max) are not surfaced in docs or SHOW CLUSTER SETTING
- 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
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