A Case for Agentic Tuning: From Documentation to Action in PostgreSQL

Hongyu Lin, Mingyu Li, Weichen Zhang, Yihang Lou, Mingjie Xing, Yanjun Wu, Haibo Chen · 2026

Read A Case for Agentic Tuning: From Documentation to Action in PostgreSQL by Hongyu Lin, Mingyu Li, Weichen Zhang, Yihang Lou, Mingjie Xing, Yanjun Wu, Haibo Chen (2026) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2605-19988.txt.

Introduction

Hongyu Lin and six colleagues move database tuning from static documentation to agents that act, with a system called PerfEvolve for PostgreSQL. It turns expert tuning methods into executable skills covering version checks, workload-specific profiling and joint optimisation of several parameters at once. On standard TPC-C and TPC-H benchmarks it beats documentation-driven baselines by up to about thirty-five percent.

Catalog record

CREATORHongyu Lin, Mingyu Li, Weichen Zhang, Yihang Lou, Mingjie Xing, Yanjun Wu, Haibo Chen
YEAR2026
COLLECTIONPAPERS
FORMATTXT
FILE SIZE56220
LICENSEhttp://creativecommons.org/licenses/by/4.0/
RIGHTSCC BY
SOURCEarXiv

Source: https://arxiv.org/abs/2605.19988

Browse the full library · About the Tower of Babel

Full text

The opening of the work, from the library's hosted text:

