https://github.com/svyatov/database-transactions
Learn database transactions from verified, runnable examples — every claim proven against a real PostgreSQL/MySQL database.
https://github.com/svyatov/database-transactions
acid bun concurrency database deadlocks isolation-levels learning locking mvcc mysql postgresql python sql transactions tutorial typescript
Last synced: about 15 hours ago
JSON representation
Learn database transactions from verified, runnable examples — every claim proven against a real PostgreSQL/MySQL database.
- Host: GitHub
- URL: https://github.com/svyatov/database-transactions
- Owner: svyatov
- License: mit
- Created: 2026-07-08T14:29:32.000Z (4 days ago)
- Default Branch: main
- Last Pushed: 2026-07-08T15:31:32.000Z (4 days ago)
- Last Synced: 2026-07-08T16:16:23.043Z (4 days ago)
- Topics: acid, bun, concurrency, database, deadlocks, isolation-levels, learning, locking, mvcc, mysql, postgresql, python, sql, transactions, tutorial, typescript
- Language: TypeScript
- Homepage: https://svyatov.github.io/database-transactions/
- Size: 587 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# database-transactions
**Learn database transactions from verified, runnable examples.**
An interactive tutorial covering isolation levels, anomalies, locking, MVCC, and real-world
concurrency patterns, where **every single claim is proven by executable code** running against
a real database.
📖 **Read online:** https://svyatov.github.io/database-transactions/
## How it works
Learning transactions usually means piecing things together from scattered articles with the
official manual open in another tab. This project puts the whole picture in one place and
holds it to one rule, nothing is claimed and everything is demonstrated:
- Every session transcript you see in the docs is **generated from a real run** against
the database, never hand-written, so it can never drift from actual behavior.
- Every lesson ships with a **scenario**: an executable definition that orchestrates
concurrent sessions and **asserts** the outcome (`bun test` runs them all).
- CI regenerates every transcript on every push and fails if anything changed.
A green build literally means "every statement on the site was just re-verified".
## Run it locally
```sh
git clone https://github.com/svyatov/database-transactions.git
cd database-transactions
bun install
docker compose up -d --wait # PostgreSQL 18.4 on :54321, MySQL 8.4 on :33061
bun test # run every scenario, assert every claim
bun lesson # list every lesson scenario…
bun lesson mysql/03-locking/deadlock --step # …and replay one live, statement by statement
bun run gen # regenerate all transcripts from real runs
bun run docs:dev # browse the site locally
```
Requirements: [Bun](https://bun.com) and [Docker](https://www.docker.com/). That's it.
The database client is built into Bun.
## Curriculum
| Chapter | PostgreSQL | MySQL |
|---|---|---|
| 1. Transactions 101: ACID, BEGIN/COMMIT/ROLLBACK, savepoints | ✅ | ✅ |
| 2. Isolation levels & anomalies: dirty reads, non-repeatable reads, phantoms, lost updates, write skew | ✅ | ✅ |
| 3. Locking: row locks, lock queues, NOWAIT/SKIP LOCKED, deadlocks, monitoring | ✅ | ✅ |
| 4. MVCC internals: snapshots, bloat, VACUUM / undo logs, history length | ✅ | ✅ |
| 5. Real-world patterns: optimistic/pessimistic locking, retries, job queues, idempotency | ✅ | ✅ |
| 6. Transactions across services: outbox, sagas, two-phase commit | ✅ | ✅ |
| 7. Pitfalls compendium: symptom → broken pattern → fix | ✅ | ✅ |
| 8. Production: spotting, debugging, and monitoring transaction bugs live | ✅ | ✅ |
Every scenario is also re-verified in CI through a **second, independent pair of drivers**
(psycopg + PyMySQL, via a thin Python harness). Two drivers agreeing on every assertion is
the proof that a claim is database behavior, not a driver artifact. Where they genuinely
differ (e.g. on server-side connection kills), the scenario says so explicitly.
```sh
uv sync --directory python && uv run --directory python pytest # the same claims, second drivers
```
## Repository layout
- `scenarios//` — one **YAML file per demo**: named sessions (dedicated database
connections), an ordered list of SQL steps interleaving them, and the expected outcome
of each step, including "this query MUST block now", verified via live lock-wait
monitoring. A handful of scenarios whose *client code* is the lesson (retry loops,
LISTEN/NOTIFY) stay as TypeScript.
- `harness/` — ~800 lines that make the above work: `loader.ts` interprets the YAML,
everything database-specific sits side by side in `harness/dialect.ts`. Deliberately
small and readable; it's part of the learning material.
- `python/` — the cross-driver check: a second thin harness (psycopg + PyMySQL) that
pytest runs in CI against the *same* YAML scenarios. Transcripts come only from the
TypeScript harness; this one exists purely to re-verify the claims.
- `docs//` — the VitePress site, one track per database. Lesson pages show plain SQL:
the *generated transcripts* (color-coded per session), nothing is duplicated by hand.
## Questions and feedback
Something in the docs unclear, hard to follow, or missing? Have a suggestion, an idea for a
lesson, or just a question? [Open an issue](https://github.com/svyatov/database-transactions/issues).
Questions and "this page didn't click for me" are as welcome as bug reports. If an explanation
lost you somewhere, telling us where is genuinely useful.
## Contributing
Found a wrong or unproven claim? That's a bug. See [CONTRIBUTING.md](CONTRIBUTING.md);
the golden rule is *no claim without a proving scenario*.
## License
MIT © Leonid Svyatov