per-user server_role to impersonate a Postgres role on the backend

[ziomarco]

Stacked on the pgdog-plugin ABI PR; only the last three commits are new here.

This adds a per-user server_role setting to users.toml so a pool can log in to Postgres as its configured server user and run every session as another role. It is usable on its own without any plugin, and the plugin host wiring builds on it in the next PR.

The role is passed in the startup packet rather than set with SET ROLE after connecting, which makes it the session's reset value. I checked this against Postgres 18: RESET ROLE and DISCARD ALL fall back to the startup role, and RESET ALL leaves role alone, so connection cleanup does not need to special-case it.

Clients on such a pool cannot change the role themselves. SET ROLE, RESET ROLE, SET SESSION AUTHORIZATION and the set_config('role', ...) spellings, including inside multi-statement queries and over the extended protocol, get a normal 42501 error and the session stays open. To make that reliable the query parser is always used for these users, since the regex fast path would otherwise let SELECT set_config(...) through. A role parameter that a client sends in its own startup packet is dropped on these pools with a warning, because PgDog would otherwise sync it to the server as SET "role" on every checkout.

PgDog warns at config load when a server_role user has no backend credential of its own, and the users.toml JSON schema and example file document the setting.

One thing to be clear about: the parser guard is a best effort filter, not the security boundary. It is a denylist over the AST and can be worked around, for example with set_config('ro'||'le', ...), a set_config call inside a CTE or a second select target, or a plpgsql DO block. The real boundary is Postgres membership: SET ROLE only works for roles the session user is a member of, so the server user should only be granted the roles it is meant to impersonate.

What the guard does have to get right is that an escape cannot outlive the session that made it. role is GUC_NO_RESET_ALL, so RESET ALL leaves an escaped role in place and the next client to check that connection out would inherit it. Pool cleanup now resets the role on check-in for server_role pools, which restores the startup-packet value, i.e. the impersonated role, not "no role". DISCARD ALL already covered this, so the extra statement only appears on the cleanup paths that did not. backend::pool::test::test_server_role_restored_on_checkin escapes the role behind the parser's back (talking straight to the server, as a DO block would) and asserts the next checkout of the same connection is back to the impersonated role; without the cleanup change it inherits the escaped one.

Forcing the query parser on for these users silently overrides query_parser = "off", so config load now warns about that per user, and the field documentation says so too.

🤖 Generated with Claude Code