---
title: Find and fix a slow PostgreSQL query in your app
description: Investigate one slow PostgreSQL query with representative test data, preserve its results, and compare execution plans.
url: "https://vercel.com/kb/prompts/fix-slow-database-query"
last_updated: 2026-11-07
related_resources:
  "[Read PostgreSQL execution plans](https://www.postgresql.org/docs/current/using-explain.html)": "Interpret plan nodes, estimates, and actual execution statistics."
  "[EXPLAIN command reference](https://www.postgresql.org/docs/current/sql-explain.html)": "Understand EXPLAIN options and the execution side effects of ANALYZE."
  "[PostgreSQL indexes](https://www.postgresql.org/docs/current/indexes.html)": "Choose indexes with attention to query benefits and maintenance overhead."
---

# Find and fix a slow PostgreSQL query in your app

Investigate one slow PostgreSQL query with representative test data, preserve its results, and compare execution plans.

Find the cause of a slow PostgreSQL query and make a measured improvement. Focus on a query that affects a page or API your users depend on.

Open or import your existing project and provide the affected request or query. You need a disposable database with representative synthetic data. Repository access and database configuration do not transfer with the prompt.

Your agent will compare execution plans and results, then prepare a scoped patch or migration for review. Measurements on test data identify candidates for improvement; they do not establish production performance.

## Agent prompt

```text
Find and fix one slow PostgreSQL query in my existing app without changing its intended results or access controls.

If the repository is unavailable, ask me to open or import it first. Read its instructions and inspect the database driver or ORM, PostgreSQL version, migrations, and test setup. Reuse these tools. Ask for the affected query or request and the expected result if the scope is unclear. If this app uses a different database, explain the mismatch before applying PostgreSQL-specific advice.

Use a disposable local or approved test database with synthetic data that represents relevant row counts, skew, and relationships. Confirm the target before running database commands. Never copy customer data or print connection secrets. If no test database is available, inspect code and prepare a reproducible fixture; mark runtime measurements as blocked.

Capture the generated SQL with parameter values redacted. Inspect its plan with EXPLAIN, then use EXPLAIN ANALYZE only against the disposable database after checking for side effects, because it executes the statement. Compare estimated and actual rows, repeated work, scans, and sorting. Separate database execution time from connection and application overhead. Repeat comparable measurements rather than relying on one run.

Implement a focused query rewrite or index migration supported by the evidence. Preserve parameterized values, tenant filters, ordering, pagination, null behavior, and transaction semantics. Avoid string interpolation for user input. Evaluate index storage and write overhead, migration locking, and a rollback path. Do not run migrations, analyze statements, or other mutations in production without explicit approval.

Extend existing tests at the query or request boundary. Compare representative results before and after, including empty results, duplicate sort values, pagination boundaries, and a different tenant where applicable. Exercise database failure handling and ensure the change does not convert errors into successful empty responses. Run the migration and rollback on disposable data when applicable.

Report the cause supported by evidence, patch, before-and-after plan and timing method, checks actually run, required setup, and rollout considerations. Clearly separate measured results from predictions that still need a representative environment.
```

## Related resources

- [Read PostgreSQL execution plans](https://www.postgresql.org/docs/current/using-explain.html): Interpret plan nodes, estimates, and actual execution statistics.

- [EXPLAIN command reference](https://www.postgresql.org/docs/current/sql-explain.html): Understand EXPLAIN options and the execution side effects of ANALYZE.

- [PostgreSQL indexes](https://www.postgresql.org/docs/current/indexes.html): Choose indexes with attention to query benefits and maintenance overhead.

## Try other prompts

- [Add regression tests for a critical user flow](/kb/prompts/add-critical-flow-regression-tests): Protect a key Next.js user journey with isolated tests for visible outcomes, failure recovery, and relevant access boundaries.

## Reference Architecture

Choose a stack and work through the decisions behind it, with curated documentation, guides, templates, and courses to help you build.

- [Agent stack](/kb/architecture/agents): Build and operate agents with models, tools, and durable workflows.
- [Web applications](/kb/architecture/web): Choose rendering, data, authentication, and caching approaches.
- [Backends](/kb/architecture/backends): Choose a runtime, connect services, and run background work.

[Browse all stacks](/kb/architecture)