GO — Healthy across the board

• Last commit 7w ago
• 22+ active contributors
• Distributed ownership (top contributor 37% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Scorecard: default branch unprotected (0/10)

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard}

PageHelper is a MyBatis physical pagination plugin that automatically rewrites SQL queries to add database-specific LIMIT/OFFSET clauses. It supports 30+ databases (MySQL, PostgreSQL, Oracle, SQL Server, etc.) and handles complex single-table and multi-table pagination without manual LIMIT clause writing. Monolithic JAR structure: core interceptor (PageInterceptor.java) wraps MyBatis execution; dialect/ directory contains 30+ database-specific implementations (AbstractDialect base class with MySqlDialect, OracleDialect, etc.); dialect/auto/ handles auto-detection via DataSource connection inspection; cache/ provides pluggable SQL cache layers; main API surface is PageHelper.java and PageInfo.java.

Java developers using MyBatis who need to add pagination to database queries without writing dialect-specific SQL. Particularly valuable for teams building multi-database applications that need to support multiple database backends with one codebase.

Production-ready and actively maintained. Version 6.1.1 targets JDK8+, has CI/CD workflows (GitHub Actions for pull requests and releases), comprehensive test coverage across 30+ database dialects, and consistent Maven releases. The project has been stable for years with 12k+ GitHub stars.

Low risk overall: single maintainer (abel533@gmail.com) but well-established community. Dependency on jsqlparser for SQL parsing (requires version compatibility—see jsqlparser4_7兼容性改动.patch) and potential breaking changes between major versions. No obvious unmaintained dependencies; pom.xml shows standard MyBatis ecosystem deps.

Version 6.1.1 is current. GitHub workflows show automated testing on PRs and Maven releases. The patch file jsqlparser4_7兼容性改动.patch indicates recent work on jsqlparser 4.7 compatibility. No detailed milestone or PR data visible, but release workflow is active.

git clone https://github.com/pagehelper/Mybatis-PageHelper.git && cd Mybatis-PageHelper && mvn clean install

Daily commands: This is a library, not a runnable application. Use: mvn test to run the test suite across all database dialects.

• src/main/java/com/github/pagehelper/PageInterceptor.java — Core MyBatis interceptor that hooks into query execution to apply pagination logic; essential entry point for understanding the entire plugin architecture
• src/main/java/com/github/pagehelper/PageHelper.java — Primary API facade providing thread-local PageHelper.startPage() and query methods; all users interact through this class
• src/main/java/com/github/pagehelper/dialect/AbstractDialect.java — Base class for all database dialect implementations; defines the contract for SQL transformation and pagination syntax generation
• src/main/java/com/github/pagehelper/Page.java — Core data model holding pagination state (pageNum, pageSize, total, rows); passed through the entire execution pipeline
• src/main/java/com/github/pagehelper/parser/CountSqlParser.java — Parses and transforms SELECT queries into COUNT queries for total record calculation; critical for pagination metadata
• src/main/java/com/github/pagehelper/page/PageAutoDialect.java — Auto-detects database dialect from DataSource configuration; enables zero-configuration setup across different databases
• src/main/java/com/github/pagehelper/PageProperties.java — Configuration class holding all plugin settings (dialect, offsetAsPageNum, rowBoundsWithFc, etc.); loaded from properties/YAML

Add Support for a New Database Dialect

1. Create a new dialect class extending AbstractDialect in src/main/java/com/github/pagehelper/dialect/helper/ (e.g., NewDbDialect.java) (src/main/java/com/github/pagehelper/dialect/helper/MySqlDialect.java)
2. Implement getPageSql(sql, page, pageSize, params) to generate dialect-specific LIMIT/OFFSET syntax (src/main/java/com/github/pagehelper/dialect/AbstractDialect.java)
3. Register the dialect in AutoDialect.detectDialect() method or in PageProperties configuration (src/main/java/com/github/pagehelper/AutoDialect.java)
4. Optionally create a RowBounds variant in src/main/java/com/github/pagehelper/dialect/rowbounds/ for RowBounds-based pagination (src/main/java/com/github/pagehelper/dialect/rowbounds/MySqlRowBoundsDialect.java)

Add Custom BoundSql Interceptor

1. Create a class implementing BoundSqlInterceptor interface in src/main/java/com/github/pagehelper/ (src/main/java/com/github/pagehelper/BoundSqlInterceptor.java)
2. Implement intercept(BoundSql, MetaObject) to modify SQL before execution (e.g., add hints, change parameters) (src/main/java/com/github/pagehelper/BoundSqlInterceptor.java)
3. Register your interceptor in PageProperties.boundSqlInterceptors property or via PageBoundSqlInterceptors.addInterceptor() (src/main/java/com/github/pagehelper/page/PageBoundSqlInterceptors.java)

