Cursor Pagination: An Opaque Bookmark, Not a Position

Strip the encoding away and a cursor is usually a keyset: the ordering-key values of the last row served. "Resume after (created_at = 2026-07-01T09:14:07Z, id = ord_8231)" compiles to a WHERE clause the database answers with an index seek — land on the boundary, read the next 50 rows, done. Page 2,001 costs what page 1 costs, because the query never mentions a position, only values. This is the entire performance story: cursors are fast because they replace "skip 100,000 rows" with "seek to a key", the operation B-tree indexes exist to make O(log n).

The mechanism imposes one hard requirement the contract must honor: a total, deterministic ordering. If two rows share a created_at and the sort ends there, "after row X" is ambiguous — ties can be returned in either order, and a page boundary that lands inside a tie duplicates or skips rows. Every cursor ordering therefore ends with a unique tiebreaker (, id), and the composite index must match the full ordering, including direction. The contract clause "sorted by created_at" carries a physical bill: one composite index per supported ordering (see Sorting: Determinism or Drift and Filtering: An Allowlist With an Index Bill for how the combinatorics escalate).

Stability under writes follows from the same design: the cursor names *values*, not positions, so inserts and deletes elsewhere in the collection cannot shift it. New rows sort before or after the frontier and are seen or not seen accordingly — the traversal never repeats and never gaps along the ordering key. The one caveat worth documenting: this is frontier stability, not a snapshot. Rows already behind the cursor can be updated or deleted after you read them; consumers needing point-in-time consistency need export semantics, not a list endpoint (see Consistency as a Contract Clause).

The token must be opaque: documented as a value the client stores and returns, never inspects, never constructs. This is not secrecy for its own sake — it is the seam that keeps your internals evolvable. The moment a client base64-decodes your cursor and discovers {"created_at": "...", "id": "..."}, someone will construct their own tokens, and your ordering keys, encoding and even column names have become public API. Now switching the tiebreaker, adding a shard hint, or fixing a timezone bug in the cursor breaks "consumers" you never knew you had — Hyrum's Law with a decoder ring (see What an API Contract Actually Is).

Practical opacity is cheap: encode the keyset, then sign or HMAC it so tampered and hand-built tokens are rejected as invalid_cursor rather than executed. Signing also closes the quiet security hole in naive cursors: a client that can forge keyset values can walk orderings and ranges your filters never offered, and a cursor that embeds a raw SQL fragment (it has been shipped) is an injection surface. The token should carry data — key values, ordering id, maybe filter hash — never anything executable, and the server should validate that the cursor's embedded ordering and filters match the request's (a cursor from ?status=paid replayed against ?status=refunded must fail loudly, not return plausible garbage).

Finally, the contract must answer the lifecycle questions clients will otherwise answer by assumption. Lifetime: keyset cursors are naturally durable (values do not expire), but if yours embed snapshot state or server-side context, say how long they live. Staleness: what happens when the anchor row was deleted? (Keyset answers gracefully — the seek lands after where it would have been.) Invalidity: a malformed, expired or mismatched cursor returns a documented 400 invalid_cursor, and the client's recovery — restart from the beginning — should be written in the docs, because a sync engine needs to know that restarting is the *designed* behavior, not a bug workaround.

Cursors give up random access, and the contract should be honest about the consequences rather than hand-waving them. No jumping to page 40; no "page 7 of 132" (there are no page numbers, and totals are a separate, separately-priced question); no trivially parallelizable traversal — page N+1's request needs page N's response. For most products these are non-features. When one of them is real, solve it deliberately: parallel export via partitioned cursors (the server hands out N range-disjoint cursors, one per worker), positional UIs via bounded Offset Pagination: Simple, Jumpable, and Lying Under Writes on that one admin surface, totals via a dedicated count endpoint with stated staleness.

Bidirectional traversal is the other buildable-but-not-free feature. A feed that lets users scroll up needs a prev_cursor alongside next_cursor, which means the server reverses the ordering and the comparison for backward seeks and un-reverses the page before returning it — mechanical, but a real second code path that deserves tests, because backward-pagination bugs (reversed pages, off-by-one at the frontier) are embarrassingly common. Ship prev_cursor when a consumer needs it, not speculatively; every emitted cursor field is contract you maintain forever.