Struct NeonWriteBatch
#[non_exhaustive]pub struct NeonWriteBatch { /* private fields */ }projection-store only.Expand description
An accumulated list of statements, owned outright.
Not a transaction. Nothing has been sent when one of these exists, and nothing
is holding a lock, a snapshot or a connection — because there is no connection
to hold. It is a Vec<SqlStatement> that becomes a single non-interactive
transaction at commit time and is otherwise inert.
This is what type Batch is bound to in the impl below, and it was what the
GAT’s 'a was bound to before ADR-0017 removed it: an owned type that never
had a use for the parameter.
Implementations§
§impl NeonWriteBatch
impl NeonWriteBatch
pub const fn new() -> Self
pub const fn new() -> Self
An empty batch that no store will commit.
This constructor predates the store stamp and is kept, const, because
removing it would be a breaking change to buy nothing — but what it hands
back has to be said out loud, because the type looks usable and is not.
A batch carries the identity of the store that began it, and
ProjectionStore::begin is the only way to obtain that identity. So a
batch from here is stamped with a private sentinel, which commit rejects as
CommitError::ForeignBatch, reset as ResetError::ForeignBatch, and
rollback as its own NeonError::ForeignBatch.
The alternative was to stamp it with the next real identity, which
would make it accepted by no store and rejected by all of them with a
different sentence — the same outcome, reached less legibly. Handing back
something plainly foreign is the honest shape: a caller who reaches for
this instead of begin finds out on the first commit rather than on the
first concurrent one.
pub fn push(&mut self, sql: &'static str, params: Vec<Value>)
pub fn push(&mut self, sql: &'static str, params: Vec<Value>)
Queues a statement written in source, with its values bound beside it.
§Security
The text is fixed and the values are bound, never interpolated. A
statement assembled out of event data at run time is a SQL injection
whose source is the log, and it commits in the same request that
advances the checkpoint, so the projection never replays those events
and nothing re-derives the rows it corrupted. &'static str makes that
a type obligation: a literal, a const or a concat! is accepted, and
an interpolated String does not compile.
use happenstance_neon::NeonWriteBatch;
fn queue(batch: &mut NeonWriteBatch, account: &str) {
batch.push(
format!("DELETE FROM balance WHERE account = '{account}'"),
Vec::new(),
);
}Where the shape of a statement genuinely depends on a run-time value,
reach for push_raw_sql deliberately.
§Parameter count
The values must match the placeholders sql uses, one for one. Nothing
counts them here; the endpoint sees them only at commit or reset
(ProjectionStore). What it refuses is CommitError::Store or
ResetError::Store, and nothing moves. Which mismatches it refuses is
unmeasured (ADR-0084): do not rely on a surplus value being refused,
because one may commit.
pub fn push_raw_sql(&mut self, statement: SqlStatement)
pub fn push_raw_sql(&mut self, statement: SqlStatement)
Queues a statement this crate cannot see the provenance of.
The unconstrained twin of push, for a statement whose
text is computed at run time. This crate’s own example is the
conformance probe, whose table name is rendered from the configured
schema.
§Security
The obligation push discharges in the type system moves
to the caller here, in full, and this method’s name is the whole of the
warning: no value may be interpolated into the statement’s text.
Compute placeholders, quote any computed identifier, and bind every
value through SqlStatement::with_params.
§Parameter count
As for push.
pub fn statements(&self) -> &[SqlStatement]
pub fn statements(&self) -> &[SqlStatement]
The queued statements, in the order they will run.
Read-only. A statement enters a batch through push or
push_raw_sql and no other way:
use happenstance_neon::{NeonWriteBatch, SqlStatement};
fn queue(batch: &mut NeonWriteBatch, account: &str) {
batch
.statements
.push(SqlStatement::new(format!("DELETE FROM balance WHERE account = '{account}'")));
}