Implementing pagination with PostgreSQL and the MantaHQ SDK

Summary

Pagination improves performance and usability when applications display large datasets. Pagination limits the number of records returned in each request and reduces rendering overhead in the browser.

This article explains:

• how pagination works in PostgreSQL
• the hidden complexity of traditional pagination architectures
• how the MantaHQ SDK simplifies pagination across PostgreSQL databases and MantaHQ internal tables
• when developers should and should not use the MantaHQ SDK

---

Why pagination exists

Applications often need to display thousands or millions of records. Loading all records at once increases query time, memory usage, and network latency. Pagination solves these problems by dividing results into smaller segments.

Pagination provides the following benefits:

• reduces database query load
• reduces data transfer size
• improves browser rendering performance
• improves user navigation

Most applications use one of the following pagination strategies:

Page-based pagination

Page-based pagination retrieves results by page number. The application calculates which rows to skip and which rows to return.

Cursor-based pagination

Cursor-based pagination retrieves results using a unique record identifier. Cursor pagination performs better when datasets grow large. This article focuses on page-based pagination because page-based pagination remains the most common implementation.

---

How pagination works in traditional applications

Traditional pagination requires multiple infrastructure layers. The following architecture shows a typical request flow:

Each layer performs a specific responsibility:

• The browser requests a page of results.
• The backend validates permissions and calculates pagination values.
• PostgreSQL executes pagination queries.
• The backend returns pagination metadata and result records.

Developers must build and maintain a backend endpoint for each dataset that supports pagination. This backend layer often introduces most of the complexity in pagination implementations.

---

The tradeoffs behind traditional pagination

Pagination often appears simple, but supporting pagination across database queries, backend services, and frontend state management requires significant code.

PostgreSQL query example

The following query retrieves the second page of users when each page contains ten records:

SELECT *
FROM users
ORDER BY created_at DESC
LIMIT 10 OFFSET 10;

The PostgreSQL query requires the developer to calculate the offset manually using the following formula:

(page_number - 1) * page_size

Pagination also requires a second query to calculate the total number of records:

SELECT COUNT(*) FROM users;

How pagination is handled on the backend

To support pagination, the backend endpoint usually handles these tasks:

• validates query parameters
• calculates offsets
• executes pagination queries
• calculates page counts
• returns structured pagination metadata

Pagination endpoints often require more than sixty lines of backend code after developers implement validation, access control, and error handling.

How pagination is handled on the client side

To fetch, display, and navigate paginated records, the frontend must:

• store current page state
• send page parameters to the backend
• update pagination controls
• manage loading and error states

Implementing frontend pagination often adds forty or more lines of state management and UI logic.

Traditional pagination summary

Traditional pagination often requires:

Layer	Typical Complexity
PostgreSQL queries	medium
Backend pagination logic	high
Frontend pagination state	medium

Developers must maintain backend, frontend, and database logic for each dataset that requires pagination.

---

Pagination using the MantaHQ SDK

The MantaHQ SDK reduces pagination complexity by acting as a unified data access layer. The MantaHQ SDK connects directly to:

• PostgreSQL databases
• MantaHQ internal data tables

Developers use a single syntax for pagination regardless of the data source.

How the MantaHQ SDK changes the workflow

The MantaHQ SDK simplifies pagination by providing a single data access layer. It connects directly to both your PostgreSQL database and internal Manta tables, eliminating the need for separate backend endpoints and manual offset calculations.

• calculates pagination offsets
• retrieves total record counts
• returns structured pagination metadata
• enforces database access controls

The MantaHQ SDK reduces pagination implementation from three layers to two layers:

Fetching paginated data with the Manta SDK

This example demonstrates how to implement pagination in a job board application using React and the MantaHQ SDK.

import { MantaClient } from "mantahq-sdk";
import { useEffect, useState } from "react";

const API_KEY = import.meta.env.VITE_MANTAHQ_API_KEY;
const manta = new MantaClient({ sdkKey: API_KEY });

function JobList() {
  const [jobs, setJobs] = useState([]);
  const [totalPages, setTotalPages] = useState(null);
  const [currentPage, setCurrentPage] = useState(1);

  useEffect(() => {
    async function fetchJobs() {
      const response = await manta.fetchAllRecords({
        table: "jobs",
        fields: ["title", "company", "location"],
        page: currentPage,
        list: 9,
      });

      setJobs(response.data);
      setTotalPages(response.meta.totalPages);
    }

    fetchJobs();
  }, [currentPage]);

  return (
    <div>
      <ul>
        {jobs.map((job) => (
          <li key={job.id}>
            {job.title} - {job.company}
          </li>
        ))}
      </ul>

      <button
        disabled={currentPage === 1}
        onClick={() => setCurrentPage((page) => page - 1)}
      >
        Previous
      </button>

      <button
        disabled={currentPage === totalPages}
        onClick={() => setCurrentPage((page) => page + 1)}
      >
        Next
      </button>
    </div>
  );
}

export default JobList;

What this code is doing

• Reactive fetching with useEffect: The component monitors currentPage. Each time the page changes, it triggers an SDK call to fetch the corresponding dataset segment.
• Automatic offset and limit calculation: The SDK handles LIMIT and OFFSET internally based on the list parameter. Developers don’t need to manually compute SQL pagination.
• Pagination metadata provided: The response includes data.meta.totalPages. The component uses this to enable or disable “Next” and “Previous” buttons accurately.
• Minimal state management: Frontend only tracks jobs, currentPage, loading, and error. The SDK abstracts database querying and counting logic.
• Unified database interface: The same SDK call works for MantaHQ internal tables or external PostgreSQL databases, eliminating backend boilerplate and reducing integration complexity.

SDK pagination workflow

The SDK accepts pagination parameters and handles database pagination internally. It eliminates manual offset calculations and the need for separate count queries.

The SDK also returns pagination metadata in a single response. The frontend uses this metadata to manage navigation buttons and page indicators automatically.

---

Traditional pagination vs MantaHQ SDK

The table below compares pagination implemented manually with a backend versus pagination handled using the MantaHQ SDK:

Feature / Task	Traditional Pagination	MantaHQ SDK
Backend endpoints needed	One per dataset	Not required
Offset calculation	Manual calculation required	Automatic
Total record counting	Separate SQL query needed	Included in SDK response
Code maintenance burden	High	Minimal
Development time	Longer	Shorter
Frontend integration	Manual state & UI logic	Automatic metadata handling

---

Run the pagination example

Complete a working pagination example in under fifteen minutes by following these steps:

1. Download the example dataset.
2. Upload the dataset to a Manta internal table or connect a PostgreSQL database.
3. Install the MantaHQ SDK.
4. Implement pagination using the provided example component.

Follow the MantaHQ documentation for setup:

• Connect your PostgreSQL database to MantaHQ
• Upload a CSV to Manta internal tables
• Install the MantaHQ SDK.

---

Conclusion

Pagination is essential for scalable applications. Traditional approaches require coordinating database queries, backend APIs, and frontend state management, which increases development time and maintenance overhead.

The MantaHQ SDK simplifies pagination by handling database queries, offset calculations, and metadata in a single interface. Developers can implement paginated views quickly, reduce boilerplate, and focus on building application features instead of managing infrastructure.

---

Prefer video tutorials? Watch a step-by-step video demonstration.

For full pagination reference and advanced usage, see the MantaHQ SDK documentation.

---

By Trevor C. Justus
Developer Relations at MantaHQ