# Add Cursor Pagination to a Quarkus Panache REST Endpoint

Yes. An agent adds keyset pagination to your Quarkus Panache list endpoints, with a limit, an opaque cursor and next_cursor in the response, tested, in a PR.

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

## What the agent does

The agent reads both resources before it changes either. In a service like `hibernate-orm-panache-quickstart` in quarkusio/quarkus-quickstarts, `pom.xml` imports the `io.quarkus.platform:quarkus-bom` at 3.40.1.2 with `maven.compiler.release` 17 and takes `quarkus-hibernate-orm-panache`, `quarkus-rest-jackson` and `quarkus-jdbc-postgresql`, with `quarkus-junit` and `rest-assured` for tests. The same model is served twice: `FruitEntityResource` at `entity/fruits` uses the active-record `FruitEntity extends PanacheEntity`, and `FruitRepositoryResource` at `repository/fruits` injects a `FruitRepository implements PanacheRepository<Fruit>` over a `Fruit` with `@Id @GeneratedValue Long id` and a `@Column(length = 40, unique = true) String name`. Both `GET` methods return `listAll(Sort.by("name"))`, every row in one response, and `import.sql` seeds Cherry, Apple and Banana with ids 1 to 3 and restarts both sequences at 4. `FruitsEndpointTest` runs `performTest` against each path: list the three, delete id 1, list again without Cherry.

Because the list is sorted by `name` and `name` is unique, the keyset is the name alone. The agent adds `limit` and `cursor` query parameters to both `GET` methods: `limit` defaults to 20 and is capped at 100, and `cursor` is the URL-safe Base64 of the last name on the previous page. The query becomes `find("name > ?1", Sort.by("name"), after).page(0, limit + 1).list()` on the entity and the same through the repository, fetching one row more than the page so the code knows whether another page exists without a second count query. The response changes from a bare array to `{"items": [...], "next_cursor": "..."}`, and `next_cursor` is left out on the last page rather than sent as null. A cursor that does not decode is a `WebApplicationException` with 400, which the existing `ErrorMapper` in each resource already turns into `{"exceptionType", "code", "error"}` JSON.

The one client in the repository is the AngularJS page at `src/main/resources/META-INF/resources/index.html`, whose controller assigns the list response to the scope and renders it. The agent updates that controller to read `data.items` and leaves the rest of the page alone, so the quickstart's own front end keeps working. The `@Cacheable` annotation on both entities stays, since Hibernate's second-level cache keys by id and a keyset query goes to the database either way. The two `ErrorMapper` classes are duplicates already; the agent does not touch them, and lists that duplication in the pull request as something it noticed and left.

Tests extend `FruitsEndpointTest.performTest` for both paths: `?limit=2` returns Apple and Banana with a `next_cursor`, following it returns Cherry with no `next_cursor`, `?limit=0` and `?limit=500` are clamped, and `?cursor=%%%` answers 400 with the JSON error shape. `FruitsEndpointIT` inherits them for the native profile unchanged. `./mvnw test` needs a database, which Quarkus Dev Services starts in a container; the sandbox has no Docker, so the agent installs `docker.io`, starts `dockerd`, and then runs the suite, and pastes the surefire summary into the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add cursor pagination to the list endpoints of this Quarkus Panache service. Read pom.xml, src/main/resources/application.properties, import.sql, index.html, every class under src/main/java and both test classes first. On both GET list methods add limit (default 20, maximum 100) and cursor query parameters; the cursor is the URL-safe Base64 of the last name on the previous page, the query is name > :after sorted by name fetching limit + 1 rows, and the response becomes {items, next_cursor} with next_cursor omitted on the last page. An undecodable cursor is a 400 through the existing ErrorMapper. Update the AngularJS controller in index.html to read items. Extend FruitsEndpointTest for both paths: a two-item first page with a cursor, the final page without one, clamped limits, and the 400. Dev Services needs Docker: install docker.io and start dockerd before ./mvnw test. Do not change the entities or the error mappers. Open a pull request with the test summary and an example of the two requests a client makes to walk the list.",
  "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 `FruitEntityResource.java`, `FruitRepositoryResource.java`, `index.html` and `FruitsEndpointTest.java`, adds a small `Cursor` helper for the Base64 encoding and decoding, and leaves the entities, `import.sql` and `application.properties` as they were. Its description pastes the surefire summary from `./mvnw test` and shows the two `curl` calls that walk the seeded table: the first with `?limit=2`, the second with the `cursor` the first returned.

