pub struct PreparedStatements { /* private fields */ }Expand description
Per-connection prepared-statement state for the proxy: which canonical
statements are prepared on this backend (LRU-bounded), plus the
bookkeeping to filter the backend’s ParseComplete/CloseComplete
replies that answer messages halephant injected on the client’s
behalf.
halephant proxies the extended query protocol with statement-name
rewriting and transparent (re)preparation, so it emits Parse/Close
messages the client never sent (re-prepares, LRU evictions) and
absorbs others (client statement closes). The backend’s reply stream
therefore carries ParseComplete/CloseComplete messages that do not
match what the client expects, and the proxy must filter them — in
FIFO order, correct under pipelining, and rolled back if a Parse is
rejected.
The cache and the reply bookkeeping are deliberately one type so the
invariant between them — every optimistic insert pairs with a queued
reply disposition, and the error path reverts both — is enforced
inside these methods rather than by convention across call sites. The
methods are pure and return intents; the async proxy layer executes
the wire actions. See
docs/superpowers/specs/2026-06-30-halephant-prepared-statement-state-design.md
for the alternatives considered.
Lives next to ServerConn because it is state that follows a
connection through its lifetime — created at connect_server time,
travelling through checkout and checkin.
Construct only via PreparedStatements::new so the LRU cap is
always explicit; there is no Default (which would silently mean an
unbounded cache). Pass max = 0 to opt into unlimited caching.
Implementations§
Source§impl PreparedStatements
impl PreparedStatements
pub fn new(max: u32) -> Self
Sourcepub fn note_client_parse(&mut self, canon: &str) -> ClientParse
pub fn note_client_parse(&mut self, canon: &str) -> ClientParse
Handle a client Parse for canon. On a cache hit the statement
is already on the backend, so the caller answers synthetically; on
a miss the caller forwards the rewritten Parse and the backend’s
real ParseComplete flows back to the client in order.
Sourcepub fn note_reprepare(&mut self, canon: &str) -> Reprepare
pub fn note_reprepare(&mut self, canon: &str) -> Reprepare
Handle an internal re-prepare triggered by a Bind/Describe
whose statement the client never (re-)Parsed. The injected
ParseComplete is suppressed.
Sourcepub fn note_portal_close(&mut self)
pub fn note_portal_close(&mut self)
Record that a client portal Close is being forwarded, so its
CloseComplete is delivered to the client.
Sourcepub fn next_parse_reply(&mut self) -> Reply
pub fn next_parse_reply(&mut self) -> Reply
Disposition of the next ParseComplete from the backend. Defaults
to forwarding when nothing is tracked, so an unexpected reply
surfaces to the client rather than being silently dropped.
Sourcepub fn next_close_reply(&mut self) -> Reply
pub fn next_close_reply(&mut self) -> Reply
Disposition of the next CloseComplete from the backend.
Sourcepub fn roll_back_after_error(&mut self)
pub fn roll_back_after_error(&mut self)
Reconcile after a backend ErrorResponse aborts the current
extended-protocol batch: every message after the error is skipped,
so the still-pending replies never arrive. Roll back the optimistic
inserts of the unconfirmed Parses and drop the orphaned Close
bookkeeping.
Sourcepub fn discard_all(&mut self)
pub fn discard_all(&mut self)
DISCARD ALL deallocated every prepared statement on the backend.
Sourcepub fn reset_pending(&mut self)
pub fn reset_pending(&mut self)
Drop pending reply bookkeeping at a transaction or session boundary. A client that disconnected mid-batch can leave a disposition whose reply the backend skipped and will never send; the cache itself persists across the boundary.