paramdef-range-validation

name	paramdef-range-validation
description	Use when adding or reviewing KubeBlocks ParametersDefinition cue/tpl numeric ranges, or when a reconfigure OpsRequest passes validation but the database cannot restart. Forces practical_min/practical_max validation instead of copying vendor hard limits.
allowed-tools	Bash(kubectl *) Bash(helm *) Bash(rg *) Read

Parameter Range Validation

Hard Rules

1. Schema guards startup, not documentation theory. A range in ParametersDefinition must block values that make the database fail to start.
2. Use practical_min / practical_max, not doc_hard_min / doc_hard_max. Vendor docs often describe parser limits, not values that can run a real instance.
3. Every numeric lower bound needs evidence. If you write >=N, be able to say how N was tested.
4. Always set an upper bound. A lower-only range still allows values that can exhaust PID, memory, file descriptor, or engine resource limits.
5. Version upgrades reset the evidence. Do not reuse a 12c / 5.7 / old-major range for a new major engine version without a boundary test.
6. Separate default, recommendation, and guardrail. The schema rejects unsafe values; defaults and docs recommend good values.

When To Invoke

Use this skill when:

• Writing a new ParametersDefinition / cue / tpl file.
• Reviewing any int & >=..., int & <=..., min/max, or enum-like numeric range.
• Debugging reconfigure where validation succeeded but the engine failed to restart.
• Upgrading an addon to a new major engine version or KubeBlocks parameter API version.

Review Checklist

For each numeric parameter:

1. Identify the source of each bound:
   • doc_hard_min/max
   • observed startup boundary
   • resource cap
   • arbitrary default copied from examples
2. Require a startup proof for practical_min:
   • value at practical_min starts successfully
   • value at practical_min - 1 is rejected by schema or demonstrably unsafe
3. Require a resource proof for practical_max:
   • container resources can tolerate the value
   • engine hard max is not exceeded
4. Add a negative validation case:
   • unsafe low value must fail during ValidatePhase
   • unsafe high value must fail during ValidatePhase
5. Confirm runtime readback after a valid reconfigure:
   • OpsRequest success alone is not enough
   • read the parameter from the running engine

Incident Triage

If reconfigure is stuck after a numeric change:

1. Check whether the value passed schema validation.
2. Check engine logs for startup failure after writing that value.
3. If the value is below practical startup requirements, classify the bug as schema guard too weak.
4. Fix the schema first. Do not paper over it by only changing the test.
5. Add a boundary-negative test so the same value is rejected before engine restart.

Bad Patterns

Pattern	Why It Fails	Fix
Copy vendor minimum directly	Parser accepts it, engine may not start	Use tested practical minimum
Lower bound only	Huge values can exhaust resources	Add practical upper bound
Default as schema minimum	Rejects values that are safe but not recommended	Keep default separate
OpsRequest Succeed as proof	Runtime may not apply or engine may restart later	Perform engine readback
Shared range across major versions	Startup requirements change	Split by engine version

Closeout Language

Good:

Checked parameter range for `processes`: schema now uses practical_min=100, not vendor hard_min=6. Boundary negative `99` is rejected in ValidatePhase; `100` starts and runtime readback confirms applied value.

Bad:

Range looks fine; copied from docs.

Related Docs

• docs/addon-paramdef-cue-range-validation-guide.md
• docs/addon-reconfigure-guide.md
• docs/addon-reconfigure-version-skew-guide.md
• docs/cases/oracle/oracle-12c-processes-cue-paramdef-range-case.md