Struct SqliteProjectionStore
pub struct SqliteProjectionStore { /* private fields */ }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
impl SqliteProjectionStore
pub async fn protect_from_reset(
&self,
id: &ProjectionId,
) -> Result<(), SqliteProjectionStoreError>
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
SqliteProjectionStoreError::Sqliteif the write fails, includingSQLITE_BUSYonce the busy timeout has passed.SqliteProjectionStoreError::ConnectionPoisoned,WorkerorNoRuntime, as for every method that hops onto a blocking thread.
pub async fn allow_reset(
&self,
id: &ProjectionId,
) -> Result<(), SqliteProjectionStoreError>
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>
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
impl SqliteProjectionStore
pub fn new(connection: Connection) -> Self
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>
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::Sqliteif 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::UnsupportedSchemaVersionif 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?
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
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}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}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}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>
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
impl Clone for SqliteProjectionStore
§impl Debug for SqliteProjectionStore
impl Debug for SqliteProjectionStore
§impl ProjectionProbe for SqliteProjectionStore
The conformance suite’s write and read seam.
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
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>
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>
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>
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>
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
impl SendProjectionStore for SqliteProjectionStore
§async fn checkpoint(&self, id: &ProjectionId) -> Result<Checkpoint, Self::Error>
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>>
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::ForeignBatchifbatchwas begun on a different store instance. Decided before any statement is prepared, so a rejected commit cannot have moved anything.CommitError::CheckpointRegressionifpositionis strictly below the recorded checkpoint. An equal position is accepted, which PS-22 permits.CommitError::Storeif 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>>
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::ForeignBatchifbatchwas begun on a different store instance, decided before any statement is prepared.ResetError::Refusedifidis protected from reset. The read model and the checkpoint are exactly as they were (PS-18), andis_protected_from_resetsays which mark refused it.ResetError::Storeif 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>
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.