Skip to main content

SqliteProjectionStore

Struct SqliteProjectionStore 

pub struct SqliteProjectionStore { /* private fields */ }
Available on crate feature projection-store only.
Expand description

A SQLite-backed projection store.

The Mutex is load-bearing rather than defensive; see the module documentation for what it buys.

Implementations§

§

impl SqliteProjectionStore

pub async fn protect_from_reset( &self, id: &ProjectionId, ) -> Result<(), SqliteProjectionStoreError>

Protects id from reset: every later reset of it, through any handle onto this file, answers ResetError::Refused and applies none of its batch.

The mark is written into the file, so it holds for a handle opened before this call, for a clone, for another process, and after every handle has closed. It guards reset only: commit on a protected projection still commits, because its own runner has to keep running. Protecting a projection that is already protected is not an error.

The first protection a file carries raises its projection schema marker to 2 (see SCHEMA_VERSION), in the same transaction as the mark, so a build that predates protection refuses to open the file rather than reset a protected projection without knowing. The marker is read when a handle opens, so a handle an older build opened before that is not stopped: deploy this build everywhere before protecting.

§Errors

pub async fn allow_reset( &self, id: &ProjectionId, ) -> Result<(), SqliteProjectionStoreError>

Lifts id’s protection, so its next reset proceeds. Lifting a protection id does not have is not an error.

The schema marker does not fall back: a file that has carried a mark stays at the version that knows what one is.

§Errors

As for protect_from_reset.

pub async fn is_protected_from_reset( &self, id: &ProjectionId, ) -> Result<bool, SqliteProjectionStoreError>

Whether id is protected from reset.

The other half of a refusal. ResetError::Refused carries no context on purpose: an operator learns that a reset was declined from the variant, and which policy declined it from the store that holds the policy. This is that read.

§Errors

As for protect_from_reset.

§

impl SqliteProjectionStore

pub fn new(connection: Connection) -> Self

Wraps an already-open connection onto an already-migrated database.

The caller is responsible for having applied the schema — use open to have that done — and the connection is used as it is given, so a caller reaching this constructor directly should have opened it through crate::connection::open_configured.

The schema includes projection_protection, which a file last migrated by a build before 0.5.0 does not have, and reset reads it: open such a file through open once before wrapping a connection to it here.

This is where the batch stamp is minted and where the fallback runtime handle is captured, for calls later made from no runtime at all: it is the point at which a caller is most likely to be inside one.

pub fn open(path: impl AsRef<Path>) -> Result<Self, SqliteProjectionStoreError>

Opens (creating if absent) a store at path and applies the checkpoint schema.

The connection is configured before anything is written to it — WAL, a stated synchronous, and a finite busy timeout — through the one path crate::connection::open_configured both stores in this crate share. Migration is idempotent and safe under a concurrent open.

§Errors
  • SqliteProjectionStoreError::Sqlite if the file cannot be opened or created — a missing directory, a permission refusal, a corrupt header — or if the schema cannot be applied. Nothing partially migrated is left behind: every statement runs inside one transaction.
  • SqliteProjectionStoreError::UnsupportedSchemaVersion if the file was written by a build that knows a later migration. Operating on an unknown schema is how a later migration loses data.
