Гайды

Как сделать пагинацию — постранично, без дублей и тормозов на глубоких страницах

Иллюстрация: стопка карточек выдаётся порциями по закладке

Сначала список из тридцати записей грузится мгновенно. Потом их тысяча — страница думает секунду. Потом сто тысяч — и приложение просто умирает на главной.

Лечится это пагинацией: отдавать не всё сразу, а порциями. Звучит скучно, но внутри спрятаны две ловушки, на которых спотыкаются почти все.

Первая: OFFSET 10000 не «перепрыгивает» десять тысяч строк — база их честно читает и выбрасывает. Чем дальше страница, тем медленнее запрос. Документация Supabase про пагинацию в pg_graphql формулирует это прямо: чем больше значение offset, тем хуже производительность, поэтому по возможности используйте пагинацию по курсору.

Вторая ловушка ещё коварнее — про неё в конце, она про дубли.

Шаг 1. Реши, нужна ли она вообще

Если записей заведомо мало — настройки, категории, десяток проектов — не усложняй. Отдай всё одним запросом и живи спокойно.

Но заметь: у API поверх базы часто есть свой потолок. У Supabase, например, ответ по умолчанию обрезается на 1000 строках — и это тихое обрезание, а не ошибка. Список, который «почему-то заканчивается», очень часто именно про этот лимит.

Шаг 2. Сделай обычную пагинацию по номеру страницы

Самый простой рабочий вариант. На SQL:

select id, title, created_at
from posts
order by created_at desc, id desc
limit 20 offset 40;

То же через клиент Supabase (.range() — это тот же offset/limit, границы включительно):

const PAGE = 20
const from = page * PAGE
const { data, error } = await supabase
  .from('posts')
  .select('id, title, created_at')
  .order('created_at', { ascending: false })
  .range(from, from + PAGE - 1)

Одна деталь тут важнее всего остального: order обязателен. Без явной сортировки база не обещает стабильный порядок строк — и одна и та же запись может оказаться и на первой странице, и на третьей. Это не мистика, это разрешённое поведение.

Шаг 3. Покажи, сколько всего страниц

Для «страница 3 из 40» нужен общий счётчик. Просить его вместе с данными:

const { data, count } = await supabase
  .from('posts')
  .select('id, title', { count: 'exact' })
  .order('created_at', { ascending: false })
  .range(0, 19)

А если нужен только счётчик, без строк — { count: 'exact', head: true }.

Имей в виду: точный счёт на большой таблице сам по себе стоит времени — базе приходится пересчитывать строки. Для бесконечной ленты он обычно не нужен вовсе: там достаточно знать, есть ли следующая порция.

Шаг 4. Перейди на курсор, когда список растёт

Курсорная (keyset) пагинация не считает, сколько строк пропустить. Она говорит: «дай двадцать записей после вот этой».

// первый запрос: курсора ещё нет
let query = supabase
  .from('posts')
  .select('id, title, created_at')
  .order('created_at', { ascending: false })
  .limit(20)

// следующие: отталкиваемся от последней записи предыдущей порции
if (cursor) query = query.lt('created_at', cursor)

const { data } = await query
const nextCursor = data.at(-1)?.created_at

База по индексу прыгает сразу в нужное место и читает ровно двадцать строк — независимо от того, первая это порция или тысячная. Насколько это ощутимо, видно на реальном примере: команда Supabase Storage в 2026 году переписала листинг объектов с OFFSET на курсор и получила на 60 миллионах записей до 14,8× ускорения на глубоких страницах, а тысячная страница стала такой же быстрой, как первая.

Цена — интерфейс. Кнопки «перейти на страницу 37» с курсором не будет: он умеет «дальше» и «назад», но не прыжки. Для ленты, чата и бесконечного скролла это ровно то, что нужно.

Шаг 5. Проверь две вещи, без которых всё развалится

  • Индекс на колонке сортировки. Без него курсор не спасёт: база всё равно перелопатит таблицу. Сортируешь по created_at — индекс должен быть по created_at.
  • Уникальный «добивочный» ключ. Если у двух записей одинаковая дата (а при массовой вставке так и будет), одна из них потеряется между страницами. Поэтому сортируй по паре: order('created_at').order('id'), и в курсоре храни оба значения.

Что получится

Список отдаётся порциями по двадцать. Первая страница и сто первая грузятся за одинаковое время. Пользователь не ждёт, база не читает лишнего, а счёт за трафик и вычисления перестаёт расти вместе с таблицей.

Почему один и тот же пост появляется на двух страницах?

Это та самая вторая ловушка. Пока пользователь читает первую страницу, кто-то добавил новую запись — и всё сдвинулось на одну позицию. Запрос со offset 20 теперь начинается на строку раньше: последний пост первой страницы приезжает снова, а один пост между страницами пропадает совсем. Курсор эту проблему убирает по построению: он привязан к записи, а не к номеру.

Пагинация или бесконечный скролл?

Это про интерфейс, а не про базу — под капотом обе схемы одинаковы. Номера страниц лучше там, где к результату возвращаются и им делятся (поиск, каталог). Бесконечный скролл — для ленты, где важно листать, а не находить конкретное место.

Можно ли пагинировать без базы, прямо в коде?

Можно, но только пока данные помещаются в памяти и их отдаёт чужой API без пагинации. Как только источник — своя база, режь на её стороне: смысл пагинации в том, чтобы лишние строки не читались вообще, а не в том, чтобы прочитать всё и показать двадцать.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →