How to Debug Performance Issues in Retool Apps

Open your app in edit mode. Open the Debug Panel (bug icon). Navigate to the Performance tab. Read each grade section. Note: Payload Size grade (A=all queries under 1.6MB, F=one or more queries dramatically over), Component Count grade (A=under 30 components, F=50+ components), and Query Count grade (A=few queries on page load, D/F=many queries on page load). Write down the grade for each category — this is your baseline before making any changes.

Switch to the Queries tab. Reload the app to capture a fresh execution trace. The Queries tab shows all queries that ran during page load, with their duration in milliseconds. Identify queries taking over 300ms — click on each to see their payload size. Queries over 1.6MB payload are immediately flagged with a warning. Note which queries ran on page load (they appear in the first few seconds after reload) vs which are triggered by user interaction.

For each slow query in the Queries tab, click to expand it. Look for the 'Response size' or payload size information. If a query returns many rows, check: How many rows does it need to return? Are there unnecessary columns in the SELECT? Is there a LIMIT clause? A 1,000-row query with 20 columns generates more data than a 10,000-row query with 2 columns — column count matters as much as row count for payload size.

1// Checklist for each large-payload query:
2// 1. Count columns: SELECT * returns everything vs SELECT id, name, status returns 3
3// 2. Check row count: is there a WHERE clause and LIMIT?
4// 3. Check for large text/JSON columns: description TEXT can be kilobytes per row
5// 4. Check for binary data: image Base64 in SQL results balloons payload
6
7// Example: calculate approximate payload size
8// 1000 rows × 5 columns × avg 50 bytes/value ≈ 250KB (fine)
9// 1000 rows × 40 columns × avg 200 bytes/value ≈ 8MB (problem)

In the Queries tab, look at which queries fire within the first 2 seconds after page load. These are your page-load queries. Count them. For each one, ask: Is this query needed for the initial view, or only when the user interacts? For queries only needed on user interaction (e.g., a detail query for a modal, a search query), disable 'Run on page load' in the query settings. This reduces simultaneous database load and speeds up initial render.

Open Chrome DevTools Network tab. Filter for 'api/v2/queries'. Reload the app. The network waterfall shows each query as a horizontal bar split into: waiting (time in queue), TTFB (time to first byte — includes Retool routing + database execution), and download (response payload download). If TTFB is 2 seconds but download is 100ms, the bottleneck is the database query execution. If TTFB is 100ms but download is 2 seconds, the bottleneck is payload size. This split tells you whether to optimize SQL or reduce payload.

Combine the Debug Panel Performance grades and Queries tab timing into a fix priority list. Order fixes by: (1) Payload grade F — immediate payload reduction needed, (2) Query grade D/F — too many page-load queries, disable unnecessary ones, (3) Slow individual queries (>500ms) — SQL optimization or caching, (4) Component count grade — split into multipage app. Implement one fix at a time and re-check grades after each change to measure improvement.