SQL Runner — how it works and what it accepts

SQL Runner executes SELECT queries against a sandboxed read-only database and returns results in the browser. This page explains the accepted statement types, timeout behavior, rate limits, and how to write queries that produce reliable output.

Accepted statements

SQL Runner accepts SELECT statements only. This includes simple SELECT statements, SELECT with JOIN (INNER, LEFT, RIGHT, FULL OUTER), SELECT with subqueries, WITH ... SELECT (CTE patterns), SELECT statements with window functions such as OVER and PARTITION BY, and EXPLAIN SELECT for plan inspection without data mutation.

Rejected statements include INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, GRANT, REVOKE, EXEC, and CALL. Validation exists to protect shared infrastructure and prevent accidental modification of data. This constraint is enforced independently in two layers: application-level statement validation rejects non-SELECT intent before execution, and database-user permissions provide a second block by removing write privileges even if input validation were bypassed.

Timeout

Every query is subject to a hard 5-second timeout enforced at the database connection level. If execution does not finish within 5 seconds, the connection is terminated and an error is returned to the UI. The timer starts when execution begins at the database, not when the HTTP request first arrives at the service layer.

Timeouts commonly occur in a few patterns: full table scans on large tables (often from missing WHERE filters or missing indexes), unindexed joins across large relations, GROUP BY operations on high-cardinality columns without narrow date or status constraints, and result sets that attempt to return far too many rows for interactive inspection.

If your query times out, narrow the WHERE clause first, add LIMIT, and verify index coverage for join and filter keys if you have privileges to inspect plans. SQL Runner is designed for narrow operational inspection checks, not for long-running analytics workloads that belong in dedicated reporting infrastructure.

Rate limits

SQL Runner enforces a rate limit of 30 queries per minute per IP address. Requests over this threshold receive HTTP 429 Too Many Requests with a Retry-After header that indicates when the request window resets.

This limit protects shared service capacity and helps ensure fair access during peak usage. If you hit the limit during intensive debugging, consolidate checks into fewer targeted queries and wait for the reset window instead of repeatedly retrying the same request.

If you are automating tests or running programmatic scripts, design your code to respect this rate limit by adding delays between executions. Under no circumstances should automated scrapers or stress-test scripts target this endpoint, as doing so can trigger temporary IP blocks to preserve availability for interactive human users.

Writing reliable queries (tips)

Reliable SQL output begins with deterministic query design. Always include ORDER BY so row order is reproducible between runs. Always include LIMIT during exploratory checks to keep output bounded and execution responsive. Prefer explicit column lists instead of SELECT * to avoid hidden schema drift and unnecessary transfer of large or sensitive fields.

Match WHERE literal types to underlying column types, for example integer comparisons against integer columns and timestamp comparisons against timestamp values. For boolean existence checks, use EXISTS rather than COUNT(*) because EXISTS expresses intent clearly and can stop after the first match. These patterns reduce false conclusions during incident analysis and make team handoff results reproducible.

When dealing with large volumes of data, proper index placement on frequently queried columns is crucial for maintaining acceptable execution speeds. If a query scans a column that is not indexed, the database is forced to evaluate every row sequentially, which leads to slow response times and eventual timeouts. Developers should proactively request query plan analysis (EXPLAIN) when performance degrades, ensuring that database resource usage remains optimized and execution plans are efficient.

Error messages reference

When a query fails, the error text is usually enough to choose the next correction step. The table below maps common SQL Runner errors to likely causes and immediate remediation.