Module within_clause 

WITHIN TENANT '<id>' [USER '<u>'] [AS ROLE '<r>'] <stmt> — a per-statement scope override for tenant + auth identity.

Designed for SaaS deployments where one process / one connection pool serves many tenants. The clause carries the scope inline with the query, so:

• no thread-local state survives the call
• connection pools cannot leak tenant context between checkouts
• async runtimes that move tasks between threads stay correct (the scope lives in a stack pushed/popped by the same execute call — no .await in between)
• clients can use prepared statements normally

Values: string literal ('acme') or NULL (clears just that field).

Structs

ScopeOverride

Per-statement scope override extracted from a WITHIN ... prefix.

Enums

FieldOverride

Tri-state for a single overridable field. Inherit means the WITHIN clause didn’t mention this field and the runtime should fall through to its prior source (session-level or auth-installed). Clear means the clause explicitly set the field to NULL — this must hide the inherited value, not fall through. Set(v) carries the literal value.

Functions

try_strip_within_prefix

Try to recognise a WITHIN TENANT ... <stmt> prefix at the start of input. Returns the parsed scope plus the remainder slice (the inner statement), or None when the input doesn’t start with WITHIN. A malformed WITHIN ... clause returns Err.