How recommendations work

Each recommendation on the Tuning tab has the same basic shape. The goal is to make it clear:

• what parameter is being discussed
• what pocketPG observed
• what value is being suggested
• how the change would be applied
• how to undo it

Recommendation shape

Field	Description
param	PostgreSQL parameter name (e.g. work_mem, max_wal_size)
category	Grouping: Memory, WAL, Connections, Autovacuum, etc.
current	Current value from pg_settings
recommended	Suggested value
action	INCREASE, DECREASE, SET, NO_ACTION, or INSIGHT
priority	CRITICAL, HIGH, MEDIUM, or LOW
reason	Human-readable explanation with the decision logic
requires_restart	Whether the change needs a PostgreSQL restart
sql	ALTER SYSTEM SET command (or avn service update for Aiven)
rollback_sql	Command to revert to the previous value
evidence	Parameter-specific metrics that drove the decision

If recommended equals current, the recommendation is normalized to NO_ACTION and shown in the collapsed healthy section.

Confidence scoring

Each recommendation also carries a confidence level: LOW, MEDIUM, or HIGH.

Confidence is about evidence quality, not importance.

Example:

• work_mem confidence is lower when statistics were recently reset
• work_mem confidence is lower when the instance is mostly idle and there is little workload to observe
• WAL recommendations are stronger when recent samples show actual checkpoint or write pressure

Low confidence does not mean "wrong." It means pocketPG had less evidence than it would prefer.

Evidence panels

The "Why?" panel expands the evidence used for that recommendation.

Depending on the parameter, this may include:

• current setting values
• recent workload peaks
• spill or WAL signals
• sample quality notes
• caveats about managed providers
• rollback context

Provider awareness

On most PostgreSQL deployments, pocketPG emits SQL such as:

ALTER SYSTEM SET work_mem = '64MB';
SELECT pg_reload_conf();

On Aiven, some parameters are changed through the Aiven API or CLI instead of direct ALTER SYSTEM. For those, pocketPG can show an avn service update command. Parameters that Aiven manages internally are marked as service-managed instead of pretending they are directly configurable.

Per-table settings such as fillfactor or autovacuum storage parameters still use ordinary SQL because they are table DDL, not provider-level service settings.

Recommendation history

When you copy a recommendation, pocketPG records a copy event.

It does not record proof that the SQL was executed successfully.

Copy history is stored in two places:

• Saved instances use a server-backed shared history.
• Raw connection-string sessions use a local browser fallback.

This is useful for review and coordination, but it should be treated as a copy log, not an audit log.

Freshness

Recommendations are based on live inputs. pocketPG avoids serving long-stale recommendation results when recent WAL, connection, or workload signals have changed.