# Add Pagination to an aiohttp App

Yes. An agent pages a list view in your aiohttp app with a page query parameter, a bounded SQLAlchemy query, previous and next links and tests, then opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pagination/aiohttp/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts from the view that lists everything. In the polls demo under `demos/polls` of aio-libs/aiohttp-demos, `aiohttpdemo_polls/views.py` has an `index` view that opens a session from `request.app[db_key]`, runs `select(db.Question)` with no order and no limit, and hands `questions.all()` to `templates/index.html`, which loops over the list and prints one link per question. `db.py` defines `Question` with `id`, `question_text` and `pub_date` on SQLAlchemy's `DeclarativeBase`, and `pg_context` builds an `async_sessionmaker` over an asyncpg engine from the `postgres` block of `config/polls.yaml`. `routes.py` registers `/` without a name, while `poll`, `results` and `vote` are named, so the index template has nothing to build a link to itself from. `requirements-dev.txt` pins `aiohttp==3.13.5`, `aiohttp-jinja2==1.6`, `asyncpg==0.32.0` and `SQLalchemy==2.0.54`, and `pytest.ini` sets `asyncio_mode = auto` and `filterwarnings = error`, so any deprecation warning the change provokes fails the suite.

The query changes first. The agent adds a `page_size` key to `utils.py`'s `TRAFARET` and to both `config/polls.yaml` and `config/polls_test.yaml`, because `settings.get_config` validates the file against that schema and refuses unknown or missing keys. `index` reads `page` from `request.query`, turns a missing value into the first page, and raises `web.HTTPBadRequest` for anything that is not a positive integer; `middlewares.py` has no override for 400, so the plain text answer goes out as is. The select gains `order_by(db.Question.pub_date.desc(), db.Question.id.desc())`, since offset paging over an unordered table can repeat or skip rows between pages, plus `offset` and `limit` from the page number. A second statement, `select(func.count()).select_from(db.Question)`, gives the total, from which the view computes the last page; a page past it raises `web.HTTPNotFound`, which the existing error middleware renders with `404.html`.

The template gets what it needs to navigate. The agent names the index route (`app.router.add_get("/", index, name="index")`) so `aiohttp_jinja2`'s `url()` helper can build `url('index')`, and `index.html` appends `?page=` for a previous link when the page is above one and a next link when it is below the last, with a `page x of y` line between them. The `No polls are available.` branch stays for an empty table. Nothing else in the demo reads the question list, so `detail.html` and `results.html` are untouched.

Tests follow `tests/test_integration.py`, which needs a running Postgres: `conftest.py` creates the database with `init_db.setup_db` and the `tables_and_data` fixture inserts one question and three choices through `init_db.sample_data`. The agent adds a fixture that inserts more questions than one page holds, using the same `async_sessionmaker` pattern, and tests that the first page lists exactly `page_size` of them in date order, that the second page lists the rest with a previous link and no next link, that `?page=0` and `?page=abc` answer 400, and that a page past the end answers 404 with the demo's 404 template. It runs `make flake` in `demos/polls` and `pytest demos/polls` as the root `Makefile` does, against a Postgres it starts in its sandbox the way the root `.github/workflows/ci.yml` `test` job does with its `postgres` service.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add pagination to the question list of this aiohttp app. Read aiohttpdemo_polls/views.py, routes.py, db.py, settings.py, utils.py, templates/index.html, config/polls.yaml, config/polls_test.yaml, init_db.py, tests/conftest.py, tests/test_integration.py, requirements-dev.txt and pytest.ini first. Add a page_size key to the config schema and both YAML files. In the index view read page from the query string, reject non-positive or non-integer values with 400, order the select by pub_date and id descending, apply offset and limit, count the total with a second select, and answer 404 past the last page. Name the index route and add previous and next links to index.html with url('index'). Write pytest tests for the first page, the last page, a bad page value and a page past the end, inserting enough questions through the existing async session pattern. Run flake8 and pytest against a local Postgres, then open a pull request that quotes the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `aiohttpdemo_polls/views.py` (the ordered, bounded query and the two error cases), `routes.py` (the named index route), `utils.py` (the `page_size` key in the trafaret), `config/polls.yaml`, `config/polls_test.yaml`, `templates/index.html` and `tests/test_integration.py`, and adds the fixture that fills more than one page. Its description quotes the `pytest` output and the lines `make flake` printed, and shows the first and second page as `curl` output from the sandbox so a reviewer can see the links without starting Postgres.

