Struct SqliteBatch
pub struct SqliteBatch { /* private fields */ }projection-store only.Expand description
An in-flight write against a SqliteProjectionStore.
An owned, Send write set replayed inside a single transaction at
commit time — not a live
rusqlite::Transaction. See the module documentation for the two
compiler errors that rule the live handle out.
§Only begin mints one
There is no SqliteBatch::new and no Default, and their absence is the
stamp’s teeth rather than an omission: a batch a caller could build by hand
carries no store’s identity, so
CommitError::ForeignBatch
would have to be reported for it or waived for everything. Fill one through
push — queueing the application’s own read-model SQL is the
caller’s whole job — and hand it back to commit or reset.
§The statement is fixed and the values are bound
This is the one place in the workspace a consumer is handed a SQL-text seam,
and the values that flow through it are exactly the bytes the library
guarantees it does not inspect: ADR-0003 makes payloads opaque Bytes,
forwarded and validated by nothing. So push takes a
&'static str — a statement that exists in the source — and the values go
beside it as bound parameters. Assembling the text out of decoded event data
is a SQL injection whose source is the event log, and it commits inside the
same BEGIN IMMEDIATE that advances the checkpoint, so it is recorded as
progress: nothing replays those events and nothing re-derives the rows.
push_raw_sql is the escape hatch for a statement
whose shape is genuinely computed — an IN (…) list sized at run time is
the honest case — and it is separately named so that reaching for it is a
decision rather than a default.
Implementations§
§impl SqliteBatch
impl SqliteBatch
pub fn push(
&mut self,
sql: &'static str,
params: impl IntoIterator<Item = Value>,
)
pub fn push( &mut self, sql: &'static str, params: impl IntoIterator<Item = Value>, )
Queues a statement to run when the batch commits.
§Security
The statement 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 inside the same
BEGIN IMMEDIATE that advances the checkpoint — so the projection never
replays those events and nothing re-derives the rows it corrupted.
That has to be a type obligation rather than a paragraph, because
nothing in the gate reads prose
(standards/rust/70-rustdoc-obligations.md, RS-70-5). A statement
written in source, with its value bound, compiles:
use happenstance_sqlite::projection_store::SqliteBatch;
use happenstance_sqlite::rusqlite::types::Value;
fn queue(batch: &mut SqliteBatch, account: &str) {
batch.push(
"DELETE FROM balance WHERE account = ?1",
[Value::Text(account.to_owned())],
);
}and the same statement with the value interpolated does not:
use happenstance_sqlite::projection_store::SqliteBatch;
use happenstance_sqlite::rusqlite::types::Value;
fn queue(batch: &mut SqliteBatch, account: &str) {
batch.push(
format!("DELETE FROM balance WHERE account = '{account}'"),
core::iter::empty::<Value>(),
);
}&'static str is the narrowest type that admits every statement written
in source and refuses every statement assembled at run time — a literal,
a const, a concat!, all of them fine. The alternative considered was
a newtype minted from a literal by a macro, which buys the same
guarantee and costs the caller an import and a wrapper for it. Where the
shape genuinely is computed, reach for
push_raw_sql deliberately.
§Parameter count
One value per number up to the highest placeholder sql uses (?N; a
bare ? takes the next number), so ?1 OR ?1 takes one. Nothing counts
them here; at commit (and reset) the driver does, and refuses a
mismatch either way as CommitError::Store (or ResetError::Store)
carrying Sqlite with
InvalidParameterCount.
Neither the batch’s statements nor the checkpoint move (ADR-0084).
Examples found in repository?
557 async fn apply(
558 &mut self,
559 event: Delivered<Ledger>,
560 batch: &mut SqliteBatch,
561 ) -> Result<(), SqliteProjectionStoreError> {
562 let (account, delta) = match event.into_event() {
563 Ledger::AccountOpened { account } => (account, 0),
564 Ledger::Deposited { account, amount } => (account, i64::from(amount)),
565 Ledger::Withdrawn { account, amount } => (account, -i64::from(amount)),
566 };
567
568 batch.push(
569 "INSERT INTO account_balance (account, balance) VALUES (?1, ?2) \
570 ON CONFLICT(account) \
571 DO UPDATE SET balance = account_balance.balance + excluded.balance",
572 [Value::Text(account.into()), Value::Integer(delta)],
573 );
574
575 Ok(())
576 }More examples
1100 async fn apply(
1101 &mut self,
1102 event: Delivered<Fulfilment>,
1103 batch: &mut SqliteBatch,
1104 ) -> Result<(), SqliteProjectionStoreError> {
1105 let (sku, delta) = match event.into_event() {
1106 Fulfilment::StockReceived { sku, quantity }
1107 | Fulfilment::OrderCancelled { sku, quantity, .. } => (sku, i64::from(quantity)),
1108 Fulfilment::OrderPlaced { sku, quantity, .. } => (sku, -i64::from(quantity)),
1109 Fulfilment::OrderDispatched { sku, .. } => (sku, 0),
1110 };
1111
1112 batch.push(
1113 "INSERT INTO stock_on_hand (sku, on_hand) VALUES (?1, ?2) \
1114 ON CONFLICT(sku) \
1115 DO UPDATE SET on_hand = stock_on_hand.on_hand + excluded.on_hand",
1116 [Value::Text(sku.into()), Value::Integer(delta)],
1117 );
1118
1119 Ok(())
1120 }
1121}
1122
1123/// Where each order has got to.
1124///
1125/// Unlike the shelf, this view writes an *absolute* value: the status is the
1126/// last one seen, not an accumulation, so replaying it from any checkpoint
1127/// lands on the same answer.
1128#[derive(Debug)]
1129struct OrderStatus {
1130 /// Which read model this is, within the projection store.
1131 id: ProjectionId,
1132 /// Every event, so the tags constrain nothing.
1133 scope: Tags,
1134}
1135
1136/// The order view's projection id.
1137const ORDER_STATUS: ProjectionId = ProjectionId::from_static("order_status");
1138
1139impl OrderStatus {
1140 /// The view over every order.
1141 fn new() -> Self {
1142 Self {
1143 id: ORDER_STATUS,
1144 scope: Tags::empty(),
1145 }
1146 }
1147}
1148
1149impl Projection for OrderStatus {
1150 type Event = Fulfilment;
1151 type Store = SqliteProjectionStore;
1152 type Error = SqliteProjectionStoreError;
1153
1154 fn id(&self) -> &ProjectionId {
1155 &self.id
1156 }
1157
1158 fn scope(&self) -> &Tags {
1159 &self.scope
1160 }
1161
1162 async fn apply(
1163 &mut self,
1164 event: Delivered<Fulfilment>,
1165 batch: &mut SqliteBatch,
1166 ) -> Result<(), SqliteProjectionStoreError> {
1167 let (order, status, sku, quantity) = match event.into_event() {
1168 Fulfilment::OrderPlaced {
1169 order,
1170 sku,
1171 quantity,
1172 } => (order, "placed", sku, quantity),
1173 Fulfilment::OrderDispatched {
1174 order,
1175 sku,
1176 quantity,
1177 ..
1178 } => (order, "dispatched", sku, quantity),
1179 Fulfilment::OrderCancelled {
1180 order,
1181 sku,
1182 quantity,
1183 } => (order, "cancelled", sku, quantity),
1184 // Nominated and ignored. The derived query is the event set crossed
1185 // with the scope, and this view's scope is empty, so a stock
1186 // receipt arrives here whether it is wanted or not — the checkpoint
1187 // still advances past it, which is what "the position considered"
1188 // means.
1189 Fulfilment::StockReceived { .. } => return Ok(()),
1190 };
1191
1192 batch.push(
1193 "INSERT INTO order_status (order_ref, status, sku, quantity) \
1194 VALUES (?1, ?2, ?3, ?4) \
1195 ON CONFLICT(order_ref) DO UPDATE SET status = excluded.status",
1196 [
1197 Value::Text(order.into()),
1198 Value::Text(status.to_owned()),
1199 Value::Text(sku.into()),
1200 Value::Integer(i64::from(quantity)),
1201 ],
1202 );
1203
1204 Ok(())
1205 }
1206}
1207
1208/// The upsert into the first table, and into the second.
1209///
1210/// Two constants rather than one `format!` over a table name, and the reason is
1211/// [`SqliteBatch::push`], which takes `&'static str`. Interpolating a
1212/// table name here was *safe* — it was a `&'static str` chosen by one of the
1213/// three constructors below and could never hold user input — but that safety
1214/// lived in a comment, and a comment is what the signature stopped accepting.
1215/// The two statements differ in one identifier, which is exactly the amount of
1216/// duplication that buys the property.
1217///
1218/// [`push_raw_sql`](SqliteBatch::push_raw_sql) is the escape hatch for
1219/// a statement whose *shape* is decided at run time — an `IN (…)` list sized by
1220/// how many keys are being written. This one's shape is not: only which of two
1221/// fixed statements runs is decided at run time, and that is a choice between
1222/// constants rather than a statement built from a value.
1223const UPSERT_DAILY_DISPATCHES: &str = "INSERT INTO daily_dispatches (day, dispatched) VALUES (?1, ?2) \
1224 ON CONFLICT(day) \
1225 DO UPDATE SET dispatched = daily_dispatches.dispatched + excluded.dispatched";
1226
1227/// The same statement against the backfill's own table. See
1228/// [`UPSERT_DAILY_DISPATCHES`] for why this is a second constant.
1229const UPSERT_DAILY_DISPATCHES_V2: &str = "INSERT INTO daily_dispatches_v2 (day, dispatched) VALUES (?1, ?2) \
1230 ON CONFLICT(day) \
1231 DO UPDATE SET dispatched = daily_dispatches_v2.dispatched + excluded.dispatched";
1232
1233/// The blue/green swap, run as the retiring view's reset batch.
1234///
1235/// No `DELETE` first: the drop takes blue's rows with it. A delete naming
1236/// `daily_dispatches` would be a hazard rather than a redundancy anywhere after
1237/// the rename, because the name by then belongs to green.
1238const PROMOTION: [&str; 2] = [
1239 "DROP TABLE daily_dispatches",
1240 "ALTER TABLE daily_dispatches_v2 RENAME TO daily_dispatches",
1241];
1242
1243/// The same swap with the new table's name mistyped, so it fails *after* the
1244/// drop has run — the one point at which a promotion split across two
1245/// transactions would already have committed blue's retirement.
1246const MISTYPED_PROMOTION: [&str; 2] = [
1247 "DROP TABLE daily_dispatches",
1248 "ALTER TABLE daily_dispatch_v2 RENAME TO daily_dispatches",
1249];
1250
1251/// How much went out each day, counted one of two ways.
1252///
1253/// One type with two configurations rather than two types, because the blue
1254/// and green halves of a rebuild differ in exactly the way a real one does:
1255/// the fold changed its mind about what it was counting, and everything else
1256/// stayed put.
1257#[derive(Debug)]
1258struct DailyDispatches {
1259 /// Which read model this is. **It does not change when the table is
1260 /// promoted** — the checkpoint is keyed by this name and the derived
1261 /// query, and renaming it to match the promoted table would discard the
1262 /// resume point.
1263 id: ProjectionId,
1264 /// Every event, so the tags constrain nothing.
1265 scope: Tags,
1266 /// The upsert this instance issues, and with it the table it writes into.
1267 upsert: &'static str,
1268 /// What one dispatch adds to its day.
1269 counting: Counting,
1270}
1271
1272/// What one dispatch adds to its day's total.
1273#[derive(Debug, Clone, Copy)]
1274enum Counting {
1275 /// One per order that went out.
1276 Orders,
1277 /// One per unit that went out.
1278 Units,
1279}
1280
1281/// The first attempt's projection id.
1282const DAILY_DISPATCHES: ProjectionId = ProjectionId::from_static("daily_dispatches");
1283
1284/// The replacement's projection id, kept across the promotion: the checkpoint
1285/// travels with the id, not with the table.
1286const DAILY_DISPATCHES_V2: ProjectionId = ProjectionId::from_static("daily_dispatches_v2");
1287
1288impl DailyDispatches {
1289 /// The first attempt: one per order.
1290 fn counting_orders() -> Self {
1291 Self {
1292 id: DAILY_DISPATCHES,
1293 scope: Tags::empty(),
1294 upsert: UPSERT_DAILY_DISPATCHES,
1295 counting: Counting::Orders,
1296 }
1297 }
1298
1299 /// The replacement, backfilled beside the first into its own table.
1300 fn counting_units() -> Self {
1301 Self {
1302 id: DAILY_DISPATCHES_V2,
1303 scope: Tags::empty(),
1304 upsert: UPSERT_DAILY_DISPATCHES_V2,
1305 counting: Counting::Units,
1306 }
1307 }
1308
1309 /// The replacement after the swap: the same id, the promoted table.
1310 fn promoted() -> Self {
1311 Self {
1312 id: DAILY_DISPATCHES_V2,
1313 scope: Tags::empty(),
1314 upsert: UPSERT_DAILY_DISPATCHES,
1315 counting: Counting::Units,
1316 }
1317 }
1318}
1319
1320impl Projection for DailyDispatches {
1321 type Event = Fulfilment;
1322 type Store = SqliteProjectionStore;
1323 type Error = SqliteProjectionStoreError;
1324
1325 fn id(&self) -> &ProjectionId {
1326 &self.id
1327 }
1328
1329 fn scope(&self) -> &Tags {
1330 &self.scope
1331 }
1332
1333 async fn apply(
1334 &mut self,
1335 event: Delivered<Fulfilment>,
1336 batch: &mut SqliteBatch,
1337 ) -> Result<(), SqliteProjectionStoreError> {
1338 let (day, delta) = match event.into_event() {
1339 Fulfilment::OrderDispatched { day, quantity, .. } => match self.counting {
1340 Counting::Orders => (day, 1),
1341 Counting::Units => (day, i64::from(quantity)),
1342 },
1343 // Nominated and ignored, for the reason `order_status` gives.
1344 Fulfilment::StockReceived { .. }
1345 | Fulfilment::OrderPlaced { .. }
1346 | Fulfilment::OrderCancelled { .. } => return Ok(()),
1347 };
1348
1349 // Which of the two constants runs is the whole of what this instance's
1350 // configuration decides. SQLite binds values and not identifiers, so a
1351 // table name can only ever reach a statement by being part of its text —
1352 // which is why the statement, and not the name, is the thing chosen.
1353 batch.push(self.upsert, [Value::Text(day), Value::Integer(delta)]);
1354
1355 Ok(())
1356 }
1357}
1358
1359/// The view that was written against a field the log does not carry.
1360///
1361/// It compiles, its query is well formed, and it nominates exactly the events
1362/// it means to. The disagreement is in the payload, and the payload is the one
1363/// thing no signature describes.
1364#[derive(Debug)]
1365struct Couriered {
1366 /// Which read model this is, within the projection store.
1367 id: ProjectionId,
1368 /// Every dispatch, so the tags constrain nothing.
1369 scope: Tags,
1370}
1371
1372/// The courier view's projection id.
1373const COURIERED: ProjectionId = ProjectionId::from_static("couriered");
1374
1375impl Couriered {
1376 /// The view over every dispatch.
1377 fn new() -> Self {
1378 Self {
1379 id: COURIERED,
1380 scope: Tags::empty(),
1381 }
1382 }
1383}
1384
1385impl Projection for Couriered {
1386 type Event = Handover;
1387 type Store = SqliteProjectionStore;
1388 type Error = SqliteProjectionStoreError;
1389
1390 fn id(&self) -> &ProjectionId {
1391 &self.id
1392 }
1393
1394 fn scope(&self) -> &Tags {
1395 &self.scope
1396 }
1397
1398 async fn apply(
1399 &mut self,
1400 event: Delivered<Handover>,
1401 batch: &mut SqliteBatch,
1402 ) -> Result<(), SqliteProjectionStoreError> {
1403 let Handover::OrderDispatched { order, courier } = event.into_event();
1404
1405 batch.push(
1406 "INSERT INTO couriered (order_ref, courier) VALUES (?1, ?2) \
1407 ON CONFLICT(order_ref) DO UPDATE SET courier = excluded.courier",
1408 [Value::Text(order.into()), Value::Text(courier)],
1409 );
1410
1411 Ok(())
1412 }
1413}
1414
1415// ---------------------------------------------------------------------------
1416// Driving views, and reporting on them
1417// ---------------------------------------------------------------------------
1418
1419/// Brings one view up to date and reports how much it applied.
1420///
1421/// Generic over the projection rather than written four times, and generic is
1422/// as far as it can go: `Projection` has an associated event type and an
1423/// associated store, so there is no `dyn Projection` to put in a registry and
1424/// no loop to write. A heterogeneous set of views is a sequence of calls, and
1425/// that is a property of the port, not a shortcoming of this file.
1426///
1427/// `P::Error: Send + Sync` because `anyhow` asks it of every error `?` moves
1428/// in, and a projection's own error carries no such bound by design: a
1429/// `!Send` application is allowed one.
1430async fn drive<P>(
1431 events: &SqliteEventStore,
1432 models: &SqliteProjectionStore,
1433 projection: &mut P,
1434 chunk: usize,
1435) -> Result<usize>
1436where
1437 P: Projection<Store = SqliteProjectionStore>,
1438 P::Error: Send + Sync,
1439{
1440 let chunk = Chunk::of(chunk.try_into()?);
1441 let progress = run_projection(events, models, projection, &Json, chunk).await?;
1442 Ok(progress.applied)
1443}
1444
1445/// Runs the broken view, which is expected to fail, and says where it stopped.
1446///
1447/// Returns the position and the decoder's own message. A run that *succeeded*
1448/// would be the interesting failure — it would mean the log had grown a
1449/// `courier` field nobody in this file wrote — so it is refused out loud
1450/// rather than reported as a pass.
1451async fn poison(
1452 events: &SqliteEventStore,
1453 models: &SqliteProjectionStore,
1454 projection: &mut Couriered,
1455) -> Result<(u64, String)> {
1456 let chunk = Chunk::of(CHUNK.try_into()?);
1457 match run_projection(events, models, projection, &Json, chunk).await {
1458 Ok(progress) => bail!(
1459 "the couriered view decoded {} event(s) it could not have",
1460 progress.applied
1461 ),
1462 Err(ProjectionError::Decode {
1463 position, source, ..
1464 }) => Ok((position.get(), error_chain(&source))),
1465 // `ProjectionError` is `#[non_exhaustive]`. A read failure or a commit
1466 // failure here would be a different defect wearing this one's clothes.
1467 Err(other) => bail!("expected a decode failure, got: {other}"),
1468 }
1469}
1470
1471/// Renders an error and everything under it, joined by `: `.
1472///
1473/// `CodecError`'s own `Display` says the payload could not be decoded, which
1474/// is a category. The value a reader needs — *which field was missing* — is
1475/// one link down the source chain, and a message that stops at the top of that
1476/// chain is the same defect `rejected` exists to avoid one layer up.
1477fn error_chain(error: &dyn core::error::Error) -> String {
1478 let mut rendered = error.to_string();
1479 let mut source = error.source();
1480
1481 while let Some(cause) = source {
1482 rendered.push_str(": ");
1483 rendered.push_str(&cause.to_string());
1484 source = cause.source();
1485 }
1486
1487 rendered
1488}
1489
1490/// Clears a view's rows and its checkpoint as one unit of work.
1491///
1492/// The statements are the *application's*, because the read model is: the port
1493/// takes a batch and commits it alongside the checkpoint reset, and it has no
1494/// idea which tables this program invented. Used for the two things reset is
1495/// actually for — retiring a view, and preparing a rebuild — and a retirement
1496/// may carry a blue/green swap, which is what puts the swap in the same
1497/// transaction as the checkpoint it retires.
1498///
1499/// A slice of statements rather than one string of several: the batch runs one
1500/// statement per `push`, and rusqlite refuses a push that holds two with
1501/// `MultipleStatement` — at commit, after the batch has left this function.
1502///
1503/// It takes the projection rather than an id, so the reset names the id the
1504/// runner commits under, `checkpoint_id`. A reset of `projection.id()`, the
1505/// bare name, clears a row the runner never wrote and leaves its checkpoint
1506/// standing.
1507async fn retire<P: Projection>(
1508 models: &SqliteProjectionStore,
1509 projection: &P,
1510 statements: &[&'static str],
1511) -> Result<()> {
1512 let key = checkpoint_id(projection)?;
1513 let mut batch = models.begin().await?;
1514 for statement in statements {
1515 batch.push(statement, []);
1516 }
1517 models.reset(batch, &key).await?;
1518 Ok(())
1519}619 async fn apply(
620 &mut self,
621 event: Delivered<Ticketing>,
622 batch: &mut SqliteBatch,
623 ) -> Result<(), SqliteProjectionStoreError> {
624 match event.into_event() {
625 Ticketing::SeatReserved { seat, patron, .. } => batch.push(
626 "INSERT INTO seat_holder (seat, patron) VALUES (?1, ?2) \
627 ON CONFLICT(seat) DO UPDATE SET patron = excluded.patron",
628 [Value::Text(seat.into()), Value::Text(patron.into())],
629 ),
630 Ticketing::SeatReleased { seat, .. } => batch.push(
631 "DELETE FROM seat_holder WHERE seat = ?1",
632 [Value::Text(seat.into())],
633 ),
634 // Nominated and ignored. The derived query is the event set crossed
635 // with the scope, and this view's scope is empty, so an opening
636 // arrives here whether it is wanted or not — the checkpoint still
637 // advances past it, which is what "the position considered" means.
638 Ticketing::ShowOpened { .. } => {}
639 }
640
641 Ok(())
642 }92 async fn apply(
93 &mut self,
94 event: Delivered<BoxOffice>,
95 batch: &mut SqliteBatch,
96 ) -> Result<(), SqliteProjectionStoreError> {
97 match event.into_event() {
98 BoxOffice::ShowScheduled { show, capacity } => batch.push(
99 "INSERT INTO show_seats (show, capacity) VALUES (?1, ?2) \
100 ON CONFLICT (show) DO NOTHING",
101 [Value::Text(show.into()), Value::Integer(capacity.into())],
102 ),
103 BoxOffice::SeatSold {
104 show,
105 sale,
106 buyer,
107 sold_by,
108 } => batch.push(
109 "INSERT INTO seat_ledger (show, sale, buyer, sold_by, status) \
110 VALUES (?1, ?2, ?3, ?4, 'held') \
111 ON CONFLICT (show, sale) DO UPDATE \
112 SET buyer = excluded.buyer, sold_by = excluded.sold_by",
113 [
114 Value::Text(show.into()),
115 Value::Text(sale.into_string()),
116 Value::Text(buyer),
117 Value::Text(sold_by.as_str().to_owned()),
118 ],
119 ),
120 BoxOffice::SaleRefunded { show, sale, reason } => batch.push(
121 "INSERT INTO seat_ledger (show, sale, status, reason) \
122 VALUES (?1, ?2, 'refunded', ?3) \
123 ON CONFLICT (show, sale) DO UPDATE \
124 SET status = 'refunded', reason = excluded.reason",
125 [
126 Value::Text(show.into()),
127 Value::Text(sale.into_string()),
128 Value::Text(reason.to_string()),
129 ],
130 ),
131 }
132 Ok(())
133 }pub fn push_raw_sql(
&mut self,
sql: impl Into<String>,
params: impl IntoIterator<Item = Value>,
)
pub fn push_raw_sql( &mut self, sql: impl Into<String>, params: impl IntoIterator<Item = Value>, )
Queues a statement this crate cannot see the provenance of.
The unconstrained twin of push, for the one case its
&'static str cannot express: a statement whose shape depends on a
run-time value, of which the honest example is an IN (…) list sized by
how many keys are being written. Build the placeholders, bind the values.
§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 sql. This crate’s own
statements show the pattern through push
(probe_write and probe_delete_all below) — the text is fixed, every
value is a [Value] beside it.
The wrong implementation this refuses to hide is the one a reviewer
waves through because it reads like the parameterised form:
push_raw_sql(format!("… WHERE account = '{account}'"), []), with
account decoded out of an event payload. It runs in the same
transaction that advances the checkpoint, so a successful injection is
recorded as progress and no later run re-derives the corrupted rows.
§Parameter count
As for push. A computed IN (…) list is where a count
goes wrong: build the placeholders and the values from the same
collection.
pub fn statements(&self) -> &[PendingStatement]
pub fn statements(&self) -> &[PendingStatement]
The queued statements, in the order they will run.