Examples found in repository?
examples/rebuilding-read-models/src/main.rs (line 155)
153async fn run(path: &Path) -> Result<()> {
154    let events = SqliteEventStore::open(path)?;
155    let models = SqliteProjectionStore::open(path)?;
156    let app = open_configured(path)?;
157    app.execute_batch(READ_MODEL_DDL)?;
158
159    seed_the_log(&events).await?;
160    two_views_two_checkpoints(&events, &models, &app).await?;
161    a_third_view_added_late(&events, &models, &app).await?;
162    reset_and_rebuild(&events, &models, &app).await?;
163    one_poisoned_view(&events, &models).await?;
164
165    writeln!(io::stdout().lock(), "\n== final log ==")?;
166    print_log(&events).await?;
167
168    Ok(())
169}
More examples
Hide additional examples
examples/transfers-on-sqlite/src/main.rs (line 129)
127async fn before_the_reopen(path: &Path) -> Result<()> {
128    let events = SqliteEventStore::open(path)?;
129    let models = SqliteProjectionStore::open(path)?;
130    let app = open_configured(path)?;
131    app.execute_batch(READ_MODEL_DDL)?;
132
133    println!("\n== opening two accounts ==");
134    open_account(&events, "a1").await?;
135    open_account(&events, "a2").await?;
136    println!("   a1 and a2 opened");
137
138    println!("\n== depositing 100 into a1 ==");
139    deposit(&events, "a1", 100).await?;
140    println!("   deposited");
141
142    println!("\n== transferring 40 from a1 to a2 ==");
143    transfer(&events, "a1", "a2", 40).await?;
144    println!("   transferred: one append, two events, both accounts checked");
145
146    println!("\n== transferring 500 from a1 to a2 ==");
147    match transfer(&events, "a1", "a2", 500).await {
148        Ok(()) => bail!("an overdrawn transfer should have been rejected"),
149        Err(err) => println!("   rejected: {err}"),
150    }
151
152    println!("\n== projecting balances into the same file ==");
153    let mut balances = Balances::new();
154    let chunk = Chunk::of(CHUNK.try_into()?);
155    let done = run_projection(&events, &models, &mut balances, &Json, chunk).await?;
156    println!("   applied {} event(s)", done.applied);
157    print_read_model(&app)?;
158
159    Ok(())
160}
161
162/// Everything after the reopen, against the same file.
163///
164/// Nothing is carried in from above but the path.
165async fn after_the_reopen(path: &Path) -> Result<()> {
166    println!("\n== everything above is dropped; reopening the same file ==");
167    let events = SqliteEventStore::open(path)?;
168    let models = SqliteProjectionStore::open(path)?;
169    let app = open_configured(path)?;
170    println!("   reopened");
171
172    println!("\n== the read model, straight off disk ==");
173    print_read_model(&app)?;
174
175    println!("\n== the same balances, folded again from the event log ==");
176    for account in ["a1", "a2"] {
177        let balance = fold_balance(&events, account).await?;
178        println!("   {account}: {}", balance.held);
179    }
180
181    println!("\n== the checkpoint survived too ==");
182    let mut balances = Balances::new();
183    let chunk = Chunk::of(CHUNK.try_into()?);
184    let done = run_projection(&events, &models, &mut balances, &Json, chunk).await?;
185    println!(
186        "   re-running the projection applied {} event(s) — the log is not replayed",
187        done.applied
188    );
189
190    println!("\n== the reopened store is live, not merely readable ==");
191    transfer(&events, "a2", "a1", 15).await?;
192    let done = run_projection(&events, &models, &mut balances, &Json, chunk).await?;
193    println!(
194        "   transferred 15 back, and the projection applied {} event(s)",
195        done.applied
196    );
197    print_read_model(&app)?;
198
199    println!("\n== final log ==");
200    print_log(&events).await?;
201
202    Ok(())
203}
examples/tickets-over-http/src/runner.rs (line 40)
34pub(crate) async fn run(path: PathBuf) -> Result<()> {
35    ensure_schema(&path)?;
36
37    // Built inside the runtime for the reason the API gives: ADR-0022 §9
38    // captures the tokio handle at construction.
39    let events = SqliteEventStore::open(&path)?;
40    let models = SqliteProjectionStore::open(&path)?;
41    let mut view = SeatHolders::new();
42    let chunk = Chunk::of(CHUNK.try_into()?);
43
44    println!("runner started against {}", path.display());
45
46    loop {
47        match run_projection(&events, &models, &mut view, &Json, chunk).await {
48            Ok(progress) => {
49                if progress.applied > 0 {
50                    println!(
51                        "applied {} event(s), through {:?}",
52                        progress.applied, progress.through
53                    );
54                }
55            }
56            // A failure here is reported and retried rather than fatal. The
57            // most likely one by far is `SQLITE_BUSY` surviving the busy
58            // timeout while the API holds the write lock, and a runner that
59            // exited on it would turn a moment of contention into an operator
60            // page. A *decode* failure would be permanent and would spin —
61            // which is why `rebuilding-read-models` exists to show what a
62            // policy for that looks like, and why this one says out loud that
63            // it does not have one.
64            Err(err) => eprintln!("projection pass failed: {err}"),
65        }
66
67        tokio::time::sleep(IDLE).await;
68    }
69}
examples/tickets-over-http/src/api.rs (line 63)
55pub(crate) async fn run(path: PathBuf) -> Result<()> {
56    ensure_schema(&path)?;
57
58    // Both stores are built **inside** the runtime, and that is load-bearing
59    // rather than stylistic: ADR-0022 §9 captures the tokio handle at
60    // construction, so a store built before a runtime exists records `None` and
61    // every read fails with `SqliteEventStoreError::NoRuntime`.
62    let events = SqliteEventStore::open(&path)?;
63    let models = SqliteProjectionStore::open(&path)?;
64
65    // Opening the show is idempotent by refusal: a second process starting
66    // against the same file is told the show is already open, and that is the
67    // correct answer rather than an error to report.
68    drop(open_show(&events, CAPACITY).await);
69
70    let listener = TcpListener::bind(SocketAddr::from(([127, 0, 0, 1], 0))).await?;
71    // The first line of stdout, and a contract with the demo role. Rust's
72    // stdout is line-buffered, so this reaches the pipe before `accept` blocks.
73    println!("listening on {}", listener.local_addr()?);
74
75    // The runner process derives the same id from the same view: the name and
76    // a digest of its query (PS-25). Reading under the bare name would answer
77    // `202` for ever.
78    let checkpoint = checkpoint_id(&SeatHolders::new())?;
79    let state = Arc::new(State {
80        events,
81        models,
82        checkpoint,
83        path,
84    });
85
86    loop {
87        let (stream, _) = listener.accept().await?;
88        let state = Arc::clone(&state);
89        tokio::spawn(async move {
90            if let Err(err) = serve(&state, stream).await {
91                eprintln!("connection failed: {err}");
92            }
93        });
94    }
95}
examples/two-devices-one-seat/src/scenario.rs (line 66)
59    pub(crate) fn open(dir: &Path, at: Place) -> Result<Self, StoryError> {
60        let file = dir.join(format!("{at}.db"));
61        let events = SqliteEventStore::open(&file).map_err(|source| StoryError::Open {
62            file: file.clone(),
63            source,
64        })?;
65        let models =
66            SqliteProjectionStore::open(&file).map_err(|source| StoryError::OpenModel {
67                file: file.clone(),
68                source,
69            })?;
70        let app = open_configured(&file)
71            .and_then(|app| app.execute_batch(DDL).map(|()| app))
72            .map_err(|source| StoryError::ReadModel {
73                file: file.clone(),
74                source,
75            })?;
76        Ok(Self {
77            events,
78            models,
79            app,
80            file,
81        })
82    }

