Skip to main content

NeonWriteBatch

Struct NeonWriteBatch 

#[non_exhaustive]
pub struct NeonWriteBatch { /* private fields */ }
Available on crate feature 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

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>)

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)

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]

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}'")));
}

pub fn len(&self) -> usize

How many statements are queued.

Worth watching: the whole batch travels in one request body, so a projection that applies ten thousand events before committing builds a ten-thousand-statement JSON document and sends it in one round trip.

pub fn is_empty(&self) -> bool

Whether anything is queued.

Trait Implementations§

§

impl Clone for NeonWriteBatch

§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
§

impl Debug for NeonWriteBatch

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
§

impl Default for NeonWriteBatch

§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.