[williamjallen]

Resolves #2734

• Added or updated tests
• Documented user facing changes

Changes

Adds the option allowUnlimited to @paginate and the paginated relation directives, and the configuration option pagination.allow_unlimited.
Fields that opt in generate first: Int instead of first: Int!, and first: null returns all items on a single page.

Nested relations then load the items of all parents with a single whereIn query and no count query, the same query as a non-paginated @hasMany.
The current workaround of passing a large first runs a count query plus a UNION ALL with one subquery per parent.
In a local benchmark with 100 parents and 2,000 children, database time went from ~75 ms to ~2 ms.

Builder directives that depend on the parent model (#2671) still get one subquery per parent.
Parents are grouped by the SQL and bindings of their decorated relation query, and only fields with field builder directives are compared.
Each subquery of the resulting UNION ALL gets a very large LIMIT, because MySQL ignores the ORDER BY of subqueries without one.

allowUnlimited requires that no maximum count applies.
Combining it with maxCount throws a DefinitionException when building the schema.
If max_count is configured after the schema was cached, first: null is rejected at runtime as well.

Breaking changes

None, fields keep generating first: Int! unless they opt in.

Changelog

Added

• Add option allowUnlimited to @paginate and paginated relation directives and configuration option pagination.allow_unlimited to fetch all items with first: null

[williamjallen]

@spawnia Any chance you could take a quick look at this?

[Copilot]

🟡 Changes recommended

Unlimited pagination currently bypasses maximum limits and mishandles some pagination metadata and nested relationships.

4 open findings

• Unlimited loading applies parent-specific decorators incorrectly · New
• Initialize empty relations before matching fetched rows · New
• first:null bypasses configured maxCount query limit · New
• Unlimited requests ignore page offsets and produce invalid pagination · New

What changed in this PR

Enables unlimited pagination when first is omitted or null.

Changes:

• Makes first nullable.
• Fetches complete result sets for root and nested relations.
• Adds pagination tests for unlimited results.

File	Description
src/​Pagination/​PaginationArgs.php	Handles nullable limits and unlimited fetching.
src/​Pagination/​PaginationManipulator.php	Makes generated first arguments nullable.
src/​Execution/​ModelsLoader/​PaginatedModelsLoader.php	Supports unlimited nested relationships.
tests/​Unit/​Pagination/​PaginateDirectiveTest.php	Updates nullable argument tests.
tests/​Integration/​Pagination/​PaginateDirectiveDBTest.php	Tests unlimited pagination variants.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

🔵 Needs a closer look

Relation query grouping has an unresolved correctness issue, and its database-specific UNION behavior needs human validation.

1 open issue

• Preserve per-parent limits and offsets in grouped queries · New

_{Review effort: Balanced}