Struct EvalContext 

pub struct EvalContext<'a> {

    pub columns: &'a [ColumnSchema],
    pub table_alias: Option<&'a str>,
    pub params: &'a [Value<'static>],
    pub default_text_search_config: Option<&'a str>,
    pub sequence_resolver: Option<&'a SequenceResolver<'a>>,
    pub catalog: Option<&'a Catalog>,
    pub mysql_dialect: bool,
    pub session_gucs: Option<&'a BTreeMap<String, String>>,
    pub users: Option<&'a UserStore>,
    pub fn_depth: u16,
    pub engine: Option<&'a Engine>,
    pub sample_rng: Option<&'a Cell<Option<u64>>>,
    pub recursion_base: Cell<usize>,
    pub render_style: RenderStyle,
    pub tz_offset_fn: Option<TzOffsetFn>,
    pub tz_localize_fn: Option<TzLocalizeFn>,
    pub tz_abbrev_fn: Option<TzAbbrevFn>,
    pub salt_fn: Option<SaltFn>,
    pub backend_pid_fn: Option<BackendPidFn>,
    pub wal_lsn_fn: Option<WalLsnFn>,
    pub backend_signal_fn: Option<BackendSignalFn>,
    pub clock: Option<ClockFn>,
    pub xact: Option<XactView<'a>>,
    pub assigned_xid: Cell<Option<u64>>,
}

Resolution context for evaluating a single row. table_alias is the alias (or table name) callers should accept as the qualifier on a column ref — e.g. FROM users AS u makes u.name valid and rejects other.name.

Fields

columns: &'a [ColumnSchema]

table_alias: Option<&'a str>

params: &'a [Value<'static>]

v6.1.1 — bound parameters for $N placeholders inside the expression tree. Empty for simple queries; populated by the prepared-statement Execute path with Bind values converted to Value. Index N (1-based per PG) hits params[N-1].

default_text_search_config: Option<&'a str>

v7.12.1 — session text-search config (from SET default_text_search_config = '<name>'). Resolved when the engine builds an EvalContext and consumed by the FTS function dispatcher when to_tsvector(text) / plainto_tsquery(text) etc are called without an explicit config arg. None falls through to simple.

sequence_resolver: Option<&'a SequenceResolver<'a>>

v7.17.0 Phase 1.1 — nextval / currval / setval resolver. The engine builds this around a &mut Catalog so apply_function can mutate sequence state without eval owning a catalog reference. When None, sequence functions return an error (read-only contexts).

catalog: Option<&'a Catalog>

v7.37.16 (16.12) — read-only catalog reference for builtins that need catalog walks (e.g. pg_partition_root, pg_partition_ancestors). None falls through to the “no catalog available” branch which returns NULL — same shape PG returns for a non-existent OID. Most evaluation sites don’t need catalog access (row scans, projections); they construct contexts with catalog: None and the engine populates Some(&self.catalog) only at the engine’s top-level entry points where the borrow is unambiguous.

mysql_dialect: bool

v7.39 (round 346, M1) — is this a MySQL-dialect session? The two dialects disagree about what counts as a truth value: MariaDB takes any non-zero number (and a string’s leading number) as true, PG refuses anything that is not boolean. Set from the engine by EvalContext::with_engine; a context built without one keeps PG’s stricter reading.

session_gucs: Option<&'a BTreeMap<String, String>>

Session GUCs set via SET name = value / set_config, keyed by lowercased name. current_setting('app.foo') reads custom (namespaced) settings from here — the mechanism apps use for request context / RLS. None in read-only contexts that have no session; unknown names then fall through to PG defaults.

users: Option<&'a UserStore>

v7.39 (read01 round 58) — the engine’s role store, so has_table_privilege('bob', …) can expand bob’s role MEMBERSHIPS (a grant to a group role answers true for its inheriting members). None in a context with no engine behind it — the role then stands alone.

fn_depth: u16

v7.39 (read01 round 61) — how deep we are inside USER-DEFINED function bodies. A function’s body is evaluated with a child context, and a body may call another function, so this bounds the recursion (a function that calls itself would otherwise blow the stack, which an embed host cannot catch).

engine: Option<&'a Engine>

