Demo application
The repository contains a demo application: a library (authors, books, editions, tags, readers, loans) in a Django project, the adorm models generated from it, a FastAPI API, a Vue frontend and the launcher demo.py. It runs every example and scenario on every available driver, the Django driver and the native PostgreSQL driver, side by side:
- Examples: a query or a write, its adorm code, and per driver the SQL the driver sent, the result and the time;
- Concurrency: flows in concurrent tasks, each in a session of its own, with what every flow saw and when, the SQL of every flow and each flow's outcome.
A collapsible header under the title bar describes the demo; it is open on the first visit and closed on later ones unless it was left open. Code and SQL are syntax-highlighted; the theme follows the system's colour scheme until it is switched in the title bar. Both settings are stored in the browser.
Running it
The codespace starts the demo with a PostgreSQL server of its own and opens it in a new browser tab.
To run it locally:
It needs PostgreSQL and a dedicated database user with CREATEDB, not a superuser. ADORM_DEMO_DATABASE_URL names the user and the demo database; it is read from the environment or from .env in the repository root (ignored by git), the environment taking precedence.
CREATE ROLE adorm LOGIN CREATEDB PASSWORD '...';uv sync
npm install
cp .env.example .env # ADORM_DEMO_DATABASE_URL=postgres://adorm:password@127.0.0.1:5432/adorm_demo
uv run python demo.py # http://127.0.0.1:5173/| Option | Effect |
|---|---|
--frontend dev | start the Vite dev server (npm run demo:dev) on --frontend-port (default 5173); the default |
--frontend built | serve demo/frontend/dist from the API at /; builds it with npm run demo:build when it is missing |
--frontend none | the API only |
--host, --port | where the API listens (default 127.0.0.1:8000); its documentation is at /docs and /redoc |
--database NAME | use the database NAME on the server of ADORM_DEMO_DATABASE_URL |
--reset | replace the library data with the fixed data set |
--setup-only, --no-setup | set up the database and exit; skip the setup |
--drop | drop the demo database and exit |
--list-drivers | list the drivers and whether each is available, then exit |
Setup, before serving:
- refuses a superuser, and a demo database owned by another role;
- creates the database when the server lacks it; the user of the URL owns it;
- applies the Django migrations and fills an empty database with the data set (
manage.py seed_library); - checks that
demo/modelsis up to date (adorm generate --check) and that the tables match the models (adorm check-schema).
Layout
| Path | Contents |
|---|---|
demo.py | launcher: database setup, the dev server, uvicorn serving demo.api.main:app |
demo/database.py | the database URL, the role and owner checks, creating and dropping the database |
demo/backend/ | Django project: settings.py, manage.py and the app library |
demo/models/ | adorm models generated by adorm generate |
demo/api/examples.py | the examples: coroutine functions on the generated models |
demo/api/scenarios.py | the concurrency scenarios: the flows and the functions that steer them |
demo/api/capture.py | recording of the SQL each driver sends, attributed to sessions |
demo/api/drivers.py | the drivers and their connection profiles |
demo/api/main.py | the FastAPI app |
demo/frontend/ | Vite, Vue 3, Vuetify, @dynamicforms/vue-forms, @dynamicforms/vue-grid, @dynamicforms/vuetify-inputs and highlight.js (npm workspace adorm-demo-frontend) |
demo/e2e/ | Playwright tests of the frontend (npm workspace adorm-demo-e2e) |
tests/demo/ | the API on every available driver, through demo.py |
After a change to demo/backend/library/models.py:
uv run python -m demo.backend.manage makemigrations library
uv run adorm generate --settings demo.backend.settings -o demo/models --line-length 120Drivers and profiles
Each available driver has three connection profiles: <driver> with a pool of six slots, <driver>-small with two slots and acquire_timeout=1, and <driver>-desk, as small, whose on_acquire hook returns the custom option app.reader set to the session's name. An example runs in the session (<driver>, "example") (desk_options in (<driver>-desk, "example")), a flow of a scenario in (<driver>, <flow>). One run, of an example or a scenario, executes at a time.
The SQL is recorded on the connections: an execute wrapper on every Django connection (COMMIT and ROLLBACK from psycopg's transaction control included, and BEGIN when psycopg sends it, before the first statement of the transaction, at that statement's start), a query logger on every asyncpg connection, opened by the asyncpg profiles' connect hook. The profiles' on_acquire and on_release hooks record which session holds a connection; a statement belongs to the session that held its connection when it started. A statement outside a lease (the setup of a new connection) belongs to the session whose lease of the connection follows, and has no session when no lease follows. The monitor connections of wait_for_lock() are left out.
Examples
An example is a coroutine function on the generated models; the page shows its source:
async def lend(isbn: str, reader: str) -> dict:
async with adorm.atomic():
edition = await Edition.objects.select_for_update().get(isbn=isbn)
if edition.available == 0:
raise LookupError(f"no copy of {isbn} on the shelf")
borrower = await Reader.objects.get(email=reader)
loan = await Loan.objects.create(
edition_id=edition.id, reader_id=borrower.id, borrowed=TODAY, due=TODAY + datetime.timedelta(days=21)
)
await Edition.objects.filter(pk=edition.pk).update(available=F("available") - 1)
return {"loan": loan.id, "isbn": isbn, "available_before": edition.available}| Example | Shows |
|---|---|
search_books | Q with |, a condition across a many-to-many relation, distinct(), ordering, a slice |
edition_details | get() with select_related(), awaiting a relation, a many-to-many and a reverse relation as query sets |
authors_with_books | prefetch_related() |
stock | aggregate() |
busiest_authors | annotate() with Count(distinct=True) across relations |
loans_per_month | values() and annotate() grouping, TruncMonth, Count(filter=...) |
books_on_the_shelf | Exists() and Subquery() with OuterRef |
overdue_loans | select_related() over two foreign keys |
dashboard | three queries at once with asyncio.gather() |
lend | a transaction with select_for_update() and an F() update |
ensure_tag | get_or_create() |
enrol_readers | bulk_create() |
desk_options | a custom option from the profile's on_acquire hook (SET), overridden in a transaction by connection_options() (SET LOCAL) and reset outside one (RESET) |
The writing examples commit; after each driver's run the demo reverts the writes with the example's undo coroutine, outside the recording. A run cancelled after the example returned still reverts its writes and ends the recording before the cancellation propagates.
Concurrency scenarios
Every scenario runs on each driver in turn. A flow is a coroutine function that takes log (records what it saw) and its arguments; the scenario starts the flows in tasks and lets them on at fixed points, observing the database with wait_for_lock() and the pool's counters, so each run takes the same course. The data the scenarios change is restored after each run, also after a cancelled one.
| Scenario | Flows | Outcome |
|---|---|---|
race | A and B lend the last copy of an edition with select_for_update(); A keeps the lock until B waits for it | A lends the copy; B gets the row after A's commit, finds no copy and raises LookupError |
lock_timeout | A holds the row lock; B reads it with select_for_update() under connection_options(lock_timeout=0.5) | B raises OperationalError with SQLSTATE 55P03 after 0.5 s; A commits |
cancel | A holds the row lock; B waits for it; the demo cancels B's task | B's statement is cancelled in the database, cancellation_outcome() is unknown, B's slot returns to the pool; A commits |
deadlock | A locks War and Peace's edition, B Anna Karenina's, then each asks for the other's row | PostgreSQL aborts one transaction with SQLSTATE 40P01 after deadlock_timeout; the other commits |
slot_deadlock | on <driver>-small: A and B each hold a slot in a transaction, then each reads in a second session (A2, B2), which needs another slot | B raises DeadlockError at once, held_sessions names B; A gets B's slot and commits |
pool_exhaustion | on <driver>-small: A and B hold both slots in open transactions; C asks for a slot; after A commits, D asks for one | C raises SessionTimeout after 1 s; D gets a slot at once |
async def lock_with_timeout(log, isbn: str) -> str:
async with adorm.atomic():
with adorm.connection_options(lock_timeout=0.5):
log("select_for_update() with lock_timeout=0.5")
await Edition.objects.select_for_update().get(isbn=isbn)
log("has the row lock", "ok")
return "locked"API
| Method and path | Answer |
|---|---|
GET /api/health | status, adorm_version and drivers, the drivers runs execute on |
GET /api/drivers | every driver of the demo: name, description, available, reason when it is not, mode |
GET /api/examples | the examples: id, title, description, code, params (with minimum and maximum of an int), writes |
POST /api/examples/{id}/run | body {"params": {...}}; example, params (the arguments the example ran with) and runs; per run driver, ms, result, error and statements |
GET /api/scenarios | the scenarios: id, title, description, code of the flows, choreography |
POST /api/scenarios/{id}/run | scenario and runs; per run id, driver, ms, flows, outcomes, events (at_ms, flow, kind, text) and statements |
An unknown id answers 404, a parameter that is unknown or does not fit 422, and no available driver 503. A statement is session, sql, params, at_ms, duration_ms and error. A flow's outcome is {"status": "ok", "result"}, {"status": "error", "error", "sqlstate", "message", "held_sessions"} or {"status": "cancelled", "statement"}.
curl -X POST http://127.0.0.1:8000/api/examples/search_books/run \
-H 'Content-Type: application/json' -d '{"params": {"search": "karamazov"}}'{
"example": "search_books",
"params": {"search": "karamazov", "genre": ""},
"runs": [
{
"driver": "django",
"ms": 5.1,
"result": [{"id": 10, "title": "The Brothers Karamazov", "genre": "novel", "year": 1880}],
"error": null,
"statements": [
{"session": "example", "sql": "SELECT DISTINCT \"library_book\".\"id\" AS \"id\", …", "params": ["%karamazov%", "%karamazov%"],
"at_ms": 2.4, "duration_ms": 1.95, "error": null}
]
},
{"driver": "asyncpg", "…": "…"}
]
}Tests
tests/demo runs demo.py against the database adorm_test_demo on the server of ADORM_TEST_DATABASE_URL and drops it afterwards: the setup and its repetition, every example on every available driver with the same result, reverted writes, parameters and errors, each scenario three times per driver, a scenario whose steering raises while a flow holds a lock, and example and scenario runs cancelled after their writes, which restore the data. They skip when the user of ADORM_TEST_DATABASE_URL is a superuser. ADORM_DEMO_REQUIRED_DRIVERS (comma-separated names) fails the suite when a listed driver is not available. A test checks that the demo's drivers include every driver class of adorm.drivers.
The Playwright tests build the frontend and run demo.py --frontend built on the database adorm_demo_e2e, which they set up and drop:
npx playwright install chromium
npm run test:e2e