PlanetScale Insights: Debug MySQL and Postgres Queries

PlanetScale Insights answers which query patterns consumed database time, read unnecessary rows or produced errors. It has versions for both Postgres and Vitess/MySQL, with different engine-specific statistics. Start by selecting the branch and incident window so a chart from a quiet development database cannot mislead the investigation.

The guidance below follows official documentation checked on October 6, 2026. The worked SQL example is a hypothetical Postgres investigation, not a measured PlanetScale benchmark. Use the same sequence on your own workload: scope, rank, inspect, propose, measure again.

What Insights shows, and what a query pattern means

Open the database in PlanetScale’s dashboard and select Insights. Choose the branch and primary or replicas. The docs describe a default 24-hour window, graphs navigable over the past seven days, and click-and-drag selection for narrower periods. The latency graph defaults to p50 and p95, with p99 and p99.9 available. Other views include queries per second, rows read and rows written. Postgres overview and Vitess overview.

The query table groups normalized SQL rather than making one row for every literal value. Postgres uses ordinal placeholders such as $1; Vitess shows placeholders such as :v1. Both docs exclude transaction-control and session statements such as BEGIN, COMMIT, ROLLBACK and SET from the queries table. Postgres patterns and Vitess patterns.

Normalization makes patterns useful for comparisons, but I would not assume that every parameter value has the same cost. Keep representative values for staging tests, especially when one tenant is much larger than another. A pattern-wide median is a starting point for investigation, not proof that every user had the same experience.

MySQL and Postgres distinctions to keep straight

These distinctions come from the separate Vitess and Postgres Query Insights references. On Postgres, I/O timing columns require track_io_timing and only begin collecting after it is enabled; the docs note possible performance impact. On Vitess, an Organization Administrator can opt into complete query collection, and prepared statements still do not reveal bind values. Raw SQL can contain personal data. Do not turn collection on merely to make an agent’s explanation more convenient.

For Vitess, the query deep dive can display an explain plan. The production button is disabled unless production web-console access is enabled. That dashboard behavior should not be copied into a Postgres runbook as though the engines had identical explain-plan controls. Vitess deep dive.

Rank by the work that matters

The documented table columns include count, total time, percentage of runtime, p50/p99/max latency, rows read, rows returned and bytes returned. A high rows-read/rows-returned ratio can indicate unnecessary scanning and a possible indexing opportunity. Query statistics.

My suggested triage order is:

1. Total time: identify the patterns occupying most of the selected window’s cumulative query time.
2. Count: decide whether the pattern became slower, more frequent, or both.
3. Rows read versus returned: find reads doing large amounts of work for a small answer.
4. Tail latency: inspect p99 and notable executions instead of stopping at p50.
5. Errors: check whether the pattern fails before treating it solely as an optimization task.

This ranking avoids spending an incident on an impressive-looking but rarely executed query. Compare equal-duration windows with similar traffic where possible, and separate primary from replica observations. Save the branch, server selection and UTC boundaries with the report so somebody else can reproduce it.

Anomalies and errors are different starting points

PlanetScale defines anomalies as sustained, substantial increases in the share of queries slower than their established baseline. The Anomalies graph uses the 97.7th-percentile, two-sigma baseline. A regularly slow weekly report can raise latency without generating an anomaly because the report is running at its expected speed. Anomalies documentation.

Use an anomaly as a timestamp and a list of affected signals. The docs surface the triggering query and changes in CPU, memory, IOPS, query volume, rows and errors. They also note that active backups can coincide with anomalies and explicitly advise against disabling backups to avoid them. An anomaly is evidence of a deviation; the root cause still needs investigation. Anomaly investigation.

The Errors pages describe captured database errors over a 24-hour period. Clicking an error reveals individual queries, when they ran, duration and attached query tags. This is documented for Postgres and Vitess.

Start with the error text and time, then compare the query with the schema and application change history. If no error is captured, also inspect the client-side failure: the dashboard’s documented scope is database errors, so it cannot establish that a request reached the database in the first place. Our Prisma connection failure guide covers that earlier boundary.

Worked Postgres example: a tenant’s orders page

Assume a hypothetical application reads recent orders for one tenant and status. The pattern rises in total time and rows read while returning a small page. Replace the example values with representative staging values from your application:

EXPLAIN
SELECT id, created_at, total_cents
FROM orders
WHERE tenant_id = 42 AND status = 'paid'
ORDER BY created_at DESC
LIMIT 50;

Plain EXPLAIN shows the planned scan, joins and estimated costs without executing the statement. Cost units are planner estimates, not milliseconds. EXPLAIN ANALYZE actually runs the statement and adds runtime observations, so use it deliberately on representative staging data. PostgreSQL EXPLAIN reference.

Suppose the plan uses a sequential scan and filters most rows away. A candidate index for testing is:

-- Candidate migration for a Postgres test branch, not a production command.
CREATE INDEX orders_tenant_status_created_idx
ON orders (tenant_id, status, created_at);

The first two columns match equality conditions. PostgreSQL’s multicolumn B-tree guidance explains why constraints on leading columns efficiently limit the portion scanned. Whether this candidate wins depends on your actual data and plan; inspect the existing indexes before adding another. PostgreSQL multicolumn indexes.

After applying the candidate to the test branch, compare actual execution with the original on the same representative dataset:

EXPLAIN (ANALYZE, BUFFERS)
SELECT id, created_at, total_cents
FROM orders
WHERE tenant_id = 42 AND status = 'paid'
ORDER BY created_at DESC
LIMIT 50;

Record the scan chosen, actual rows, buffer activity and execution time. Test a large tenant and a small tenant rather than treating one parameter value as the entire workload. There is no promised latency reduction here: both the SQL and outcome must be checked against the application’s schema and data.

Once the reviewed migration reaches production, compare Insights windows for the pattern’s count, rows read, tail latency and total time. Keep application latency alongside those observations. The PlanetScale production checklist explains why the rollout procedure differs for Postgres and Vitess.

Close the observability and alert gaps

Insights is useful for query investigation. My production checklist also calls for request latency/error telemetry, connection-pool behavior, capacity metrics, deploy history and a notification path to the on-call owner. A dashboard somebody can open is different from an alert somebody receives.

For Postgres, PlanetScale exposes Prometheus-compatible per-branch metrics and HTTP service discovery. Its guide requires a service token with read_metrics_endpoints, and documents connection-state, edge-connection, WAL-size, PgBouncer and CPU metrics. The discovery API uses token authorization with TOKEN_ID:TOKEN; that differs from the MCP’s Bearer-secret authentication. Postgres Prometheus integration.

Use those metrics in the alerting system your team operates, with thresholds based on capacity and user impact. Verify a failed scrape and an application connection error as well as a slow-query case. Keep longer-lived incident evidence outside the dashboard when the investigation needs more than its documented history window.

Agents can inspect Insights and schema recommendations through the official MCP, including an insights-only endpoint that excludes SQL execution tools. Our PlanetScale MCP setup guide covers the permission distinction between reading metadata and opening a query session. Official MCP documentation.

Where Polylane fits

Polylane for PlanetScale detects production issues and fixes them by opening pull requests. It connects to PlanetScale, so when a query starts failing or slowing down it works out why, and the fix arrives ready for your team’s normal review.

Finish with a reproducible investigation record

Save the branch and engine, selected server role, incident window, normalized query pattern, error or anomaly evidence, proposed change and before/after measurements. State what you could not observe. If the database became faster but the endpoint did not, reopen the application-side investigation rather than calling the index work a resolved incident.

Running on PlanetScale? See how Polylane monitors PlanetScale in production.