v7.39 (read01 round 63) — the ENGINE, for a user-function body that has its own FROM (SELECT v FROM t WHERE id = k). Such a body has to run through the real executor: reading catalog’s rows straight from eval would bypass the row-header visibility filter, so under in-place MVCC a function would happily read DEAD rows. None in a context with no engine behind it — a body with a FROM then errors, saying so.

sample_rng: Option<&'a Cell<Option<u64>>>

v7.38 (read01 U15) — per-scan deterministic sampler state for TABLESAMPLE … REPEATABLE(seed). A fresh cell is created before a scan whose predicate may draw __tsm_fract(seed); the cell holds None until the first draw seeds it from that literal, then a scan-local xorshift sequence (isolated from the process-global random() PRNG, so it’s deterministic and rescan-stable). None here means no sampler is attached.

recursion_base: Cell<usize>

v7.38 (read01 P3.25) — native-stack-overflow guard. Lazily seeded with the stack pointer of the outermost eval_expr call; deeper calls compare their own pointer against it and bail with EvalError::StackDepthExceeded once usage crosses a safe margin, so a pathologically nested expression errors instead of aborting the process. Owned (not a borrowed cell) so it stays stack-local and never touches Engine’s Sync bound.

render_style: RenderStyle

v7.39 (GUC knife 3) — session render style (DateStyle / IntervalStyle / extra_float_digits) for text output produced inside expression evaluation (::text casts). Contexts built away from the session (per-shard scan filters, index probes) keep the default — they don’t render text output.

tz_offset_fn: Option<TzOffsetFn>

v7.39 (tz epic) — host IANA timezone lookups for named zones (session rendering, AT TIME ZONE, literal zone suffixes).

tz_localize_fn: Option<TzLocalizeFn>

tz_abbrev_fn: Option<TzAbbrevFn>

salt_fn: Option<SaltFn>

v7.38 (read01 P5.24) — host-provided CSPRNG (the server injects /dev/urandom). Cryptographic builtins (gen_random_bytes, gen_salt) draw from this instead of the process-static xorshift PRNG, so their output isn’t predictable. None (no host CSPRNG) falls back to the PRNG — fine for the non-cryptographic random().

backend_pid_fn: Option<BackendPidFn>

v7.39 (read01 pgstatfuncs.c) — calling-connection identity for pg_backend_pid(); None (embedded / detached contexts) → 1.

wal_lsn_fn: Option<WalLsnFn>

v7.39 (round 476) — the WAL byte position, for the LSN functions.

backend_signal_fn: Option<BackendSignalFn>

v7.39 (round 318, V51) — host connection-control hook for pg_cancel_backend / pg_terminate_backend. None (embedded / detached contexts) ⇒ there is nothing to signal, so they answer false rather than pretending the signal landed.

clock: Option<ClockFn>

v7.38 (read01 P6.08) — host wall clock (µs since Unix epoch). uuidv7 uses it for the real time-ordered 48-bit millisecond prefix; None (no host clock) falls back to the deterministic anchor.

xact: Option<XactView<'a>>

v7.38 (T24) — read-only view of the engine’s transaction-version state, so the txid_* / pg_*_xact_id / pg_xact_status builtins report the real transaction ids instead of a constant stub. None on the scan / join / aggregate contexts that never evaluate them.

assigned_xid: Cell<Option<u64>>

v7.38 (T24) — PG’s txid_current() ASSIGNS an id to a transaction that has none. In autocommit a read-only statement has no writer version, so the first call allocates one here and later calls in the same statement reuse it — SELECT txid_current(), txid_current() must agree, as in PG.

Implementations

impl<'a> EvalContext<'a>

pub const fn new( columns: &'a [ColumnSchema], table_alias: Option<&'a str>, ) -> Self

pub const fn with_render_style(self, style: RenderStyle) -> Self

v7.39 (GUC knife 3) — attach the session render style.

pub const fn with_backend_signal_fn(self, f: Option<BackendSignalFn>) -> Self

v7.39 (round 318, V51) — attach the host connection-control hook.

pub const fn with_wal_lsn_fn(self, f: Option<WalLsnFn>) -> Self

v7.39 (round 476) — attach the WAL byte-position provider.

