# Fix N+1 KV Reads in a Hono API

Yes. An agent finds the Hono list handler that does one Workers KV get per key after a list, rewrites it to read in one pass, proves it with Vitest, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/fix-n-plus-one-queries/hono/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the API to find where the extra reads come from. In a Worker like the `blog` example in honojs/examples, `src/index.ts` builds a `Hono` app, mounts a middleware router at `/api` that applies `prettyJSON()` and `basicAuth` with `USERNAME` and `PASSWORD` from `Bindings` on every non-GET under `/posts/*`, and mounts `src/api.ts` at the same prefix. `api.ts` registers `GET` and `POST /posts`, `GET`, `PUT` and `DELETE /posts/:id`, with `cors()` on `/posts/*`, and delegates to `src/model.ts`. There, posts live in the `BLOG_EXAMPLE` KV namespace under keys prefixed `v1:post:`, `createPost` writes `{id, title, body}` as JSON with `crypto.randomUUID()` for the id, and `getPosts` is the problem: it calls `KV.list({ prefix })`, then loops over `list.keys` and calls `KV.get(keys[i].name)` for each one, awaiting each in turn. For N posts that is one list plus N serial gets, so the list endpoint's latency grows with the number of posts, one round trip at a time. `src/api.test.ts` runs under `@cloudflare/vitest-pool-workers` with `isolatedStorage: false` and walks the five routes in order, asserting `posts.length` is 0 before a create and 1 after. `package.json` pins `hono` at `^4.2.4`, `wrangler` at `^3.53.0` and `vitest` 1.3.0.

The fix has two parts, and the agent does the safe one first. In `getPosts` it replaces the serial loop with a single `Promise.all` over `keys.map((k) => KV.get(k.name))`, so the N gets go out together and the handler waits once; that keeps the response shape and is enough for a small blog. It also handles `list_complete` and `cursor` from the `list` result, which the current code ignores, so a namespace with more keys than one `list` page returns no longer silently drops the rest.

The second part removes the gets altogether for the list endpoint. `KV.put` accepts a `metadata` object that `KV.list` returns beside each key without a `get`, so `createPost` and `updatePost` write `{ title }` as metadata alongside the JSON value, and a new `listPostSummaries` builds `{id, title}` rows from `list.keys[i].metadata` alone, in one call per page. `GET /posts` switches to that summary shape and `GET /posts/:id` keeps returning the full post with `body`, which is what a client needs to render a list and a page. Because older keys were written without metadata, `listPostSummaries` falls back to a `get` only for keys whose `metadata` is missing, and the pull request notes that a one-off re-put of existing posts removes the fallback path.

The agent updates `api.test.ts` so the list assertions check `id` and `title` and adds cases for a key written without metadata and for a two-page list, which it builds by putting more keys than the `limit` it passes to `list` in the test. It runs `vitest --run` in the Worker pool, then `wrangler dev` with a local KV namespace to call the endpoints with `curl` and compare the response for the old and new `getPosts`, and pastes both the test output and a short before-and-after of the request log into the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Fix the N+1 KV reads in the list endpoint of this Hono API and open a pull request. Read package.json, wrangler.example.toml, vitest.config.ts, src/index.ts, src/api.ts, src/bindings.ts, src/model.ts and src/api.test.ts first. In model.ts, getPosts lists keys with a prefix and then awaits one KV.get per key in a loop. First replace the loop with Promise.all over the keys and handle list_complete and cursor so every page is read. Then store { title } as metadata on every put in createPost and updatePost, add listPostSummaries that builds { id, title } rows from list metadata without a get, falling back to get only for keys with no metadata, and switch GET /posts to return those summaries while GET /posts/:id keeps returning the full post. Update api.test.ts for the new list shape and add cases for a key with no metadata and for a list that spans two pages. Run vitest --run, then wrangler dev with a local KV namespace and call the endpoints with curl. Paste the test output and a before-and-after of the list request in the pull request. Do not change the auth middleware or the other routes.",
  "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

What comes back is a pull request that edits `src/model.ts`, `src/api.ts` and `src/api.test.ts` and touches neither `src/index.ts` nor the auth middleware. The description explains the two steps, parallel gets and metadata-backed summaries, shows the new `GET /posts` response shape beside the old one, pastes the `vitest` output with the new cases named, and includes the `curl` calls against `wrangler dev` so a reviewer can see the shape change rather than infer it.

A repository with a CI job that runs `npm test` in the workspace runs the Worker-pool tests on the pull request. The run's record keeps the `wrangler dev` session and every request made against it.

A reviewer checks that no client depends on `body` in the list response before the shape changes, that the metadata stays under KV's per-key metadata limit for the fields chosen, and that the fallback `get` for keys without metadata is temporary. If the shape change is not acceptable, the first step alone, `Promise.all` plus paging, still ships and the second can wait.

## Run it on every Hono service that lists from KV

A team with several Workers sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own `model.ts`, so a service that already stores metadata gets only the paging fix and a service that lists from two prefixes gets both handled, and each run opens its own pull request. Send a `request_id` per request so a retried call returns the run it already started.

Give the key a `webhook_url` and every run it starts posts `run.completed` when its turn ends, with `data.session_url` to read the pull request link and the test output from.

## Why run it on Rush?

A serial-read bug is quiet in a test with one post and loud in production with a thousand, and the honest check is to run the Worker locally, write enough keys to cross a list page, and watch the request. In a Rush sandbox the agent runs `vitest` in the Workers pool, starts `wrangler dev` with a local namespace, writes the keys, calls the endpoint before and after, and keeps every command and response in the run's record.

The result is a branch with the fix in two separable steps and a pull request that shows the response shape change in the open, so the reviewer can take the conservative half if the API contract must hold. The same request works on any Hono or plain Workers service whose list handler follows a `list` with a `get` per key.

## Frequently asked questions

### Does Promise.all alone fix it?

It fixes the latency, since the gets go out together instead of one after another, and the paging fix stops dropped keys. It does not reduce the number of KV reads, which still grows with the number of posts and is billed per read. The metadata step is what brings the list endpoint down to one read per page.

### Why change the response shape of GET /posts?

KV metadata is small by design, so it can carry a title but not a post body. Returning `{id, title}` from the list and the full post from `GET /posts/:id` is the shape most clients want, and the pull request shows it explicitly. A team that must keep `body` in the list keeps the first step and skips the second.

### What about posts written before metadata existed?

The summary function falls back to a `get` for any key whose `list` entry has no metadata, so nothing disappears from the list. The pull request suggests a one-off script that re-puts each existing post with its metadata, after which the fallback never runs.

### Will the existing tests still pass?

The create, read, update and delete cases pass unchanged. The two list cases change because the list rows no longer carry `body`; the agent updates those assertions and adds the two new cases, and the `vitest` output in the pull request shows all of them.

## More Hono jobs

- [Turn Sentry Errors Into Fix Pull Requests for a Hono App](https://getrush.ai/run/fix-sentry-errors/hono/)
- [Migrate a Hono Worker from KV to D1](https://getrush.ai/run/migrate-kv-to-d1/hono/)
- [Review Pull Requests on a Hono API](https://getrush.ai/run/review-pull-requests/hono/)

## The same job on other stacks

- [Fix N+1 Queries in a Laravel App](https://getrush.ai/run/fix-n-plus-one-queries/laravel/)
- [Fix N+1 Queries in a Phoenix App](https://getrush.ai/run/fix-n-plus-one-queries/phoenix/)
- [Fix N+1 Queries in a Rails App](https://getrush.ai/run/fix-n-plus-one-queries/rails/)

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