A Case for Agentic Tuning: From Documentation to Action in PostgreSQL Hongyu Lin, Mingyu Li, Weichen Zhang, Yihang Lou, Mingjie Xing, Yanjun Wu, Haibo Chen Abstract Documentation has long guided computer system tuning by distilling expert knowledge into per-parameter recommendations. Yet such guides capture only what experts conclude, discarding how they reason. This fundamental gap manifests in three concrete deficiencies: documentation grows stale as software evolves, fails under heterogeneous workloads, and ignores inter-parameter dependencies. We propose shifting from static documentation to dynamic action for system tuning. We introduce PerfEvolve , which translates expert tuning methodologies into executable skills that equip LLM-based agents to perform version-consistency verification, workload-specific profiling, and multi-parameter joint optimization. Evaluated on PostgreSQL under TPC-C and TPC-H benchmarks, PerfEvolve outperforms state-of-the-art documentation-driven tuning baselines by up to 35.2%. The tool is available at https://github.com/ISCAS-OSLab/PerfEvolve . 1 Introduction Modern computer systems, from operating systems 52 ; 27 ; 10 to database systems 38 ; 32 ; 40 ; 28 , expose hundreds of configurable parameters that govern their runtime behavior. These parameters control everything from memory allocation to I/O scheduling to concurrency policies. Collectively, they define a vast configuration space whose optimal point shifts with hardware generations, workload characteristics, and deployment scale. Navigating this space well can yield order-of-magnitude performance improvements 19 ; 34 ; 35 ; 60 ; navigating it poorly leads to resource waste, latency spikes, and missed service-level objectives. Historically, system operators have relied on documentation as the primary source for tuning expertise: official reference manuals, community-maintained guides, and the built-in rule sets embedded in dedicated tuning tools 48 ; 55 ; 9 ; 46 ; 30 ; 31 ; 29 . Documentation encodes the expertise of system developers and practitioners, distilling years of benchmarking and field observation into recommended defaults, safe operating ranges, and cautionary notes. In a sense, it is the externalized long-term knowledge of the systems community 3 ; 5 ; 20 . The advent of large language models (LLMs) has opened a new frontier in automated tuning. Recent work has proposed feeding documentation directly to LLMs to construct informed priors over the parameter space 47 ; 11 ; 45 . State-of-the-art systems such as GPTuner 22 exemplifies this paradigm: it ingests official manuals and community guides, uses LLMs to extract parameter semantics and value constraints, and injects the resulting knowledge into a Bayesian optimization loop 56 , which significantly narrows the search space compared to uninformed baselines. However, this line of work rests on an implicit assumption that documentation is sufficiently correct . When this assumption is flawed, improvements are bounded by the quality of the documentation itself. Through a systematic analysis of documentation for various production systems 38 ; 32 ; 28 ; 27 ; 1 , we identify three deficiencies that hinder documentation’s utility as a tuning oracle. To ground our analysis, we select a widely deployed relational database system, i.e., PostgreSQL, as a representative running example. PostgreSQL offers a mature documentation ecosystem and has served as the primary benchmark for recent documentation-driven tuning frameworks 22 ; 13 . • Staleness: Documentation lags behind system evolution. PostgreSQL’s random_page_cost still recommends 4.0 since version 7.4, calibrated for rotational HDD, yet the optimal value on SSDs is closer to 1.1 39 ; 37 . • Context insensitivity: Documentation specifies what a parameter does but not when a given value is optimal. PostgreSQL recommends shared_buffers = 25% RAM with no distinction between OLTP and OLAP, SSD and HDD, or read- vs. write-heavy workloads 41 ; 7 ; 24 . • Correlation absence: Documentation overlooks parameter correlation. Our analysis shows that the shared_buffers \times work_mem correlation explains 39% of performance variance, a dependency entirely absent from the official documentation. Insight: process ( how ), rather than results ( what ). The deficiencies above share a common root cause. Documentation records the results of expert tuning, the recommended values that practitioners have concluded through experience, rather than the process by which experts arrive at those recommendations. A result (e.g., “set shared_buffers to 25% of RAM”) is an environment-specific snapshot. It embeds implicit assumptions about hardware, workload, and system version at the time of writing. When any of those assumptions shift, a new server is provisioned, a workload evolves, a version upgrade changes internal behavior, the recommendation becomes stale or misleading. A process (e.g., “measure buffer hit ratio under representative load; adjust shared_buffers across candidate values") is environment-agnostic. It is a reproducible methodology that seeks the best answer for the target environment and workload it is applied to. The process does not become stale when the system version changes. This distinction has a practical implication for automated tuning. In any deployment scenario, active profiling of the target system under a representative workload is necessary to determine the true optimal configuration. Documentation should serve to accelerate profiling: telling the tuning agent what to measure, how to structure its probes, and what decision rules to apply to the signals it observes. Documentation that only provides static recommended values offers none of this guidance; it either leads the agent to blindly apply stale recommendations or reduces it to uninformed random search over the huge configuration space. Proposal. We present PerfEvolve , a tool that operationalizes expert tuning methodology as executable procedural knowledge . Rather than encoding tuning expertise as value or range recommendations, PerfEvolve encodes it as structured procedural knowledge that an LLM-based tuning agent can learn and execute against a live system to determine the optimal configuration for that specific deployment. PerfEvolve accelerates profiling through two novel techniques: • Dimensionality reduction via sensitivity analysis: From hundreds of parameters, PerfEvolve identifies the small subset that materially affects performance for the given workload via top- k sensitivity analysis. Focusing profiling effort on this subset reduces the effective search space by orders of magnitude and concentrates optimization budget on the parameters where it yields the greatest reward. • Topology discovery for joint optimization: Before committing to any configuration, PerfEvolve mines the correlation structure among sensitive parameters and groups strongly correlated ones into joint optimization components. Parameters within a component are tuned together, capturing correlation effects that per-parameter tuning would miss. We compare PerfEvolve against two state-of-the-art systems, GPTuner 22 and E2ETune 13 . PerfEvolve improves PostgreSQL performance by up to 35.2% across OLTP and OLAP workloads in just 30 trials. Under cross-hardware transfer, prior approaches degrade substantially, while PerfEvolve effectively recovers from these degradations by up to 58.9% without requiring hardware-specific retuning. Moreover, PERFEVOLVE eliminates invalid or harmful configurations, raising the success rate of tuning experiments from 68% to 100% and further accelerating convergence. Contributions. We make the following contributions: • We systematically identify three fundamental deficiencies that hinder existing system documentation from serving as an effective and actionable tuning oracle. • We propose a methodology that encodes "procedural knowledge" into system documentation, transforming static recommendations (what to set) into reproducible workflows (how to determine what to set). • We design and implement PerfEvolve , a tool that automates the generation of process-oriented tuning documentation. PerfEvolve provides structured skills that empower LLM-based agents to conduct autonomous profiling. • PerfEvolve significantly improves the system performance over state-of-the-art tuning systems. 2 Characterization of Documentation Gaps 2.1 Documentation Deficiencies Across Systems We survey the

Read the complete text