pub const fn with_backend_pid_fn(self, f: Option<BackendPidFn>) -> Self

v7.39 (read01 pgstatfuncs.c) — attach the calling-connection id.

pub const fn with_tz_fns( self, offset: Option<TzOffsetFn>, localize: Option<TzLocalizeFn>, abbrev: Option<TzAbbrevFn>, ) -> Self

v7.39 (tz epic) — attach the host timezone lookups.

pub fn zone_offset_at(&self, zone: &str, utc_micros: i64) -> Option<i64>

v7.39 (tz epic) — offset (µs east) of an arbitrary zone spec at a UTC instant: fixed forms resolve statically, named zones through the host tzdb. None = unknown zone.

pub fn session_tz_offset_at(&self, utc_micros: i64) -> i64

v7.39 (tz epic) — the SESSION zone’s offset at a UTC instant (per-value: DST zones vary within one statement).

pub fn session_tz_abbrev_at(&self, utc_micros: i64) -> Option<String>

v7.39 (tz epic) — the session zone’s designation at an instant (named zones only; None lets renderers spell UTC / +HH).

pub fn zone_local_to_utc(&self, zone: &str, local_micros: i64) -> Option<i64>

v7.39 (tz epic) — local wall micros in zone -> UTC micros (PG’s DST disambiguation for named zones).

pub const fn with_salt_fn(self, f: Option<SaltFn>) -> Self

v7.38 (read01 P5.24) — attach the host CSPRNG so cryptographic builtins don’t fall back to the predictable PRNG.

pub const fn with_clock(self, f: Option<ClockFn>) -> Self

v7.38 (read01 P6.08) — attach the host wall clock so uuidv7 gets a real time-ordered prefix instead of the deterministic anchor.

pub const fn with_sample_rng(self, cell: &'a Cell<Option<u64>>) -> Self

v7.38 (read01 U15) — attach a per-scan TABLESAMPLE REPEATABLE sampler cell. The cell (seeded lazily on first __tsm_fract draw) must outlive the context and be created fresh per scan so a rescan re-seeds and reproduces the same sample.

pub const fn with_engine(self, engine: &'a Engine) -> Self

Attach the session’s GUC map so current_setting can resolve custom (namespaced) settings written with SET / set_config. v7.39 (read01 round 63) — thread the engine (see engine).

pub const fn with_users(self, users: &'a UserStore) -> Self

v7.39 (read01 round 58) — thread the role store (see users).

pub const fn with_session_gucs(self, gucs: &'a BTreeMap<String, String>) -> Self

pub const fn with_catalog(self, catalog: &'a Catalog) -> Self

v7.37.16 (16.12) — attach a read-only catalog reference so builtins like pg_partition_root can walk partition roles. Defaults to None (NULL semantics).

pub fn session_tz_offset(&self) -> i64

v7.38 (T-tstz Phase 2) — the micro-offset of the session TimeZone GUC (SET TimeZone = '+09' → +9h). A fixed offset / abbreviation resolves; UTC and an unset GUC give 0; a named IANA zone (no tzdata) also gives 0 so a timestamptz still renders — as +00 — rather than erroring on every display. Timestamptz rendering / cast is the only consumer.

pub const fn with_xact(self, xact: XactView<'a>) -> Self

v7.38 (T24) — attach the transaction-version view the txid_* builtins read. Defaults to None, where they fall back to the process-wide cursor.

pub const fn with_sequence_resolver( self, resolver: &'a SequenceResolver<'a>, ) -> Self

v7.17.0 — attach a sequence resolver. The engine wraps a &mut Catalog in a closure that performs the requested SequenceOp.

pub const fn with_params(self, params: &'a [Value<'static>]) -> Self

v6.1.1 — attach a parameter buffer for $N placeholder resolution. The slice must outlive the context; callers construct it from the prepared statement’s Bind values.

pub const fn with_default_text_search_config(self, cfg: Option<&'a str>) -> Self

v7.12.1 — attach the session’s default_text_search_config. Used by the FTS function dispatcher when no explicit config arg is given.

Trait Implementations

impl<'a> Clone for EvalContext<'a>

fn clone(&self) -> EvalContext<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.