pub fn open_in_memory() -> Result<Self, SqliteProjectionStoreError>

Opens a private in-memory store and applies the checkpoint schema.

A convenience for a single-handle caller, and not what a ProjectionFixture should reach for: a private in-memory database is per-connection, so a second connect would open a second, empty database rather than a second handle onto this one — and every rule that reads back through a fresh handle would fail.

What it is is a complete store: begin, commit, reset and rollback all work against it, on the same checkpoint schema, and the only thing it cannot do is be looked at from a second connection.

§Errors

Returns SqliteProjectionStoreError::Sqlite if SQLite refuses the connection or the schema cannot be applied, and SqliteProjectionStoreError::UnsupportedSchemaVersion on the version mismatch open documents — unreachable on a database this call just created, and checked on the same path rather than on a second one.

Trait Implementations§

§

impl Clone for SqliteProjectionStore

§

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 SqliteProjectionStore

§

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

Formats the value using the given formatter. Read more
§

impl ProjectionProbe for SqliteProjectionStore

The conformance suite’s write and read seam.

It lives here, in src/, and not in tests/projection.rs: that is a different crate, where neither ProjectionProbe nor SqliteProjectionStore is local and the orphan rule answers error[E0117]. The feature that turns it on forwards one flag on a dependency this crate already has.

§

const READS_THROUGH_BATCH: bool = false

false, and it is the honest answer rather than a gap.

A SqliteBatch is a list of statements that has been sent to SQLite exactly never, so there is no open transaction to read through — and answering from committed state is what PS-12 forbids by name, because a projection doing get then set inside one batch would then read the value from before the batch began and lose every increment after the first.

The alternative is rejected on the record: a shadow map inside the batch would answer these reads from a second source of truth SQLite never sees, and would buy a green batch_reads_reflect_pending_writes that says nothing about this adapter’s real read path. PS-12 permits false outright, and the two rules that would have used it are emitted as reported skips rather than omitted.

§

async fn probe_write( &self, batch: &mut Self::Batch, key: &str, value: u64, ) -> Result<(), Self::Error>

Queues one probe row. Never awaits and never fails, because queueing SQL into a buffer the caller owns cannot fail.

§

async fn probe_delete_all( &self, batch: &mut Self::Batch, ) -> Result<(), Self::Error>

Queues removal of every probe row, so that reset can be checked without the suite knowing what a read model is.

§

async fn probe_read(&self, key: &str) -> Result<Option<u64>, Self::Error>

Reads one probe row from committed state, through the same blocking seam as every other method here.

§

async fn probe_read_through( &self, _batch: &mut Self::Batch, _key: &str, ) -> Result<Option<u64>, Self::Error>

Never called, because READS_THROUGH_BATCH is false.

§Panics

Always. The specification permits exactly this for an adapter whose batch has no read path, and the panic is the honest answer: any value returned here would be a claim about pending writes SQLite has never been told about.

§

impl SendProjectionStore for SqliteProjectionStore

§

async fn checkpoint(&self, id: &ProjectionId) -> Result<Checkpoint, Self::Error>

How far id has been brought, and whether its rows are authoritative.

§Errors
  • the connection mutex was poisoned, or the blocking task did not complete, or there was no runtime to run it on;
  • the driver failed;
  • the stored row carried a position that is not a SequencePosition, or an authority discriminant this build does not know — both are reported rather than resolved to a default.
