[jbylund]

Part 2 of the #35 stack, on top of #119.

#23 closed the SET/RESET/DISCARD grammar holes in the middleware and left one seam open: a statement the middleware declined to answer arrived at the session as raw SQL, where an author had to re-parse it to discover it was connection boilerplate at all — the complaint #23 opened with, narrowed to a couple of statements.

async def set_parameter(self, name: str, raw_value: str | None, parsed_value: SettingValue | None) -> None:
    """Told about every SET, RESET and set_config() the middleware handled."""

Called from the single _apply_set_config funnel, so every route reaches it. Does nothing by default.

Both spellings, because a session wants different ones for different jobs

raw_value is the text the client wrote — what to forward to a real backend. parsed_value is what it means — what to act on.

SET work_mem = '32MB'        raw='32MB'  parsed=32768    int, in the parameter's own unit (kB)
SET row_security = 'tr'      raw='tr'    parsed=True     bool
SET client_encoding = 'utf8' raw='utf8'  parsed='UTF8'   canonicalised
SET app.tenant = 'acme'      raw='acme'  parsed='acme'   a custom GUC has no type to parse
RESET work_mem               raw=None    parsed=None

Both None only for a reset, which is unambiguous: no parameter parses to None.

Handed over rather than read off session_vars. The connection records before it tells, so the parsed value is reachable there — but depending on that would make the order of two statements inside _apply_set_config part of a public contract. Moving the hook call above the write would then leave every session reading stale state, silently.

pg_mimic.settings_values is now exported, so a session can run the same parser over a value this did not hand it — one a real backend reported back. SettingValue is exported too, being in a public signature.

One operation, four spellings

RESET x is SET x TO DEFAULT in Postgres — one statement, one path through guc.c — and _set_value has always mapped DEFAULT and LOCAL to None before anything downstream sees them:

RESET work_mem                          -> ('work_mem', None, None)
SET work_mem TO DEFAULT                 -> ('work_mem', None, None)
SET TIME ZONE LOCAL                     -> ('timezone',  None, None)
SELECT set_config('work_mem', NULL, ..) -> ('work_mem', None, None)

Which is why there is one hook rather than set_parameter plus reset_parameter: two of those say SET, so a reset-specific hook would have nowhere sensible to put them. A session overriding only it would miss two spellings of the same thing, with no symptom. Verified against 18.4 that they really do mean the default — SET work_mem TO DEFAULT reads back 4MB, its boot value.

Refusal restores absence, not just the previous value

Raising PgError rejects the setting and undoes the connection's record. A refused SET app.tenant on a name never set before leaves current_setting('app.tenant', true) IS NULL true, rather than readable-but-blank — different questions, and #32 turns on the difference, being the row-level-security probe for "was this ever set?".

The undo is built before the write, since SET LOCAL touches one dict and everything else touches two.

RESET ALL goes through the funnel a name at a time

Rather than clearing the dicts, so a session hears it as it would hear RESET x written out. A session that refuses one leaves the rest reset — there is no transaction around a RESET ALL, and that is what Postgres does with a failure partway through.

The store stays on Connection

As #35 argues: a bare BaseSession bypasses the middleware chain entirely, and the connection still owes ParameterStatus on the wire and still has to answer SHOW. Putting the store on Session would mean a fallback for the BaseSession case and two things to keep in sync. The session is told, so there is no second source of truth.

Tests

15 in a new tests/test_set_parameter_hook.py, covering each route into the funnel, all four reset spellings, both value spellings, the refusal, the absence-restoring undo, and that a session which does not override the hook is unaffected.

Suite: 875 passed, 17 xfailed.

Remaining in the stack

3. discard() hook
4. dotted custom GUCs in the SET grammar, and _PASSED_THROUGH_SETTINGS reworked — where the role / session_authorization finding from An on_execute effect may be awaited #119 lands

Dotted GUCs already reach the hook through set_config('app.tenant', ...), which is how the refusal tests here are written; part 4 adds the SET app.tenant = 'acme' spelling.

History

The commits show this arriving at a two-argument hook first, with parsed_value reachable only through session_vars. Review moved it to three: the argument against a third parameter was that overrides have to match it, and that cost is real for a released hook but not for one that has never shipped.