{"id":51596912,"url":"https://github.com/svyatov/database-transactions","last_synced_at":"2026-07-11T19:30:40.314Z","repository":{"id":370200264,"uuid":"1293718050","full_name":"svyatov/database-transactions","owner":"svyatov","description":"Learn database transactions from verified, runnable examples — every claim proven against a real PostgreSQL/MySQL database.","archived":false,"fork":false,"pushed_at":"2026-07-08T15:31:32.000Z","size":601,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-08T16:16:23.043Z","etag":null,"topics":["acid","bun","concurrency","database","deadlocks","isolation-levels","learning","locking","mvcc","mysql","postgresql","python","sql","transactions","tutorial","typescript"],"latest_commit_sha":null,"homepage":"https://svyatov.github.io/database-transactions/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/svyatov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-08T14:29:32.000Z","updated_at":"2026-07-08T15:32:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/svyatov/database-transactions","commit_stats":null,"previous_names":["svyatov/database-transactions"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/svyatov/database-transactions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svyatov%2Fdatabase-transactions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svyatov%2Fdatabase-transactions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svyatov%2Fdatabase-transactions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svyatov%2Fdatabase-transactions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/svyatov","download_url":"https://codeload.github.com/svyatov/database-transactions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svyatov%2Fdatabase-transactions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35374165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acid","bun","concurrency","database","deadlocks","isolation-levels","learning","locking","mvcc","mysql","postgresql","python","sql","transactions","tutorial","typescript"],"created_at":"2026-07-11T19:30:40.104Z","updated_at":"2026-07-11T19:30:40.303Z","avatar_url":"https://github.com/svyatov.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# database-transactions\n\n**Learn database transactions from verified, runnable examples.**\n\nAn interactive tutorial covering isolation levels, anomalies, locking, MVCC, and real-world\nconcurrency patterns, where **every single claim is proven by executable code** running against\na real database.\n\n📖 **Read online:** https://svyatov.github.io/database-transactions/\n\n## How it works\n\nLearning transactions usually means piecing things together from scattered articles with the\nofficial manual open in another tab. This project puts the whole picture in one place and\nholds it to one rule, nothing is claimed and everything is demonstrated:\n\n- Every session transcript you see in the docs is **generated from a real run** against\n  the database, never hand-written, so it can never drift from actual behavior.\n- Every lesson ships with a **scenario**: an executable definition that orchestrates\n  concurrent sessions and **asserts** the outcome (`bun test` runs them all).\n- CI regenerates every transcript on every push and fails if anything changed.\n  A green build literally means \"every statement on the site was just re-verified\".\n\n## Run it locally\n\n```sh\ngit clone https://github.com/svyatov/database-transactions.git\ncd database-transactions\nbun install\ndocker compose up -d --wait   # PostgreSQL 18.4 on :54321, MySQL 8.4 on :33061\nbun test                      # run every scenario, assert every claim\nbun lesson                    # list every lesson scenario…\nbun lesson mysql/03-locking/deadlock --step   # …and replay one live, statement by statement\nbun run gen                   # regenerate all transcripts from real runs\nbun run docs:dev              # browse the site locally\n```\n\nRequirements: [Bun](https://bun.com) and [Docker](https://www.docker.com/). That's it.\nThe database client is built into Bun.\n\n## Curriculum\n\n| Chapter | PostgreSQL | MySQL |\n|---|---|---|\n| 1. Transactions 101: ACID, BEGIN/COMMIT/ROLLBACK, savepoints | ✅ | ✅ |\n| 2. Isolation levels \u0026 anomalies: dirty reads, non-repeatable reads, phantoms, lost updates, write skew | ✅ | ✅ |\n| 3. Locking: row locks, lock queues, NOWAIT/SKIP LOCKED, deadlocks, monitoring | ✅ | ✅ |\n| 4. MVCC internals: snapshots, bloat, VACUUM / undo logs, history length | ✅ | ✅ |\n| 5. Real-world patterns: optimistic/pessimistic locking, retries, job queues, idempotency | ✅ | ✅ |\n| 6. Transactions across services: outbox, sagas, two-phase commit | ✅ | ✅ |\n| 7. Pitfalls compendium: symptom → broken pattern → fix | ✅ | ✅ |\n| 8. Production: spotting, debugging, and monitoring transaction bugs live | ✅ | ✅ |\n\nEvery scenario is also re-verified in CI through a **second, independent pair of drivers**\n(psycopg + PyMySQL, via a thin Python harness). Two drivers agreeing on every assertion is\nthe proof that a claim is database behavior, not a driver artifact. Where they genuinely\ndiffer (e.g. on server-side connection kills), the scenario says so explicitly.\n\n```sh\nuv sync --directory python \u0026\u0026 uv run --directory python pytest   # the same claims, second drivers\n```\n\n## Repository layout\n\n- `scenarios/\u003cdb\u003e/` — one **YAML file per demo**: named sessions (dedicated database\n  connections), an ordered list of SQL steps interleaving them, and the expected outcome\n  of each step, including \"this query MUST block now\", verified via live lock-wait\n  monitoring. A handful of scenarios whose *client code* is the lesson (retry loops,\n  LISTEN/NOTIFY) stay as TypeScript.\n- `harness/` — ~800 lines that make the above work: `loader.ts` interprets the YAML,\n  everything database-specific sits side by side in `harness/dialect.ts`. Deliberately\n  small and readable; it's part of the learning material.\n- `python/` — the cross-driver check: a second thin harness (psycopg + PyMySQL) that\n  pytest runs in CI against the *same* YAML scenarios. Transcripts come only from the\n  TypeScript harness; this one exists purely to re-verify the claims.\n- `docs/\u003cdb\u003e/` — the VitePress site, one track per database. Lesson pages show plain SQL:\n  the *generated transcripts* (color-coded per session), nothing is duplicated by hand.\n\n## Questions and feedback\n\nSomething in the docs unclear, hard to follow, or missing? Have a suggestion, an idea for a\nlesson, or just a question? [Open an issue](https://github.com/svyatov/database-transactions/issues).\nQuestions and \"this page didn't click for me\" are as welcome as bug reports. If an explanation\nlost you somewhere, telling us where is genuinely useful.\n\n## Contributing\n\nFound a wrong or unproven claim? That's a bug. See [CONTRIBUTING.md](CONTRIBUTING.md);\nthe golden rule is *no claim without a proving scenario*.\n\n## License\n\nMIT © Leonid Svyatov\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvyatov%2Fdatabase-transactions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsvyatov%2Fdatabase-transactions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvyatov%2Fdatabase-transactions/lists"}