§

async fn commit( &self, batch: Self::Batch, id: &ProjectionId, position: SequencePosition, authority: Authority, ) -> Result<(), CommitError<Self::Error>>

Applies batch and moves id’s checkpoint to position, as one unit.

One BEGIN IMMEDIATE carries all of it: the recorded checkpoint is read under the same write lock that will overwrite it, then every queued statement runs in the order it was pushed, then the checkpoint is upserted with the authority this commit claims. Reading the checkpoint before the transaction opens is the defect that shape exists to avoid — two commits would interleave between the read and the write and both would pass.

§Errors
  • CommitError::ForeignBatch if batch was begun on a different store instance. Decided before any statement is prepared, so a rejected commit cannot have moved anything.
  • CommitError::CheckpointRegression if position is strictly below the recorded checkpoint. An equal position is accepted, which PS-22 permits.
  • CommitError::Store if the connection mutex was poisoned, the blocking task did not complete, there was no runtime to run it on, the driver failed, or the recorded row could not be read back.
§

async fn reset( &self, batch: Self::Batch, id: &ProjectionId, ) -> Result<(), ResetError<Self::Error>>

Applies batch and returns id to Checkpoint::NeverRun, as one unit.

commit’s dual, in one BEGIN IMMEDIATE: the caller’s own deletes, then the removal of this projection’s checkpoint row — removal rather than a sentinel position, because the absence of a row is NeverRun and a sentinel would make a reset indistinguishable from a commit at the first position.

It deletes nothing this adapter chose. The read model is the caller’s, and an adapter that truncated a table of its own naming would be scoped to something the port deliberately never told it.

A projection protected through protect_from_reset is refused. The mark is read first, inside the same BEGIN IMMEDIATE, so a refused reset has run none of the caller’s statements.

§Errors
  • ResetError::ForeignBatch if batch was begun on a different store instance, decided before any statement is prepared.
  • ResetError::Refused if id is protected from reset. The read model and the checkpoint are exactly as they were (PS-18), and is_protected_from_reset says which mark refused it.
  • ResetError::Store if the connection mutex was poisoned, the blocking task did not complete, there was no runtime to run it on, or the driver failed.
§

async fn rollback(&self, batch: Self::Batch) -> Result<(), Self::Error>

Discards the batch without committing.

Nothing was ever sent to SQLite, so this is a drop — which is also the evidence PS-7 asks for: for a buffering adapter, “dropping a batch must roll back” is free, and the store is usable afterwards because nothing was ever checked out to return.

§Errors

SqliteProjectionStoreError::ForeignBatch if batch was begun on a different store instance. The batch is consumed either way; the refusal is how a caller learns it was holding the wrong one, on the call that was meant to be the cleanup.

§

type Error = SqliteProjectionStoreError

How this adapter fails.
§

type Batch = SqliteBatch

The adapter’s write set. Read more
§

async fn begin(&self) -> Result<Self::Batch, Self::Error>

Opens a write set. 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<TraitVariantBlanketType> ProjectionStore for TraitVariantBlanketType
where TraitVariantBlanketType: SendProjectionStore,

Source§

type Error = <TraitVariantBlanketType as SendProjectionStore>::Error

How this adapter fails.
Source§

type Batch = <TraitVariantBlanketType as SendProjectionStore>::Batch

The adapter’s write set. Read more
Source§

async fn begin( &self, ) -> Result<<TraitVariantBlanketType as ProjectionStore>::Batch, <TraitVariantBlanketType as ProjectionStore>::Error>

Opens a write set. Read more
Source§

async fn checkpoint( &self, id: &ProjectionId, ) -> Result<Checkpoint, <TraitVariantBlanketType as ProjectionStore>::Error>

How far this projection has been brought, and whether its rows are authoritative. Read more
Source§

async fn commit( &self, batch: <TraitVariantBlanketType as ProjectionStore>::Batch, id: &ProjectionId, position: SequencePosition, authority: Authority, ) -> Result<(), CommitError<<TraitVariantBlanketType as ProjectionStore>::Error>>

Applies batch and moves id’s checkpoint to position, as one unit. Read more
Source§

async fn reset( &self, batch: <TraitVariantBlanketType as ProjectionStore>::Batch, id: &ProjectionId, ) -> Result<(), ResetError<<TraitVariantBlanketType as ProjectionStore>::Error>>

Applies batch and returns id to Checkpoint::NeverRun, as one unit. Read more
Source§

async fn rollback( &self, batch: <TraitVariantBlanketType as ProjectionStore>::Batch, ) -> Result<(), <TraitVariantBlanketType as ProjectionStore>::Error>

Discards the batch without committing. Read more
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.