Implement Auto-Detection for a New DataSource Type

1. Create a new class extending DataSourceAutoDialect in src/main/java/com/github/pagehelper/dialect/auto/ (e.g., MyDataSourceAutoDialect.java) (src/main/java/com/github/pagehelper/dialect/auto/HikariAutoDialect.java)
2. Override getDialectClass() to detect your DataSource type and return the appropriate dialect class (src/main/java/com/github/pagehelper/dialect/auto/DataSourceAutoDialect.java)
3. Register the new auto-dialect in DataSourceNegotiationAutoDialect.negotiateDialectClass() or configure it in application properties (src/main/java/com/github/pagehelper/dialect/auto/DataSourceNegotiationAutoDialect.java)

Configure PageHelper for Spring Boot Application

1. Add pagehelper dependency to pom.xml or gradle build file (pom.xml)
2. Create @Configuration class or set properties in application.properties/application.yml with pagehelper.* properties (src/main/java/com/github/pagehelper/PageProperties.java)
3. Ensure PageInterceptor is registered as a MyBatis plugin (auto-configured in Spring Boot starter) (src/main/java/com/github/pagehelper/PageInterceptor.java)
4. In your mapper/service, call PageHelper.startPage(pageNum, pageSize) before each query (src/main/java/com/github/pagehelper/PageHelper.java)

Thread-local context: Page object lives in ThreadLocal, so pagination only applies to the immediately following query—must call PageHelper.startPage() directly before each query in the same thread. JSqlParser version mismatches can break SQL parsing (see jsqlparser4_7兼容性改动.patch); verify jsqlparser version in pom.xml when updating. Auto-dialect detection reads from live DataSource—requires a working database connection at initialization time. Some databases need dialect-specific configuration (e.g., SQL Server 2012 vs 2005). Nested queries and dynamic SQL generated at runtime may not rewrite correctly if jsqlparser doesn't parse them.

• MyBatis Interceptor Pattern — PageHelper works entirely via MyBatis plugin interface (QueryInterceptor); understanding Interceptor.intercept() and plugin wrapping is essential to modifying pagination logic
• SQL AST Parsing and Rewriting — PageHelper uses JSqlParser to parse SELECT statements into abstract syntax trees, modify them to add LIMIT clauses, and regenerate SQL—this is the core transformation mechanism
• ThreadLocal Context Storage — Pagination parameters live in ThreadLocal<Page>, allowing pagination to apply only to the immediately following query without explicit method parameters
• Database Dialect Pattern — PageHelper implements 30+ dialect classes (MySqlDialect, OracleDialect, etc.) to handle database-specific LIMIT/OFFSET syntax differences—critical for multi-database support
• DataSource Connection Pooling Detection — Auto-dialect feature inspects DataSource implementation class (Hikari, Druid, C3P0, etc.) to infer database type without user configuration—requires reflection and class introspection
• Physical vs Logical Pagination — PageHelper implements physical pagination (rewriting SQL to LIMIT at database layer), not logical (loading all rows and slicing in-memory)—crucial for performance with large result sets
• Bounded Query Caching — Rewritten SQL is cached (GuavaCache, SimpleCache) to avoid re-parsing the same query repeatedly—pluggable cache strategy lets teams choose between Guava or custom implementations

• mybatis/mybatis-3 — Core MyBatis framework that PageHelper plugs into via the Interceptor interface
• baomidou/mybatis-plus — Alternative MyBatis enhancement framework with built-in pagination via IPage, direct competitor
• pagehelper/pagehelper-spring-boot-starter — Spring Boot auto-configuration wrapper for PageHelper—allows zero-config setup in Spring Boot projects
• pagehelper/pagehelper-spring — Spring Framework integration package for declarative pagination via Spring namespaces and AOP

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for BoundSqlInterceptor and BoundSqlInterceptorChain

The BoundSqlInterceptor.java and BoundSqlInterceptorChain.java files exist in the codebase but there are no visible test files for these critical interceptor chain components. These handle SQL modification logic that is central to pagination functionality. Adding thorough unit tests would ensure the interceptor chain pattern works correctly across different scenarios and prevent regressions.

• [ ] Create src/test/java/com/github/pagehelper/BoundSqlInterceptorTest.java with tests for individual interceptor execution
• [ ] Create src/test/java/com/github/pagehelper/BoundSqlInterceptorChainTest.java with tests for chain order, short-circuit behavior, and error handling
• [ ] Test edge cases: empty interceptor chain, null SQL, multiple interceptors modifying the same BoundSql
• [ ] Run tests with Maven and verify coverage of both success and failure paths

