Why use a cursor instead of OFFSET for event search?

Say it in 30 seconds

Say it like this (20-30 seconds)

MiniTickets orders events by starts_at and ID, then asks for rows after the last tuple. That is keyset pagination: deep pages do not repeatedly skip a growing OFFSET prefix, and the ID gives equal timestamps a stable order. The cursor preserves timestamp precision and a fixed upcoming cutoff. It is not a database snapshot, so concurrent edits can still change later pages; the product must accept that or require a stronger search-session contract.

The deeper answer

The search query fetches limit plus one rows, returns at most limit, and derives the next cursor from the last returned item. Its timestamp is formatted with microsecond precision because JavaScript Date would otherwise lose precision and could skip or repeat equal-time rows at a boundary.

The cursor includes asOf so moving wall-clock time does not change the upcoming filter between requests. A composite B-tree index supports the starts_at and ID order. Text search has its own trigram index; a cursor alone cannot make every filter fast.

Inserts, deletes and sort-key changes remain visible according to each query’s database view. A new row before the cursor may not appear in that traversal; a moved row can cross its boundary. For browsing events this can be acceptable. An audit export would need snapshot or version semantics and a clear retention policy instead.

Counter-questions

Why not order only by starts_at?

Several events can share a start time. The UUID tie-breaker makes the tuple order deterministic and gives the next page an unambiguous boundary.

What if filters change between pages?

Start a new traversal and discard the old cursor. A cursor is meaningful only with the same search semantics; the current shape is not a signed snapshot token binding every filter.

What do you measure before adding an index?

Use realistic filters and deep-page plans, row counts and latency. A matching index helps only when the planner and workload can use it; extra indexes also increase write and storage cost.

Where in MiniTickets

Read Search pagination, then inspect the rds-postgres piece →.

apps/api/src/queries/event-search.ts → search