AgentTune Database Knob Advisor

Produce an evidence-backed tuning plan before proposing any database change. Treat the target DBMS, exact version, workload, hardware, objective, constraints, and baseline as one tuning task; never mix evidence from different major versions.

This skill adapts the four-stage structure described by AgentTune: workload analysis, knob selection, range pruning, and configuration recommendation. It adds explicit source provenance, layered bounds, approval gates, and deterministic validation.

Operating boundary

Default to read-only discovery, research, and planning.
Never apply settings, restart a service, run a load generator, or execute write SQL without the user's explicit authorization for that action and target.
Prefer a clone or staging environment. For production, provide commands and a rollout plan for the operator to review.
Redact passwords, tokens, private hostnames, customer data, and SQL literals before using external search or an LLM.
Preserve the baseline configuration and the exact rollback command before any authorized experiment.

Required context

Collect or request these fields. Mark unknowns; do not silently guess them.

DBMS name, exact version/build, deployment topology, and configuration scope.
CPU count, memory, storage type/IOPS, network limits, container/cgroup limits, and data size.
Representative workload window, SQL mix or benchmark, concurrency, read/write ratio, working set, and peak pattern.
One primary objective such as throughput, p95 latency, or cost, plus guardrails for errors, p99 latency, memory, replication lag, and recovery time.
Current parameter values, restart policy, benchmark budget, and rollback method.

Use read-only queries from references/introspection-queries.md where applicable. Verify them against the exact product version before execution.

Workflow

1. Analyze the workload

Establish a baseline with at least three comparable runs or multiple stable time windows.
Summarize query families, concurrency, read/write mix, resource saturation, cache behavior, locks, log/flush pressure, temp work, and replication constraints.
Separate symptoms from evidence. A high cache miss rate may justify investigating memory knobs; it does not prove that increasing one value is safe.
Define the objective function and rejection gates before selecting knobs.

2. Build an evidence catalog

Follow references/evidence-protocol.md. Search in this order:

Exact-version official parameter documentation.
Exact tag or commit in the official GitHub/source repository.
Live database introspection and shipped sample configuration.
Official release notes, issues, and maintainers' explanations.
Papers and reputable operational material for hypotheses only.

For each candidate capture name, scope, type, unit, current/default value, legal values, hard minimum and maximum, dynamic/restart behavior, dependencies, deprecation status, and source URLs. Record the product version or source tag for every hard-bound claim.

Do not infer a hard minimum or maximum from an LLM response. If the product does not expose a bound, store it as null, explain the uncertainty, and keep the proposed range conservative.

3. Select high-impact knobs

Map each observed bottleneck to mechanisms and then to candidate knobs.
Reject knobs unrelated to the workload, unavailable in this version, deprecated, dominated by another setting, or unsafe under the stated constraints.
Prefer a small set that fits the experiment budget. Start with 5-15 knobs unless evidence supports more.
Document the causal hypothesis for every selected knob and the metric that can falsify it.

4. Prune ranges

Maintain three distinct layers:

hard_min / hard_max: DBMS legality from official evidence or live metadata.
effective_min / effective_max: hard bounds reduced by hardware, topology, units, dependencies, and global/per-session memory envelopes.
recommended_min / recommended_max: the region worth exploring for this workload and objective.

The invariant is hard range ⊇ effective range ⊇ recommended range, with the current value retained as the safe baseline even when it lies outside a provisional recommendation. State formulas for resource constraints, especially per-connection memory and coupled buffers. Keep enum and Boolean domains explicit.

Create knob-catalog.json using the schema demonstrated in examples/knob-catalog.example.json, then run:

python scripts/knob_tool.py validate knob-catalog.json

Fix every validation error before producing candidates.

5. Plan iterative search

Use references/tuning-playbook.md.

Root the search at the unchanged baseline.
Probe one knob at a time at conservative points before combining knobs.
Keep only candidates that pass validity and guardrails; expand around the best reproducible candidates.
Use a bounded beam/tree search when interactions matter. The experiment budget, beam width, and stopping rules must be explicit.
Re-run the baseline periodically to detect environmental drift.
Record every attempted configuration, actual applied values, timestamps, benchmark identity, metrics, logs, failure class, and rollback result.

Generate an initial deterministic plan with:

python scripts/knob_tool.py plan knob-catalog.json --budget 20 --output experiment-plan.json

The script generates a safe ordering; it does not replace benchmarking or causal judgment.

6. Recommend and report

Return:

Scope, assumptions, unknowns, and confidence.
Baseline and objective/guardrail definitions.
Workload findings and selected knobs with causal hypotheses.
Evidence table with direct URLs, exact versions/tags, and conflicts.
Layered ranges with units and dependency formulas.
Ordered experiment plan, approval gates, benchmark method, rollback, and stop conditions.
Results observed so far and the next candidate batch.

Clearly label a value as documented, observed, derived, or hypothesized. Never present an untested candidate as an optimal production configuration.

Search and source guidance

When browser or code-search tools are available, use queries such as:

<DBMS> <exact version> <knob> official documentation minimum maximum
site:github.com/<official-org>/<official-repo> <exact tag> <knob>
repo:<official-org>/<official-repo> path:<config-source-path> <knob>
<DBMS> <exact version> <knob> release notes deprecated restart

Inspect the official repository's tag or commit rather than the default branch when tuning an older release. Search the symbol definition, parser/validator, default table, sample configuration, and tests. Cite source permalinks pinned to a commit when possible.

References

AgentTune paper: https://renata.borovica-gajic.com/data/2026_sigmod.pdf
AgentTune official repository: https://github.com/intlyy/AgentTune