Add integration tests for AutoDialect detection across different datasource pools

The repo supports multiple datasource pool implementations (Druid, HikariCP, C3P0, DBCP, Tomcat) with separate AutoDialect classes in src/main/java/com/github/pagehelper/dialect/auto/. Currently there appear to be no dedicated integration tests verifying that each pool's dialect detection works correctly. This is high-risk code since incorrect dialect detection leads to broken pagination.

• [ ] Create src/test/java/com/github/pagehelper/dialect/auto/AutoDialectIntegrationTest.java
• [ ] Add test cases for DruidAutoDialect.java, HikariAutoDialect.java, C3P0AutoDialect.java, DbcpAutoDialect.java, and TomcatAutoDialect.java
• [ ] Test both successful detection scenarios and fallback behavior when pools are not available
• [ ] Verify correct dialect is returned for MySQL, PostgreSQL, Oracle, and SQL Server databases with each pool

Add unit tests for all database-specific dialect implementations

The src/main/java/com/github/pagehelper/dialect/helper/ directory contains 15+ database dialect implementations (MySqlDialect, OracleDialect, PostgreSqlDialect, Db2Dialect, etc.) but there are no visible corresponding test files. Each dialect must correctly transform SQL for its specific database syntax. Missing tests for these dialects means edge cases in SQL generation (LIMIT/OFFSET, ROW_NUMBER, etc.) could be silently broken.

• [ ] Create src/test/java/com/github/pagehelper/dialect/helper/DialectTestSuite.java as a parent test class with common test cases
• [ ] Add dialect-specific tests: MySqlDialectTest.java, OracleDialectTest.java, PostgreSqlDialectTest.java, SqlServer2012DialectTest.java, Db2DialectTest.java
• [ ] For each dialect, test: basic pagination SQL, complex JOIN queries, subqueries, and database-specific syntax (e.g., Oracle's ROWNUM, PostgreSQL's LIMIT/OFFSET)
• [ ] Verify countSql generation and pageSql transformation produce valid SQL for each database

• Add integration tests for Impala dialect—it's registered in AutoDialect but no dedicated test class exists in src/test/java/com/github/pagehelper/test/integration/
• Document the BoundSqlInterceptor and BoundSqlInterceptorChain classes in src/main/java/com/github/pagehelper/ with JavaDoc examples—they enable post-processing but have minimal comments
• Add support for auto-detection of CloudScape and Derby via the auto-dialect system by creating src/main/java/com/github/pagehelper/dialect/auto/DerbyAutoDialect.java following the pattern of DruidAutoDialect.java

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pagehelper-org/Mybatis-PageHelper shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pagehelper-org/Mybatis-PageHelper repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pagehelper-org/Mybatis-PageHelper.

What it runs against: a local clone of pagehelper-org/Mybatis-PageHelper — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pagehelper-org/Mybatis-PageHelper | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 78 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pagehelper-org/Mybatis-PageHelper. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pagehelper-org/Mybatis-PageHelper.git
#   cd Mybatis-PageHelper
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pagehelper-org/Mybatis-PageHelper and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pagehelper-org/Mybatis-PageHelper(\\.git)?\\b" \\
  && ok "origin remote is pagehelper-org/Mybatis-PageHelper" \\
  || miss "origin remote is not pagehelper-org/Mybatis-PageHelper (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main/java/com/github/pagehelper/PageInterceptor.java" \\
  && ok "src/main/java/com/github/pagehelper/PageInterceptor.java" \\
  || miss "missing critical file: src/main/java/com/github/pagehelper/PageInterceptor.java"
test -f "src/main/java/com/github/pagehelper/PageHelper.java" \\
  && ok "src/main/java/com/github/pagehelper/PageHelper.java" \\
  || miss "missing critical file: src/main/java/com/github/pagehelper/PageHelper.java"
test -f "src/main/java/com/github/pagehelper/dialect/AbstractDialect.java" \\
  && ok "src/main/java/com/github/pagehelper/dialect/AbstractDialect.java" \\
  || miss "missing critical file: src/main/java/com/github/pagehelper/dialect/AbstractDialect.java"
test -f "src/main/java/com/github/pagehelper/Page.java" \\
  && ok "src/main/java/com/github/pagehelper/Page.java" \\
  || miss "missing critical file: src/main/java/com/github/pagehelper/Page.java"
test -f "src/main/java/com/github/pagehelper/parser/CountSqlParser.java" \\
  && ok "src/main/java/com/github/pagehelper/parser/CountSqlParser.java" \\
  || miss "missing critical file: src/main/java/com/github/pagehelper/parser/CountSqlParser.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 78 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~48d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pagehelper-org/Mybatis-PageHelper"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.