A reviewer checks three things: that the order key is stable (two questions published on the same day are separated by `id`), that the count query and the page query run in the same session so a question inserted between them cannot push the last page off by one in a way the template does not handle, and that `page_size` has a sensible value in `polls.yaml` for the real app rather than the small one the tests use.

The vote flow, the per-question pages and the static route are untouched. A request to `/` with no query string renders the same first page as before, now with a next link when there is more.

## Run it on every new list view

A list view that works on a demo table turns into a slow page once the table grows, so the useful moment is when a new one lands. An automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` runs read-only with a prompt that looks for a `select(...)` in a view that neither limits nor orders its result, and comments on the pull request naming the view and the template. The event the trigger adds after the prompt names the pull request; nothing is filled into the prompt itself.

When the comment is right, a handler on your own server sends this body to `POST /o/{org}/sessions` with the view's name added to the end of the prompt and the pull request's branch in `resources` as `https://github.com/your-org/your-app/tree/<branch>`, with a `request_id` that is a UUID v5 of the pull request's head SHA so a repeated delivery returns the run it already started. The key that starts it gets `run.completed` at its `webhook_url` with the new pull request's URL.

## Why run it on Rush?

The tests here need a Postgres with a database the suite creates and drops, which is why `conftest.py` calls `setup_db` and `teardown_db` with an admin connection. On a laptop that means a container or a local server and a matching `polls_test.yaml`; in the sandbox the agent starts one, runs the suite against it, and the exact commands and their output stay in the run's record beside the pull request.

The same change is due in every list view that was written against a small table, in this app and in the next one. One run per repository reads that app's own session and template conventions and opens one pull request each, so a team with several aiohttp services gets the same ordering and error behaviour in all of them without one person doing the rounds.

## Frequently asked questions

### Why offset paging rather than a cursor?

The list is small, server-rendered and navigated with previous and next links, which is what offset paging is for. A keyset cursor on `(pub_date, id)` is the right change if the table grows large or the list becomes an API; the ordered query the agent writes is the same one a cursor would need, so the move later is small.

### Why does it change the config schema?

The demo validates its YAML with a trafaret in `utils.py` and `get_config` refuses keys the schema does not list. Putting `page_size` there means the test config can use a small page while the real one uses a larger value, and a missing key fails at startup rather than at the first request.

### What happens past the last page?

The view raises `web.HTTPNotFound`, and the error middleware in `middlewares.py` already renders `404.html` for that status. A bad value such as `?page=0` is a `400` with a plain text body, since nothing in the app renders that status.

### Will the tests run in GitHub Actions?

Yes. The repository's `ci.yml` already starts a `postgres` service with the password `init_db.py` expects and runs the polls suite through the root `Makefile`, so the new tests run there with no workflow change.

### Does it touch the vote or results pages?

No. Only the index view, its route name and its template change. The per-question views keep using `db.get_question`, and `vote` still redirects to the named `results` route.

## More aiohttp jobs

- [Add Prometheus Metrics to an aiohttp App](https://getrush.ai/run/add-prometheus-metrics/aiohttp/)
- [Add Rate Limiting to an aiohttp App](https://getrush.ai/run/add-rate-limiting/aiohttp/)
- [Add Request ID Logging to an aiohttp App](https://getrush.ai/run/add-request-id-logging/aiohttp/)

## The same job on other stacks

- [Add Pagination to an Eleventy Blog Archive](https://getrush.ai/run/add-pagination/eleventy/)
- [Add Cursor Pagination to a FastAPI Endpoint from a Linear Issue](https://getrush.ai/run/add-pagination/fastapi/)
- [Add Pagination to a Gatsby Blog Index](https://getrush.ai/run/add-pagination/gatsby/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