Both endpoints now answer the same shape, so a client written against one works against the other, and a page never repeats or skips a row when a fruit is inserted between two requests, because the cursor names a position in the sort order rather than an offset into it.

Before merging, a reviewer decides whether 20 and 100 are the right defaults for the real table, confirms that the AngularJS change renders the page, and checks that any other client of these endpoints is updated for the `items` wrapper, since that is the one breaking change in the pull request.

## Run it on every list endpoint that returns every row

A team with several Quarkus services sends this body once per repository to `POST /o/{org}/sessions`, each with its own repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own entities: a table sorted by a non-unique column gets a cursor on that column and the id together, with a row comparison in the query, and a service on Panache's reactive variant gets the same page logic on `Uni` results.

Each run opens its own pull request on its own branch, and the person who started the batch reads every surefire summary from `GET /o/{org}/sessions`, newest first.

## Why run it on Rush?

The mistakes in keyset pagination are at the boundaries: a page that repeats its last row, a cursor that decodes to a name with a quote in it, a last page that still advertises a next one. They show only when a real database has more rows than one page and someone walks it to the end. The agent walks it in its sandbox, against the Postgres that Dev Services starts, and the assertions it writes stay in the suite.

The run keeps every command and its output, including the Docker setup and the full Maven log, so a reviewer sees the suite pass without starting a container on a laptop. Several services can be paginated at once, each in its own sandbox, each with its own pull request.

## Frequently asked questions

### Why a cursor on the name rather than the id?

The endpoints sort by `name`, and `name` is declared unique, so the name alone identifies a position in that order. A cursor on the id would need the sort to change to id order, which would change what every client sees. If the sort column were not unique the agent would use the column and the id together.

### Why does the response shape change?

A bare JSON array has nowhere to carry the next cursor. The agent wraps the list in `items` and adds `next_cursor` beside it, and omits `next_cursor` on the last page so a client checks for its presence rather than for null. The pull request names this as the one breaking change and updates the repository's own front end for it.

### Why fetch limit + 1 rows?

To learn whether another page exists without a `count` query, which on a large table costs more than the page itself. The extra row is dropped from `items` and its presence sets `next_cursor`.

### Does the second-level cache interfere?

No. `@Cacheable` on the entities caches rows by id, and a keyset query always runs against the database for the ordering and then populates entities from the cache where it can. The agent leaves the annotation in place and says so.

### How does it run the tests without a database?

Quarkus Dev Services starts a Postgres container for `@QuarkusTest` when no datasource URL is configured for the test profile, which is this project's setup. The sandbox has no Docker, so the agent installs `docker.io`, starts `dockerd` and then runs `./mvnw test`; the transcript shows both steps.

## More Quarkus jobs

- [Add Flyway Migrations to a Quarkus App](https://getrush.ai/run/add-flyway-migrations/quarkus/)
- [Add Graceful Shutdown to a Quarkus Service](https://getrush.ai/run/add-graceful-shutdown/quarkus/)
- [Add Health Checks to a Quarkus Service](https://getrush.ai/run/add-health-checks/quarkus/)

## The same job on other stacks

- [Add Cursor Pagination to a Rocket App](https://getrush.ai/run/add-cursor-pagination/rocket/)
- [Add Cursor Pagination to a Sequelize + Express API](https://getrush.ai/run/add-cursor-pagination/sequelize/)
- [Add Cursor Pagination to a Serverless DynamoDB API](https://getrush.ai/run/add-cursor-pagination/serverless/)

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