Forgejo PAGINATION_LIMIT configuration for API pagination measurement

What the Numbers Say (Confirmed)

Forgejo’s PAGINATION_LIMIT in the [service] section of app.ini caps the limit query‑parameter on list endpoints (repos, issues, PRs). Changing it requires a server restart and the value is clamped to the configured maximum (often 100, but the exact default and cap vary by release).

Immediate Answer to Your Questions

• Increasing PAGINATION_LIMIT from 20 to 100 typically reduces the *number of HTTP requests* needed to enumerate a fixed set of items, thereby lowering per‑request overhead (authentication, routing, JSON framing).
• The *total request latency* for the full listing usually drops, but the *per‑request latency* rises because each query fetches more rows and the JSON payload grows.
• Throughput (requests per second) tends to improve linearly up to the point where a single request’s memory or database buffer usage hits a practical limit; a sharp cliff at 100 is not guaranteed but can appear if the DB engine or Go garbage collector struggles with very large result sets.
• Database query count per page stays roughly constant (Forgejo uses OFFSET/LIMIT queries plus a few permission checks). Thus, total query count for a full listing scales inversely with page size.
• Response time difference between limit=20 and limit=100 is usually a few milliseconds per page on a modest database, but can grow to tens of milliseconds if the dataset is large or the DB is heavily loaded.

Likely Explanation (Not Confirmed)

In practice, larger pages shift the bottleneck from HTTP connection churn to database row fetching and Go’s JSON encoder. With a very high limit, the single request can become CPU‑bound (serialization) or memory‑bound (buffer allocation), causing a tail‑latency spike. Concurrent load exacerbates this because the DB connection pool may be exhausted, forcing back‑pressure and increasing overall latency.

How to Measure It Yourself

1. Determine the exact default and maximum. Run forgejo admin config or inspect app.ini and the bundled app.example.ini for your version.
2. Prepare a stable dataset. Create a known number of repositories, issues, or PRs (e.g., 10,000 items) so that the total count is fixed across tests.
3. Warm‑up the server. Restart Forgejo, then perform a few list requests at the default limit to allow caches and connection pools to settle.
4. Run a benchmark. Use a load tool (k6, wrk, or a simple Go script) to issue concurrent GETs to the list endpoint with ?limit=20 and ?limit=100. Keep the concurrency level (e.g., 50 VUs) the same for both runs.
5. Collect metrics. Record per‑request latency percentiles (p50, p95, p99), total elapsed time for the full listing, and throughput (requests/second). Enable database query logging to count queries per full listing.
6. Analyze memory and CPU. Monitor top or htop and the Go runtime’s pprof to see if large pages trigger GC pauses or memory pressure.
7. Compare. Plot latency vs. limit and look for linearity or a cliff. Verify that the total number of DB queries scales inversely with the page size.

What We Still Need to Know

To fine‑tune the recommendation, please let us know which database backend you are using (PostgreSQL, MySQL, SQLite, etc.). Different engines handle large LIMIT clauses and buffer sizes differently, which can affect the point at which a performance cliff appears.