Struct NeonConfig
#[non_exhaustive]pub struct NeonConfig {
pub schema: Box<str>,
pub event_table: Box<str>,
pub sequence: Box<str>,
pub meta_table: Box<str>,
pub checkpoint_table: Box<str>,
pub isolation: IsolationLevel,
pub max_response_bytes: usize,
}Expand description
Configuration shared by both Neon-backed stores.
§Every name here reaches SQL as an identifier, not as a parameter
The /sql endpoint binds values. A table name is not a value, so every
field below is interpolated into the statement text — which makes a bad one an
injection rather than a type error. Two shapes were available and the weaker
one is the obvious one.
Rejected: validate at construction. A with_event_table returning
Result, or panicking, on anything outside [A-Za-z0-9_]. It reads like a
gate and is not one: this struct’s fields are pub, so a caller can assign
past every setter, and #[non_exhaustive] stops construction from outside
the crate rather than assignment. A guard a caller can walk around is a guard
that will be walked around, and the walk is silent.
Chosen: escape at emission. quote_ident wraps every name in double
quotes and doubles any embedded double quote, which is Postgres’ own quoting
rule and is total — there is no identifier it fails to neutralise, and it
does not have to be reached through a particular door. A table name of
a"; DROP TABLE victim; -- becomes one harmless, entirely unusable
identifier, and the statement fails at name resolution rather than executing
anything. The unit tests at the bottom of this file are that claim, written
out.
The cost is real and is worth stating: quoting makes every name
case-sensitive, so with_event_table("Event") names a different table
from the default event, exactly as it would in hand-written SQL. That is
Postgres’ rule rather than this crate’s, and it is the price of not having a
name that can escape.
§Why a schema at all
The endpoint ignores options=-c search_path=… in the connection string —
measured, SHOW search_path still answers "$user", public — and there is no
session to hold a SET in. So an unqualified name is resolved against
whatever the proxy’s backend happens to have, which is not a property this
adapter can own. Every statement it emits is schema-qualified, and the
fixture’s one-schema-per-instance isolation is bought with this field and
nothing else.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.schema: Box<str>The schema every table below lives in.
Defaults to public. Qualifying rather than relying on a search_path
is not a preference: the /sql proxy discards the connection string’s
options parameter and holds no session, so there is no search_path
this adapter could set and rely on.
event_table: Box<str>The table events are written to.
sequence: Box<str>The sequence positions are drawn from.
Named separately rather than derived as {event_table}_position_seq,
because the derivation would be a second naming rule living in a format!
where nobody looks for one — and because position deliberately carries
no column default, so the sequence is read explicitly at the one
INSERT that allocates and its name is therefore a thing this crate says
out loud rather than a thing Postgres remembers.
meta_table: Box<str>The one-row table holding this store’s
StoreId.
checkpoint_table: Box<str>The table projection checkpoints are written to.
isolation: IsolationLevelThe isolation level for the batched, non-interactive transaction.
Defaults to IsolationLevel::Serializable, which is not Postgres’
default. At ReadCommitted a conditional insert can miss a conflict a
concurrent transaction committed after this one took its snapshot, and
with no interactive transaction there is no second look to catch it. The
price is SQLSTATE 40001 aborts under contention. The event store
retries them, and one that outlives its budget reaches the caller as
AppendError::Busy carrying a
NeonSqlError::is_serialization_failure.
It applies only to a request carrying two or more statements, because that is the only form the endpoint honours the header on — measured, and the reason a conditional append is a two-statement batch rather than the single CTE this crate used to document.
max_response_bytes: usizeThe response-size ceiling, at most MAX_RESPONSE_BYTES.
Implementations§
§impl NeonConfig
impl NeonConfig
pub fn with_schema(self, schema: impl Into<Box<str>>) -> Self
pub fn with_schema(self, schema: impl Into<Box<str>>) -> Self
Overrides the schema every table is qualified by.
pub fn with_event_table(self, table: impl Into<Box<str>>) -> Self
pub fn with_event_table(self, table: impl Into<Box<str>>) -> Self
Overrides the event table name.
pub fn with_sequence(self, sequence: impl Into<Box<str>>) -> Self
pub fn with_sequence(self, sequence: impl Into<Box<str>>) -> Self
Overrides the position sequence name.
pub fn with_meta_table(self, table: impl Into<Box<str>>) -> Self
pub fn with_meta_table(self, table: impl Into<Box<str>>) -> Self
Overrides the store-identity table name.
pub fn with_checkpoint_table(self, table: impl Into<Box<str>>) -> Self
pub fn with_checkpoint_table(self, table: impl Into<Box<str>>) -> Self
Overrides the checkpoint table name.
pub const fn with_isolation(self, isolation: IsolationLevel) -> Self
pub const fn with_isolation(self, isolation: IsolationLevel) -> Self
Overrides the isolation level for batched requests.
pub const fn with_max_response_bytes(self, bytes: usize) -> Self
pub const fn with_max_response_bytes(self, bytes: usize) -> Self
Lowers the response ceiling below MAX_RESPONSE_BYTES.
Raising it above has no effect on the endpoint, which enforces its own cap; the value is clamped so the adapter’s error and the endpoint’s behaviour cannot disagree.
pub fn qualified_event(&self) -> String
pub fn qualified_event(&self) -> String
The event table, quoted and schema-qualified.
pub fn qualified_meta(&self) -> String
pub fn qualified_meta(&self) -> String
The store-identity table, quoted and schema-qualified.
pub fn qualified_checkpoint(&self) -> String
pub fn qualified_checkpoint(&self) -> String
The checkpoint table, quoted and schema-qualified.
pub fn qualified_sequence(&self) -> String
pub fn qualified_sequence(&self) -> String
The sequence, quoted and schema-qualified.
pub fn sequence_literal(&self) -> String
pub fn sequence_literal(&self) -> String
The sequence as the SQL string literal nextval takes.
nextval accepts a regclass, and the way to name a quoted, qualified
sequence to it is a string literal holding the quoted, qualified name —
so the identifier’s own quotes end up inside a literal and the literal
needs its own escaping. Two escaping rules on one value is precisely
where an injection hides, which is why this is one function with one test
rather than a format! at the call site.
A bound $n parameter was the alternative and it works — the endpoint
casts a text parameter to regclass happily. It lost on placeholder
arithmetic: the append’s statement already numbers its guard predicate
from a running index, and threading one more slot through that for a
value that is never caller-supplied buys nothing the escaping below does
not.