Skip to content
Get packs

Guide · Open source

How to use Mybatis-PageHelper: Maven setup and paging basics

Updated · written with AI from the project's own documentation and checked against our catalogue data

Mybatis-PageHelper is a pagination plugin for MyBatis, a Java database library. It adds page-by-page query support so you do not have to write paging logic into each SQL statement by hand. This guide covers what you need installed, how to add the dependency, which databases are supported and how to handle a database that is not on the list.

PageHelperpagehelper-org/Mybatis-PageHelper · ★ 12.3k · MIT

Quick start

  1. 1Confirm prerequisites. Check that you have Java JDK 8+ for PageHelper 6, MyBatis 3.1.0+ and jsqlparser available.
  2. 2Add the Maven dependency. Copy the pagehelper dependency block into pom.xml and replace the version placeholder with the latest release.
  3. 3Check your database. Confirm your database appears in the README's dialect alias list.
  4. 4Configure a custom dialect if needed. If your database is not listed, set dialectAlias with a custom implementation or a supported alias.
  5. 5Read the How To Use guide. Open the project's How To Use page for configuration and usage details.

What you need before you start

PageHelper hooks into MyBatis, so it only helps Java projects that already use MyBatis. The README lists the following requirements.

  • Java JDK 8+ for PageHelper 6 (per the README). The README also says PageHelper 5 supports JDK 6+.
  • MyBatis 3.1.0+ (per the README).
  • jsqlparser, which the README describes as a required dependency.

Add PageHelper to your Maven project

If you use Maven, add the dependency to your pom.xml. The README uses a version placeholder, so replace it with the latest release before you build. jsqlparser is also needed on the classpath; the README notes that the versions of pagehelper and jsqlparser correspond to the dependency versions in pom.xml.

  • Copy the dependency block into the dependencies section of pom.xml.
  • Replace the version placeholder with the latest release.
  • If you use Spring Boot, the README points to pagehelper-spring-boot-starter as a separate project.
<dependency> <groupId>com.github.pagehelper</groupId> <artifactId>pagehelper</artifactId> <version>最新版本</version> </dependency>

Check whether your database is supported

PageHelper produces physical (database-level) paging for many databases. The plugin registers a dialect alias for each one, and it picks the matching paging syntax automatically. The README's list includes HSQLDB, H2, PostgreSQL, MySQL, MariaDB, SQLite, Oracle, DB2, AS400, Informix, SQL Server, Derby, DM (Dameng), Kingbase, openGauss and several others.

If your database is not in the list, you can set the dialectAlias parameter. The README says this lets you define a custom implementation alias, and that multiple entries are separated by semicolons. This adds setup work, so check the list first.

  • Example: oracle=com.github.pagehelper.dialect.helper.OracleDialect
  • Example using a shorter alias from version 6.0: oracle=oracle9i
  • Example mapping Dameng to Oracle syntax: dm=oracle
<property name="dialectAlias" value="oracle=com.github.pagehelper.dialect.helper.OracleDialect"/>

Understand how the README describes the plugin's scope

The README says the plugin supports complex single-table and multi-table paging. It also links to an "Important" page for special cases, so read that before you rely on unusual queries. For the full configuration and usage options, the README sends you to the How To Use document in the project wiki.

The README also mentions a QueryInterceptor specification for advanced use of the Executor interceptor, which is documented separately in the wiki.

  • Read the Important notes page for special cases.
  • Read the How To Use page for configuration and usage details.
  • Read the Changelog before upgrading between major versions.

What people use it for

  • Adding page-by-page query results to a Java service that already uses MyBatis.
  • Paging queries on MySQL, PostgreSQL or Oracle, which the README lists as supported.
  • Reusing one paging plugin across several MyBatis projects instead of writing custom paging code for each one.
  • Running paged queries on a database the README lists, such as H2 or SQLite, for development or testing.

Frequently asked questions

Is Mybatis-PageHelper free to use?

The repository is licensed under MIT, according to the project's listing. MIT is a permissive open-source licence, but check the LICENSE file in the repository before you rely on it for a commercial product.

What are the requirements for Mybatis-PageHelper?

According to the README, PageHelper 6 needs Java JDK 8+, MyBatis 3.1.0+ is required and jsqlparser is a required dependency. PageHelper 5 supports JDK 6+.

How do I install Mybatis-PageHelper?

If you use Maven, add the pagehelper dependency with groupId com.github.pagehelper and artifactId pagehelper to pom.xml. Replace the version placeholder with the latest release. The README also lists jsqlparser as a required dependency.

Which databases does Mybatis-PageHelper support?

The README lists many databases, including MySQL, PostgreSQL, Oracle, MariaDB, SQL Server, DB2, H2, SQLite and Dameng. If your database is not in the list, you can set the dialectAlias parameter to map a custom implementation.

Can I use Mybatis-PageHelper without MyBatis?

No. The plugin hooks into MyBatis, so it will not help in projects that do not use it. The README also describes it as a Java library only.

How does Mybatis-PageHelper compare with MyBatis-Plus or Spring Data JPA?

This source does not include a direct comparison, so it cannot say which is better. PageHelper is a MyBatis pagination plugin with a configurable dialect system. MyBatis-Plus and Spring Data JPA are separate options that you would need to evaluate on their own documentation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use Mybatis-PageHelper if you already write Java with MyBatis and want a configurable paging plugin that supports the databases listed in the README. Pick something else if your project does not use MyBatis, is not Java, or runs on a database that is not on the list and you do not want to write custom dialect setup.

Install options & downloads