Skip to content

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 ​

Open in GitHub Codespaces

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.

sql
CREATE ROLE adorm LOGIN CREATEDB PASSWORD '...';
bash
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/
OptionEffect
--frontend devstart the Vite dev server (npm run demo:dev) on --frontend-port (default 5173); the default
--frontend builtserve demo/frontend/dist from the API at /; builds it with npm run demo:build when it is missing
--frontend nonethe API only
--host, --portwhere the API listens (default 127.0.0.1:8000); its documentation is at /docs and /redoc
--database NAMEuse the database NAME on the server of ADORM_DEMO_DATABASE_URL
--resetreplace the library data with the fixed data set
--setup-only, --no-setupset up the database and exit; skip the setup
--dropdrop the demo database and exit
--list-driverslist the drivers and whether each is available, then exit

Setup, before serving:

  1. refuses a superuser, and a demo database owned by another role;
  2. creates the database when the server lacks it; the user of the URL owns it;
  3. applies the Django migrations and fills an empty database with the data set (manage.py seed_library);
  4. checks that demo/models is up to date (adorm generate --check) and that the tables match the models (adorm check-schema).

Layout ​

PathContents
demo.pylauncher: database setup, the dev server, uvicorn serving demo.api.main:app
demo/database.pythe 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.pythe examples: coroutine functions on the generated models
demo/api/scenarios.pythe concurrency scenarios: the flows and the functions that steer them
demo/api/capture.pyrecording of the SQL each driver sends, attributed to sessions
demo/api/drivers.pythe drivers and their connection profiles
demo/api/main.pythe 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:

bash
uv run python -m demo.backend.manage makemigrations library
uv run adorm generate --settings demo.backend.settings -o demo/models --line-length 120

Drivers 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:

python
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}
ExampleShows
search_booksQ with |, a condition across a many-to-many relation, distinct(), ordering, a slice
edition_detailsget() with select_related(), awaiting a relation, a many-to-many and a reverse relation as query sets
authors_with_booksprefetch_related()
stockaggregate()
busiest_authorsannotate() with Count(distinct=True) across relations
loans_per_monthvalues() and annotate() grouping, TruncMonth, Count(filter=...)
books_on_the_shelfExists() and Subquery() with OuterRef
overdue_loansselect_related() over two foreign keys
dashboardthree queries at once with asyncio.gather()
lenda transaction with select_for_update() and an F() update
ensure_tagget_or_create()
enrol_readersbulk_create()
desk_optionsa 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.

ScenarioFlowsOutcome
raceA and B lend the last copy of an edition with select_for_update(); A keeps the lock until B waits for itA lends the copy; B gets the row after A's commit, finds no copy and raises LookupError
lock_timeoutA 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
cancelA holds the row lock; B waits for it; the demo cancels B's taskB's statement is cancelled in the database, cancellation_outcome() is unknown, B's slot returns to the pool; A commits
deadlockA locks War and Peace's edition, B Anna Karenina's, then each asks for the other's rowPostgreSQL aborts one transaction with SQLSTATE 40P01 after deadlock_timeout; the other commits
slot_deadlockon <driver>-small: A and B each hold a slot in a transaction, then each reads in a second session (A2, B2), which needs another slotB raises DeadlockError at once, held_sessions names B; A gets B's slot and commits
pool_exhaustionon <driver>-small: A and B hold both slots in open transactions; C asks for a slot; after A commits, D asks for oneC raises SessionTimeout after 1 s; D gets a slot at once
python
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 pathAnswer
GET /api/healthstatus, adorm_version and drivers, the drivers runs execute on
GET /api/driversevery driver of the demo: name, description, available, reason when it is not, mode
GET /api/examplesthe examples: id, title, description, code, params (with minimum and maximum of an int), writes
POST /api/examples/{id}/runbody {"params": {...}}; example, params (the arguments the example ran with) and runs; per run driver, ms, result, error and statements
GET /api/scenariosthe scenarios: id, title, description, code of the flows, choreography
POST /api/scenarios/{id}/runscenario 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"}.

bash
curl -X POST http://127.0.0.1:8000/api/examples/search_books/run \
     -H 'Content-Type: application/json' -d '{"params": {"search": "karamazov"}}'
json
{
  "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:

bash
npx playwright install chromium
npm run test:e2e

Released under the MIT License.