@tamsensedev/runner 0.13.0 → 0.19.0

package/library/skills/postgres-performance/SKILL.md

@@ -1,97 +1,97 @@
----
-name: postgres-performance
-description: Use when writing or reviewing PostgreSQL queries, ORM data access, indexes, pagination, row-level security policies or connection handling, or when an endpoint or page is slow. Checks missing indexes, N+1 queries, OFFSET pagination, long transactions, racy upserts and pool misuse, and verifies fixes with EXPLAIN on a local database.
----
-
-# PostgreSQL performance
-
-Most slow Postgres code comes from a short list of mistakes: a query without a usable index, a query inside a loop, deep OFFSET pages, transactions held open across network calls, and connections opened per request. This skill finds them in a diff or in slow code and proves the fix with a query plan.
-
-The project's conventions win (naming, ORM style, how indexes are declared, which database version it targets). Schema changes that come out of this work, such as new indexes, must follow the `safe-database-changes` skill (build indexes without blocking writes, separate migration).
-
-## Safety
-
-- Never connect to a real, shared or production database to "check" a plan. Work on a throwaway local database (see `safe-database-changes` for how to get one) or reason from the code.
-- `EXPLAIN ANALYZE` executes the statement. For INSERT, UPDATE or DELETE, run it only on the throwaway database, inside `BEGIN; ... ROLLBACK;`.
-- Do not change server settings (`ALTER SYSTEM`, `max_connections`, pooler config) from a task run. Put recommended settings in the report.
-
-## Process
-
-### 1. Find the SQL that actually runs
-
-ORMs hide the real queries. Read the data-access code and, when you can run it locally, turn on query logging for one request or test: Prisma `log: ['query']`, Django `connection.queries` or `DEBUG` SQL logging, Rails log output, SQLAlchemy `echo=True`, Sequelize `logging`, TypeORM `logging: true`, Drizzle `logger: true`, or `log_statement = 'all'` on the throwaway database. Count queries per request, not just their speed.
-
-### 2. Check against the list, highest impact first
-
-| Priority | Look for | Rule |
-|---|---|---|
-| 1 | Filters, joins and sorts on columns with no matching index | [Indexes](references/rules.md#indexes) |
-| 1 | A query per item inside a loop, or lazy-loaded relations in a list | [N+1](references/rules.md#n1-queries) |
-| 1 | A new connection or client per request; a pool per module | [Connections](references/rules.md#connections) |
-| 1 | RLS policies calling a function per row, unindexed policy columns | [Row-level security](references/rules.md#row-level-security) |
-| 2 | Composite index in the wrong column order; foreign key without an index | [Indexes](references/rules.md#indexes) |
-| 2 | Deep `OFFSET` pagination | [Pagination](references/rules.md#pagination) |
-| 2 | Unbounded `SELECT` (no `LIMIT`) on growing tables; `SELECT *` on wide rows | [Query shape](references/rules.md#query-shape) |
-| 2 | Transactions held across HTTP calls or user input; check-then-insert | [Transactions and locks](references/rules.md#transactions-and-locks) |
-| 3 | Row-by-row inserts; `COUNT(*)` to test existence | [Query shape](references/rules.md#query-shape) |
-| 3 | Functions or casts on indexed columns (`lower(email) = ...`), leading-wildcard `LIKE` | [Indexes](references/rules.md#indexes), [Search](references/rules.md#search-and-jsonb) |
-| 3 | Worker queues that block each other | [Transactions and locks](references/rules.md#transactions-and-locks) |
-| 4 | Column types (int ids that will overflow, `timestamp` without zone, float money) | [Types](references/rules.md#types-and-keys) |
-
-Table size matters. An index on a 200-row lookup table is noise; a missing one on an events table is an outage. When you do not know the size, say what you assumed.
-
-### 3. Fix with the smallest change
-
-- Prefer fixing the query (batch the loop, keyset pagination, select fewer columns) over adding an index; prefer one composite index that serves several queries over several single-column ones.
-- Every index slows writes and takes space. Add one only for a query that runs often or on a large table, and check that an existing index does not already cover it (a composite index on `(a, b)` serves queries on `a` alone).
-- In ORMs, use the ORM's own tools first: eager loading (`include`, `select_related` / `prefetch_related`, `includes`, `joinedload` / `selectinload`), batch `findMany` with `in`, `createMany`, `bulk_create`, `insert_all`, upsert helpers.
-
-### 4. Verify
-
-On the throwaway database, with enough rows for the planner to behave like production (generate them with `generate_series`; a few hundred rows often get a sequential scan no matter what):
-
-```sql
-INSERT INTO orders (customer_id, status, created_at)
-SELECT (random() * 10000)::int, (ARRAY['pending','paid','shipped'])[1 + (random() * 2)::int],
-       now() - random() * interval '365 days'
-FROM generate_series(1, 200000);
-ANALYZE orders;
-
-EXPLAIN (ANALYZE, BUFFERS)
-SELECT id, total FROM orders WHERE customer_id = 42 ORDER BY created_at DESC LIMIT 20;
-```
-
-Read the plan:
-
-- `Seq Scan` on a big table with a selective filter, and a large `Rows Removed by Filter`: missing or unusable index.
-- Estimated rows far from actual rows: stale statistics (run `ANALYZE`) or a correlated filter.
-- `Sort` with `external merge`: sorting on disk; an index matching `ORDER BY` can remove the sort.
-- `Nested Loop` with a huge `loops` count on the inner side: missing index on the join column.
-- `Index Scan` followed by many heap fetches where a covering index would allow an `Index Only Scan`.
-
-Compare the plan before and after the fix. For N+1 fixes, count the queries for one request before and after, or assert the count in a test if the project has a helper for it.
-
-If you cannot run a database, say so and explain from the code why the fix helps.
-
-## Report
-
-For each finding: file and line, the query or ORM call, why it is slow (with the plan or the query count if you measured), the fix, and its cost (new index, extra memory). Separate what you changed from recommendations for operators (pool size, timeouts, server settings).
-
-## Common mistakes
-
-- Adding an index for every column in a WHERE clause, or duplicating an existing index's leading columns.
-- Indexing a low-selectivity column alone (a boolean, a status with three values) when a partial or composite index is what the query needs.
-- Wrapping the indexed column in a function or cast, so the index cannot be used.
-- Measuring on an empty table and concluding the plan is fine.
-- "Fixing" N+1 by caching instead of batching.
-- Raising pool size or `max_connections` to hide connection leaks.
-- Running `EXPLAIN ANALYZE` on a write statement against a real database.
-
-## Done when
-
-- Each slow pattern found is fixed or listed with a reason it was left.
-- New indexes go through a migration that follows `safe-database-changes`.
-- The fix is backed by a plan or query count from a throwaway database, or the report says it could not be measured.
-- Operator-level recommendations are in the report, not applied.
-
-Sources: supabase/agent-skills supabase-postgres-best-practices (MIT, commit c9be0e9). Changed: made Postgres-generic and condensed.
+---
+name: postgres-performance
+description: Use when writing or reviewing PostgreSQL queries, ORM data access, indexes, pagination, row-level security policies or connection handling, or when an endpoint or page is slow. Checks missing indexes, N+1 queries, OFFSET pagination, long transactions, racy upserts and pool misuse, and verifies fixes with EXPLAIN on a local database.
+---
+
+# PostgreSQL performance
+
+Most slow Postgres code comes from a short list of mistakes: a query without a usable index, a query inside a loop, deep OFFSET pages, transactions held open across network calls, and connections opened per request. This skill finds them in a diff or in slow code and proves the fix with a query plan.
+
+The project's conventions win (naming, ORM style, how indexes are declared, which database version it targets). Schema changes that come out of this work, such as new indexes, must follow the `safe-database-changes` skill (build indexes without blocking writes, separate migration).
+
+## Safety
+
+- Never connect to a real, shared or production database to "check" a plan. Work on a throwaway local database (see `safe-database-changes` for how to get one) or reason from the code.
+- `EXPLAIN ANALYZE` executes the statement. For INSERT, UPDATE or DELETE, run it only on the throwaway database, inside `BEGIN; ... ROLLBACK;`.
+- Do not change server settings (`ALTER SYSTEM`, `max_connections`, pooler config) from a task run. Put recommended settings in the report.
+
+## Process
+
+### 1. Find the SQL that actually runs
+
+ORMs hide the real queries. Read the data-access code and, when you can run it locally, turn on query logging for one request or test: Prisma `log: ['query']`, Django `connection.queries` or `DEBUG` SQL logging, Rails log output, SQLAlchemy `echo=True`, Sequelize `logging`, TypeORM `logging: true`, Drizzle `logger: true`, or `log_statement = 'all'` on the throwaway database. Count queries per request, not just their speed.
+
+### 2. Check against the list, highest impact first
+
+| Priority | Look for | Rule |
+|---|---|---|
+| 1 | Filters, joins and sorts on columns with no matching index | [Indexes](references/rules.md#indexes) |
+| 1 | A query per item inside a loop, or lazy-loaded relations in a list | [N+1](references/rules.md#n1-queries) |
+| 1 | A new connection or client per request; a pool per module | [Connections](references/rules.md#connections) |
+| 1 | RLS policies calling a function per row, unindexed policy columns | [Row-level security](references/rules.md#row-level-security) |
+| 2 | Composite index in the wrong column order; foreign key without an index | [Indexes](references/rules.md#indexes) |
+| 2 | Deep `OFFSET` pagination | [Pagination](references/rules.md#pagination) |
+| 2 | Unbounded `SELECT` (no `LIMIT`) on growing tables; `SELECT *` on wide rows | [Query shape](references/rules.md#query-shape) |
+| 2 | Transactions held across HTTP calls or user input; check-then-insert | [Transactions and locks](references/rules.md#transactions-and-locks) |
+| 3 | Row-by-row inserts; `COUNT(*)` to test existence | [Query shape](references/rules.md#query-shape) |
+| 3 | Functions or casts on indexed columns (`lower(email) = ...`), leading-wildcard `LIKE` | [Indexes](references/rules.md#indexes), [Search](references/rules.md#search-and-jsonb) |
+| 3 | Worker queues that block each other | [Transactions and locks](references/rules.md#transactions-and-locks) |
+| 4 | Column types (int ids that will overflow, `timestamp` without zone, float money) | [Types](references/rules.md#types-and-keys) |
+
+Table size matters. An index on a 200-row lookup table is noise; a missing one on an events table is an outage. When you do not know the size, say what you assumed.
+
+### 3. Fix with the smallest change
+
+- Prefer fixing the query (batch the loop, keyset pagination, select fewer columns) over adding an index; prefer one composite index that serves several queries over several single-column ones.
+- Every index slows writes and takes space. Add one only for a query that runs often or on a large table, and check that an existing index does not already cover it (a composite index on `(a, b)` serves queries on `a` alone).
+- In ORMs, use the ORM's own tools first: eager loading (`include`, `select_related` / `prefetch_related`, `includes`, `joinedload` / `selectinload`), batch `findMany` with `in`, `createMany`, `bulk_create`, `insert_all`, upsert helpers.
+
+### 4. Verify
+
+On the throwaway database, with enough rows for the planner to behave like production (generate them with `generate_series`; a few hundred rows often get a sequential scan no matter what):
+
+```sql
+INSERT INTO orders (customer_id, status, created_at)
+SELECT (random() * 10000)::int, (ARRAY['pending','paid','shipped'])[1 + (random() * 2)::int],
+       now() - random() * interval '365 days'
+FROM generate_series(1, 200000);
+ANALYZE orders;
+
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT id, total FROM orders WHERE customer_id = 42 ORDER BY created_at DESC LIMIT 20;
+```
+
+Read the plan:
+
+- `Seq Scan` on a big table with a selective filter, and a large `Rows Removed by Filter`: missing or unusable index.
+- Estimated rows far from actual rows: stale statistics (run `ANALYZE`) or a correlated filter.
+- `Sort` with `external merge`: sorting on disk; an index matching `ORDER BY` can remove the sort.
+- `Nested Loop` with a huge `loops` count on the inner side: missing index on the join column.
+- `Index Scan` followed by many heap fetches where a covering index would allow an `Index Only Scan`.
+
+Compare the plan before and after the fix. For N+1 fixes, count the queries for one request before and after, or assert the count in a test if the project has a helper for it.
+
+If you cannot run a database, say so and explain from the code why the fix helps.
+
+## Report
+
+For each finding: file and line, the query or ORM call, why it is slow (with the plan or the query count if you measured), the fix, and its cost (new index, extra memory). Separate what you changed from recommendations for operators (pool size, timeouts, server settings).
+
+## Common mistakes
+
+- Adding an index for every column in a WHERE clause, or duplicating an existing index's leading columns.
+- Indexing a low-selectivity column alone (a boolean, a status with three values) when a partial or composite index is what the query needs.
+- Wrapping the indexed column in a function or cast, so the index cannot be used.
+- Measuring on an empty table and concluding the plan is fine.
+- "Fixing" N+1 by caching instead of batching.
+- Raising pool size or `max_connections` to hide connection leaks.
+- Running `EXPLAIN ANALYZE` on a write statement against a real database.
+
+## Done when
+
+- Each slow pattern found is fixed or listed with a reason it was left.
+- New indexes go through a migration that follows `safe-database-changes`.
+- The fix is backed by a plan or query count from a throwaway database, or the report says it could not be measured.
+- Operator-level recommendations are in the report, not applied.
+
+Sources: supabase/agent-skills supabase-postgres-best-practices (MIT, commit c9be0e9). Changed: made Postgres-generic and condensed.