You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add copyable prompts for all 50 non-INFO checks, using each finding's actual objects and observed values.
Include read-only diagnosis and approval safeguards.
Use the same SQL file for installation or upgrade, preserve metadata, and generate shared helpers from canonical SQL.
Type of Change
New health check
Bug fix
Performance improvement
Documentation update
Refactoring/code cleanup
Breaking change
Related Issues
None.
Testing
PostgreSQL Version Compatibility
PostgreSQL 15
PostgreSQL 16
PostgreSQL 17
PostgreSQL 18
Testing notes:
PG17: 618 passed; PG18: 562 passed, one skipped each.
PG15/16: 94 upgrade/view tests passed per version, 10 environment-specific probes skipped.
Generation, data-sync, shell syntax, and diff checks pass.
Managed Database Platforms
Amazon RDS for PostgreSQL
Google Cloud SQL for PostgreSQL (currently unable to test)
Azure Database for PostgreSQL (currently unable to test)
Neon
Supabase
Self-managed PostgreSQL
Platform-specific notes:
Tested the function and both view variants in local containers.
Additional Notes
New and existing function installations both run the complete pgFirstAid.sql; known older signatures upgrade automatically with ownership, grants, and comments preserved.
All installers execute as one atomic statement, including through transaction pooling.
View recovery preserves permissions, comments, and security options; dependent rebuilds stop with RESTRICT. data/agent_prompt.sql is the maintained prompt source; CI checks generated copies.
• Add copyable, finding-specific prompts to non-INFO results across all three SQL installers.
• Include observed evidence, read-only diagnosis, approval safeguards, and safer object
identification.
• Document upgrade requirements and test prompt coverage, permissions, and installer compatibility.
The following are alternative approaches to this PR:
1. Install the prompt helper from a shared SQL file
➕ Keeps guidance in one maintained source instead of three copies.
➖ Standalone installers would require an additional file or a build step.
2. Generate prompts outside PostgreSQL
➕ Avoids changing SQL result signatures and adding a caller-visible helper grant.
➖ Requires another tool and may separate prompts from the exact finding evidence.
Recommendation: Keep database-side generation so each copyable prompt travels with its finding and the installers remain standalone. The equality test helps control duplicated guidance; explicit function-recreation and helper-grant instructions are essential because the appended column changes the function signature and caller requirements.
Files changed (9) +1293 / -68
Enhancement (3) +618 / -68
pgFirstAid.sqlAppend curated prompts to function findings+206/-20
Append curated prompts to function findings
• Adds a helper with check-specific guidance for non-INFO findings and appends agent_prompt to pg_firstAid() results. Improves quoted target evidence for indexes, tables, replication slots, and foreign keys; the new return column requires explicit recreation of existing functions.
view_pgFirstAid.sqlAppend prompts without dropping the self-hosted view+206/-24
Append prompts without dropping the self-hosted view
• Adds the prompt helper and an appended agent_prompt column while switching to CREATE OR REPLACE VIEW to preserve existing view identity. Improves target evidence and identifier quoting in several findings.
view_pgFirstAid_managed.sqlAppend prompts to the managed-platform view+206/-24
Append prompts to the managed-platform view
• Adds matching prompt guidance and an appended agent_prompt column to the managed installer. Replaces the view in place and improves quoted targets and supporting evidence for affected checks.
test_agent_prompts.pyExercise prompt evidence and upgrade behavior+502/-0
Exercise prompt evidence and upgrade behavior
• Adds database-backed tests across all three installers for curated guidance, INFO omission, quoted targets, and column order. Covers view identity and dependencies, function recreation, restricted-role helper grants, and consistency of duplicated helper definitions.
README.mdIntroduce copyable prompts and flag function upgrades+24/-0
Introduce copyable prompts and flag function upgrades
• Adds the feature to the overview, shows how to select prompts, and clarifies that INFO prompts are NULL. Points existing function installations to the required upgrade procedure.
agent-prompts.mdDocument prompt safety, permissions, and upgrades+130/-0
Document prompt safety, permissions, and upgrades
• Describes copying and reviewing finding-specific prompts. Provides helper-grant guidance, view replacement expectations, and a transactional rehearsal for explicit function recreation.
1. Query text reaches the agent prompt for long sessions 🟡 P2🐞 Bug👈 Shift left
Description
The new agent_prompt column passes p_current_value through to the generated prompt, and for the
Long Running Queries and Idle In Transaction checks that value is the raw session SQL from
pg_stat_activity. Any literal values in that SQL, including credentials or personal data, are
therefore copied into a prompt intended for an external agent, in addition to the existing output
column.
Security concern about SQL literals in prompts, but no matching accepted or rejected precedent
found. Subjective, so uncertain.
ⓘ Recommendations generated based on similar findings in past PRs
Evidence
pg_firstAid() now calls pgfirstaid_agent_prompt(... hr.current_value ...). For the 'Long Running
Queries' check, current_value is the raw query from pg_stat_activity, and for 'Idle In Transaction
Over 5 Minutes' it is the truncated query text, so both paths place session SQL inside the
generated prompt.
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
## Issue description
Session SQL text from pg_stat_activity is copied into agent_prompt through p_current_value, so literal values can reach an external agent's context.
## Fix Focus Areas
- pgFirstAid.sql[1217-1243]
- pgFirstAid.sql[1366-1378]
- pgFirstAid.sql[2337-2340]
## Recommended Fix
Do not pass raw query text into the prompt. Pass only the queryid or a short redacted form, or document that agent_prompt must be treated as sensitive. Apply the same change to the matching views.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Installers now fail fast: psql runs with ON_ERROR_STOP=1 so failures stop the install instead of
continuing on the old function; a pgFirstAid.sql preflight DO block raises an explicit upgrade error
for legacy functions; the Python audit catches InvalidFunctionDefinition and psycopg2.Error and
exits with a logged message instead of crashing with a traceback; and the upgrade procedure is
documented.
Description
The new agent_prompt column in pg_firstAid()'s RETURNS TABLE makes `CREATE OR REPLACE
FUNCTION` fail with "cannot change return type of existing function" wherever an older copy is
already installed. The bundled workflows/pgfirstaid_audit.py pulls pgFirstAid.sql from main by
default and runs it with no preceding DROP, catching only OperationalError, so every PR audit
against an existing staging database crashes after merge. workflows/db-health-checks.yml runs `\i
pgFirstAid.sql without ON_ERROR_STOP`, so it keeps going on the old 8-column function and nobody
notices.
2. Query prompts target the wrong database✓ Resolved
Query findings now include dbid, originating database name, userid, and role in object_name, and the
prompt relabels the connection database as "Report connection database" while directing agents to
per-finding evidence for the true target. Query checks are also filtered to the connected database
before ranking.
Description
pgfirstaid_agent_prompt labels every finding with current_database(), but the query checks
retain only the query ID and omit the originating database and user. When a statistics reader sees a
query from another database, its copyable prompt identifies the connected database instead and lacks
the context needed to distinguish that query's statistics.
3. View reinstall no longer recovers from column-type drift✓ Resolved
The view installers now call a shared _pgfirstaid_install_view helper (data/view_installer.sql,
embedded in view_pgFirstAid.sql and view_pgFirstAid_managed.sql). On an incompatible existing layout
it captures owner, grants (including grantors), comments and options, then drops and recreates
v_pgfirstaid with RESTRICT inside an atomic transaction, restores ACLs/comments, and rolls back on
failure. Compatible layouts still use CREATE OR REPLACE VIEW. This directly addresses
column-type/layout drift without the unconditional drop, though via a different mechanism than the
suggested explicit casts and CI upgrade test (the diff adds tests in
testing/test_view_installation.py covering old-layout recovery).
Description
Removing drop view if exists v_pgfirstAid means each installer now depends on `CREATE OR REPLACE
VIEW`. That only succeeds when every existing column keeps the same name, type and position. A
deployed view from an older release with a different layout, or any later check whose union branch
changes a column's resolved type, now makes the installer fail. The removed comment says the drop
existed precisely because of these "conversion issues with new health checks".
The shared agent_prompt template now instructs agents to rehearse transactional changes in staging
with BEGIN/ROLLBACK after explicit approval, and to handle non-transactional operations (VACUUM,
CONCURRENTLY index ops) through a separate staging rehearsal. The same wording is applied to
view_pgFirstAid.sql and view_pgFirstAid_managed.sql.
Description
The shared agent_prompt template requires staging tests but does not instruct agents to rehearse
transactional commands with BEGIN and ROLLBACK. When an agent proposes SQL for a finding, the
prompt can lead it to seek approval without the transactional dry run required by the pgFirstAid
verification workflow.
5. Prompt helper body is copied into three installers✓ Resolved
Canonical helper moved to data/agent_prompt.sql; tools/sync_sql_helpers.py regenerates the embedded
copies in all three installers; the check mode runs in PR Safe Checks
(.github/workflows/pr-safe-checks.yml) so stale copies are rejected before merge.
Description
The entire pgfirstaid_agent_prompt body (50 curated cases plus the template) is duplicated in
pgFirstAid.sql, view_pgFirstAid.sql and view_pgFirstAid_managed.sql, and all three run `CREATE
OR REPLACE` on the same function name. A guidance edit made in one file and missed in another leaves
the copies out of sync. Whichever installer ran last then silently overwrites the shared helper for
the function and both views.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request Summary
Add copyable prompts for all 50 non-INFO checks, using each finding's actual objects and observed values.
Include read-only diagnosis and approval safeguards.
Use the same SQL file for installation or upgrade, preserve metadata, and generate shared helpers from canonical SQL.
Type of Change
Related Issues
None.
Testing
PostgreSQL Version Compatibility
Testing notes:
PG17: 618 passed; PG18: 562 passed, one skipped each.
PG15/16: 94 upgrade/view tests passed per version, 10 environment-specific probes skipped.
Generation, data-sync, shell syntax, and diff checks pass.
Managed Database Platforms
Platform-specific notes:
Tested the function and both view variants in local containers.
Additional Notes
New and existing function installations both run the complete
pgFirstAid.sql; known older signatures upgrade automatically with ownership, grants, and comments preserved.All installers execute as one atomic statement, including through transaction pooling.
View recovery preserves permissions, comments, and security options; dependent rebuilds stop with
RESTRICT.data/agent_prompt.sqlis the maintained prompt source; CI checks generated copies.