recon_gen._dev.perf

Dev tooling — top-N expensive query capture (Y.2.gate.c.10).

Lifted from scripts/dump_top_queries.py (W.8a) so both the standalone script (still in place until Y.2.gate.f.4 deletes it) and the in-process e2e conftest fixture import the same helpers.

Sources:

  • PostgreSQL — pg_stat_statements (auto-loaded on Aurora; needs CREATE EXTENSION pg_stat_statements once per database).

  • Oracle — v$sqlstats (DBA view; the admin user on RDS Oracle SE2 has read access by default).

  • SQLite — no equivalent stats view; caller skips and writes a “skipped” marker.

Both available sources are cumulative across the operator’s other workloads on the shared DB. The like_pattern filter narrows to queries whose text contains the configured substring (default: the L2 instance prefix) so the output is ours, not noise from other tenants.

All helpers are pure functions on the connection / row data — the caller owns connection lifecycle and “where to write the file”.

Functions

dialect_name(dialect)

Stable string representation for path/filename use.

fetch_top_queries(conn, dialect, *, ...)

Run the dialect-appropriate top-queries query.

format_skipped(*, title, dialect, reason)

Render a "we tried but couldn't" marker.

format_top_queries_markdown(*, title, ...[, ...])

Render a perf-debug markdown table from rows fetched above.
recon_gen._dev.perf.dialect_name(dialect)[source]

Stable string representation for path/filename use.

Mirrors the script’s "postgres" if cfg.dialect is POSTGRES else "oracle" shape but covers SQLite explicitly. Used for $RECON_GEN_RUN_DIR/db/<dialect>/top-queries.md paths.

Return type:

str

Parameters:

dialect (Dialect)

recon_gen._dev.perf.fetch_top_queries(conn, dialect, *, like_pattern, top)[source]

Run the dialect-appropriate top-queries query.

For PG, idempotently bootstraps pg_stat_statements (Aurora rds_superuser can; locked-down PGs raise InsufficientPrivilege which we swallow so the next query falls into the caller’s “skipped” path). For Oracle, the v$sqlstats.sql_fulltext column is a CLOB; the last column gets .read()-ed here so downstream formatters stay dialect-agnostic.

Raises whatever the underlying driver raises — the caller is responsible for the “stats view unavailable / skipped” fallback.

Return type:

list[tuple[Any, ...]]

Parameters:

  • conn (Any)

  • dialect (Dialect)

  • like_pattern (str)

  • top (int)

recon_gen._dev.perf.format_skipped(*, title, dialect, reason)[source]

Render a “we tried but couldn’t” marker. Caller writes this when the stats view is unavailable, the connection failed, or the dialect isn’t supported. Output stays valid markdown so the CI artifact upload + downstream readers don’t choke.

Return type:

str

Parameters:

  • title (str)

  • dialect (str)

  • reason (str)

recon_gen._dev.perf.format_top_queries_markdown(*, title, dialect, like_pattern, rows, note=None)[source]

Render a perf-debug markdown table from rows fetched above.

Renders empty-row state as _No matching rows._ (CI artifacts that ran zero matching queries are still valid evidence).

Return type:

str

Parameters:

  • title (str)

  • dialect (str)

  • like_pattern (str)

  • rows (list[tuple[Any, ...]])

  • note (str | None)