# Add Cursor Pagination to an aiohttp App

Yes. An agent replaces an aiohttp view's unbounded select with a keyset query, an opaque cursor and a next link, tests the pages against Postgres, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-cursor-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 an app like the `polls` demo in aio-libs/aiohttp-demos, `aiohttpdemo_polls/views.py` has `index`, which 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`, where a Jinja loop renders one link per question through `url('poll', question_id=question.id)`. `db.py` declares `Question` with an integer primary key, `question_text` as `String(200)` and `pub_date` as a date, on SQLAlchemy 2.0.54 with asyncpg 0.32.0 per `requirements-dev.txt`. `routes.py` registers `/` without a name, so there is no reverse route for the index yet.

The cursor is a keyset over `(pub_date, id)`, ordered newest first, because `pub_date` alone is not unique and an offset would skip or repeat rows when a poll is added between pages. The agent adds `after` and `limit` query parameters to `index`: `limit` defaults to 20 and is capped at 100, and `after` is a urlsafe base64 string of the last row's `pub_date` and `id`, decoded in a helper that raises `web.HTTPBadRequest` on anything it cannot parse, matching the error the `vote` view already raises for a bad choice. The query becomes `select(Question).where(tuple_(Question.pub_date, Question.id) < (date, id)).order_by(Question.pub_date.desc(), Question.id.desc()).limit(limit + 1)`, and the extra row, when present, becomes `next_cursor`. The template gets an `Older polls` link built with `url('index')`, so the agent names the route in `routes.py`.

Tests follow the existing suite. `tests/conftest.py` builds the app from `init_app` with `config/polls_test.yaml` and the `tables_and_data` fixture loads `init_db.sample_data`, which inserts one question, so the new `tests/test_pagination.py` inserts a few dozen more through the app's session maker inside the test, with dates that tie on purpose. It asserts that the first page holds `limit` rows, that following the link until it disappears visits every id exactly once, that a cursor from the middle of a tie returns the right neighbour, and that `?after=garbage` answers 400. `pytest.ini` runs with `asyncio_mode = auto` and turns every warning into an error, so the test uses no deprecated session API.

The check is the repository's own: `make test` in the demo runs `pytest tests` against the Postgres the `db` fixture creates, and the root `Makefile` runs `pytest demos/polls` with the other demos, which is what `.github/workflows/ci.yml` executes with a Postgres service. The agent runs `flake8` from `requirements-dev.txt` too, since the root `make lint` covers the demos.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add cursor pagination to the polls index in this aiohttp app. Read aiohttpdemo_polls/views.py, routes.py, db.py, templates/index.html, tests/conftest.py, tests/test_integration.py, init_db.py, pytest.ini and requirements-dev.txt first. Replace the unbounded select in the index view with a keyset query over (pub_date, id), newest first, taking after and limit query parameters: limit defaults to 20 and is capped at 100; after is a urlsafe base64 cursor of the last row's pub_date and id, and a cursor that does not parse answers 400 with web.HTTPBadRequest. Fetch limit + 1 rows and expose next_cursor to the template as an Older polls link; name the index route so url('index') works. Add tests/test_pagination.py that inserts questions with tied dates through the app's session maker, walks every page and asserts each id appears once, checks a cursor inside a tie, and checks the 400. Run make test and flake8, and open a pull request with the 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`, `routes.py` and `templates/index.html`, adds a small cursor module beside them and `tests/test_pagination.py`. Its description pastes the `pytest` run with the `--durations=10` table that `pytest.ini` turns on and the `flake8` result, and shows a decoded example cursor so a reviewer can see it carries a date and an integer and nothing else.

The index now answers in constant time whatever the table size, and a poll inserted while a reader is on page three does not shift what page four shows. A client that stores the cursor can resume later; a client that sends a stale cursor for a deleted row still gets the rows after it, because the comparison is on values, not on the row's existence.

Before merging, a reviewer decides the default and maximum page sizes, checks whether the `(pub_date, id)` index Postgres needs for the keyset should land as a migration in the same pull request or a separate one, and confirms the `Older polls` link text matches the site's tone.

## Run it on every list view with no limit

A team with several aiohttp services starts one run per repository from the terminal: one `POST /o/{org}/sessions` each, with that repository in `resources` and a `request_id` that is a UUID v5 of its full name, so a retried call returns the run already started. Each run reads its own views: a service whose list is already ordered by a unique column gets a single-column cursor, one that returns JSON gets `next_cursor` in the body instead of a template link, and one on aiopg instead of SQLAlchemy gets the same keyset written as SQL.

Each run opens its own pull request on its own branch, and `GET /o/{org}/sessions` lists them newest first, so the person who started the batch reads every test result from one place.

## Why run it on Rush?

Pagination that looks right on ten rows breaks on ten thousand, and the breakage is a missing row nobody notices. The agent proves the keyset with data it inserts itself, including the ties that make `(pub_date, id)` necessary, against a real Postgres in its own sandbox, and the walk-every-page test stays in the suite to catch a later change to the ordering.

The run keeps every command and its output, so the reviewer sees the test run and the lint pass without creating the database locally. Several services can be paginated at once, each in its own sandbox, and one whose view already bounds its query is left with a note instead of a second cursor.

## Frequently asked questions

### Why not offset and limit?

An offset counts rows from the start every time, so page cost grows with the page number, and a row inserted or deleted before the offset shifts every later page. A keyset compares against the last row's values, so each page is one indexed range scan and a concurrent insert changes nothing a reader has already seen.

### Is the cursor safe to expose?

It is base64 of a date and an integer, readable by anyone, and it is treated as untrusted input: it is parsed strictly, a bad one answers 400, and the values only ever reach the query as bound parameters through SQLAlchemy. If the agent finds the team wants cursors to be opaque, it notes that signing them is a separate change.

### Does the template still work with few polls?

Yes. With fewer than `limit + 1` rows there is no `next_cursor` and the link is not rendered, so a site with three polls looks exactly as it does today. The empty state, `No polls are available.`, is unchanged.

### Does it need a database migration?

The query works without one; Postgres can scan the table. For the keyset to be fast at scale, a composite index on `(pub_date, id)` helps, and the agent proposes it in the pull request description rather than adding Alembic to a project that does not use it.

## More aiohttp jobs

- [Add Alembic Migrations to an aiohttp App](https://getrush.ai/run/add-database-migrations/aiohttp/)
- [Add a Dockerfile to an aiohttp App](https://getrush.ai/run/add-dockerfile/aiohttp/)
- [Add Health Checks to an aiohttp App](https://getrush.ai/run/add-health-checks/aiohttp/)

## The same job on other stacks

- [Add Cursor Pagination to an Axum API](https://getrush.ai/run/add-cursor-pagination/axum/)
- [Add Cursor Pagination to a chi API from a Linear Issue](https://getrush.ai/run/add-cursor-pagination/chi/)
- [Add Cursor Pagination to a Cloudflare Worker on D1](https://getrush.ai/run/add-cursor-pagination/cloudflare-workers/)

## 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/)
