case studies

Case Study: A Checkout That Is Never Half Done, Tested With 1200 Power Cuts

A checkout touches several things that must change together. The cart goes away, an order appears with its lines, and the stock goes down. If the power fails halfway, the worst outcomes are an order with the stock never taken, or a paid order with the cart still sitting there. With a key-value store for carts and an SQL database for orders, those are two systems and two commits, and somebody has to write the cleanup for the gap between them.

In KvSQL the cart can stay a plain key-value entry while orders and stock live in SQL tables, and the checkout is still one transaction. This case study runs that checkout and then cuts the power at every point of its commit. It’s part of case_studies.rs in the repository, with output in case-studies.md from the recorded run of October 22, 2026.

A checkout that is never half done. The commit is five steps: write 1, write 2, sync, meta write and sync, with a power cut placed before each step and after the last. Each cut was replayed 200 ways. Results: 794 files held the shop as before, with the cart kept and stock untouched; 406 held the shop as after, with the order placed and the cart gone; 0 were half done. 1,200 reopened files, every one passed verify.

Every cut point in the commit, and what the reopened files held.

The Checkout

The shop has tables for stock, prices, orders and order lines, two indexes, 3,000 older orders and 3,000 other carts. Customer 17’s cart, a plain key-value entry, holds a kettle, four mugs and a teapot. The checkout is one write transaction:

let mut tx = db.begin_write()?;
let cart = tx.get("carts", b"customer-17")?;                      // key door
tx.execute("INSERT INTO orders VALUES (5001, 'customer-17', 0)", &[])?;
// for each item in the cart:
tx.execute("UPDATE stock SET qty = qty - ? WHERE sku = ? AND qty >= ?", &[..])?;
let price = tx.get_row("prices", &Value::Text(sku))?;              // key door
tx.execute("INSERT INTO order_lines VALUES (?, 5001, ?, ?)", &[..])?;
// then:
tx.execute("UPDATE orders SET total = ? WHERE id = 5001", &[..])?;
tx.delete("carts", b"customer-17")?;                               // key door
tx.commit()?;

Run with no failure, it takes the stock from 12, 40, 5 and 9 down to 11, 36, 4 and 9. It writes order 5001 with a total of 9,700 cents and three order lines, and the cart is gone.

Cutting the Power at Every Step

The program runs on the same simulated disk as the project’s power-cut tests. On that disk the checkout’s commit is five steps: two writes of new pages, a sync, the write of the meta page that makes the commit visible, and a final sync. The program cuts the power before each step and after the last, which is six cut points. Each cut is replayed 200 ways, because a real disk can keep unsynced writes, drop them, reorder them or tear them at 512-byte sectors.

That’s 1,200 files. Each was reopened, passed verify, and was compared with the shop’s full state. 794 held the shop exactly as before the checkout, with the cart there and the stock untouched. 406 held it exactly as after. None held anything in between: no order without its stock taken, no cart left beside its order.

What It Shows

One transaction can mix the key door and the SQL door freely, and the commit protects all of it the same way. The application doesn’t need a cleanup job for half-finished checkouts, because there can’t be one. The testing post covers the 20,000-cut test that this case study borrows its disk from.