@tamsensedev/runner 0.13.0 → 0.19.0

package/library/skills/postgres-performance/references/rules.md

@@ -1,265 +1,265 @@
-# PostgreSQL rules: wrong and right
-
-Read the section that matches what you found in step 2 of the skill. Each rule shows the slow form and the fix. Table and column names are examples.
-
-## Indexes
-
-**Index the columns you filter and join on.** Without one, every lookup scans the whole table.
-
-```sql
--- wrong: no index on customer_id, so Seq Scan on a large table
-SELECT * FROM orders WHERE customer_id = 123;
--- right
-CREATE INDEX orders_customer_id_idx ON orders (customer_id);
-```
-
-**Composite indexes: equality columns first, range or sort columns last.** An index on `(a, b)` serves `a = ?` and `a = ? AND b > ?`, but not `b > ?` alone.
-
-```sql
--- wrong: two single-column indexes, combined with a slower bitmap scan
-CREATE INDEX ON orders (status);
-CREATE INDEX ON orders (created_at);
--- right, for WHERE status = 'pending' AND created_at > ... ORDER BY created_at
-CREATE INDEX orders_status_created_idx ON orders (status, created_at);
-```
-
-**Index foreign key columns.** Postgres indexes the referenced primary key, not the referencing column. Without it, joins and `ON DELETE CASCADE` scan the child table.
-
-```sql
--- find foreign keys whose columns lead no index
-SELECT c.conrelid::regclass AS table_name, a.attname AS column_name
-FROM pg_constraint c
-JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY (c.conkey)
-WHERE c.contype = 'f'
-  AND NOT EXISTS (
-    SELECT 1 FROM pg_index i
-    WHERE i.indrelid = c.conrelid AND i.indkey[0] = a.attnum
-  );
-```
-
-**Partial indexes for queries that always filter the same way.** Smaller and faster than a full index.
-
-```sql
--- queries always add deleted_at IS NULL
-CREATE INDEX users_active_email_idx ON users (email) WHERE deleted_at IS NULL;
-```
-
-**Covering indexes to skip the table.** `INCLUDE` columns you select but do not filter on, so the plan can use an Index Only Scan.
-
-```sql
-CREATE INDEX orders_status_idx ON orders (status) INCLUDE (customer_id, total);
-SELECT status, customer_id, total FROM orders WHERE status = 'shipped';
-```
-
-**Match the index to the expression.** A function or cast on the column hides it from a plain index.
-
-```sql
--- wrong: index on email is not used
-SELECT * FROM users WHERE lower(email) = lower($1);
--- right: expression index (or store a normalized column)
-CREATE INDEX users_email_lower_idx ON users (lower(email));
-```
-
-Also watch implicit casts: comparing a `bigint` column with a `text` parameter, or a `timestamptz` column with a date string in another type, can prevent index use.
-
-**Pick the index type for the operator.**
-
-| Data and operator | Index |
-|---|---|
-| `=`, `<`, `>`, `BETWEEN`, `IN`, `ORDER BY` | B-tree (default) |
-| JSONB containment `@>`, `?`, arrays, full-text `@@` | GIN |
-| Ranges, geometry, nearest neighbour | GiST |
-| Huge append-only tables queried by time ranges | BRIN |
-
-**Do not over-index.** Each index costs write time, disk and vacuum work. Before adding one, list existing indexes (`\d table` or `pg_indexes`) and check whether one already has the needed leading columns. In reviews, flag new indexes that duplicate an existing prefix.
-
-## N+1 queries
-
-One query for the list, then one per item:
-
-```sql
--- wrong: 1 + N round trips
-SELECT id FROM users WHERE active;
-SELECT * FROM orders WHERE user_id = 1;
-SELECT * FROM orders WHERE user_id = 2;
--- ...
--- right: one query with an array parameter, or a join
-SELECT * FROM orders WHERE user_id = ANY ($1::bigint[]);
-```
-
-In ORMs this hides behind lazy relations in a loop or a template. Use eager loading (`include`, `with`, `select_related` / `prefetch_related`, `includes` / `preload`, `joinedload` / `selectinload`) or collect ids and fetch once. GraphQL resolvers need a batching loader. Count queries per request to confirm.
-
-## Pagination
-
-OFFSET reads and discards every skipped row, so deep pages get slower and rows shift between pages when data changes.
-
-```sql
--- wrong
-SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 19980;
--- right: keyset (cursor) pagination
-SELECT * FROM products WHERE id > $last_id ORDER BY id LIMIT 20;
--- sorting by several columns: the cursor holds all of them, the index matches
-SELECT * FROM products
-WHERE (created_at, id) > ($last_created_at, $last_id)
-ORDER BY created_at, id LIMIT 20;
-```
-
-OFFSET is acceptable for small, bounded lists (admin tables with a few pages). Exact total counts on large tables are expensive too; consider "has more" instead of a full `COUNT(*)`.
-
-## Query shape
-
-**Bound every list query.** A `SELECT` without `LIMIT` on a table that grows will eventually return too much. Select only the columns you need, especially with wide text or JSON columns.
-
-**Test existence with EXISTS, not COUNT.**
-
-```sql
--- wrong
-SELECT count(*) FROM orders WHERE user_id = $1;   -- then check > 0
--- right
-SELECT EXISTS (SELECT 1 FROM orders WHERE user_id = $1);
-```
-
-**Batch inserts.** One statement per row means one round trip per row.
-
-```sql
--- wrong: a loop of single-row INSERTs
--- right: multi-row VALUES (hundreds to a few thousand rows per statement)
-INSERT INTO events (user_id, action) VALUES ($1, $2), ($3, $4), ($5, $6);
--- bulk loads: COPY, or the driver's copy or bulk helper
-```
-
-**Upsert atomically.** Select-then-insert races under concurrency.
-
-```sql
--- wrong: two requests both see "not found", both insert, one fails
-SELECT 1 FROM settings WHERE user_id = $1 AND key = $2;
-INSERT INTO settings (user_id, key, value) VALUES ($1, $2, $3);
--- right (needs a unique constraint on user_id, key)
-INSERT INTO settings (user_id, key, value) VALUES ($1, $2, $3)
-ON CONFLICT (user_id, key) DO UPDATE SET value = excluded.value, updated_at = now();
-```
-
-**Beware `NOT IN (subquery)`** when the subquery can return NULL: it returns no rows. Use `NOT EXISTS`.
-
-## Transactions and locks
-
-**Keep transactions short.** Never hold a transaction (and its row locks) open across an HTTP call, a queue publish or user input.
-
-```sql
--- wrong
-BEGIN;
-SELECT * FROM orders WHERE id = 1 FOR UPDATE;
--- app calls the payment API for 3 seconds while the row stays locked
-UPDATE orders SET status = 'paid' WHERE id = 1;
-COMMIT;
--- right: call the API first, then a short conditional update
-UPDATE orders SET status = 'paid', payment_id = $1
-WHERE id = $2 AND status = 'pending'
-RETURNING id;
-```
-
-**Lock rows in a consistent order** to avoid deadlocks, for example `SELECT ... WHERE id IN (...) ORDER BY id FOR UPDATE` before updating several rows, or do it in one UPDATE statement.
-
-**Job queues: `FOR UPDATE SKIP LOCKED`.** Workers then take different rows instead of waiting on each other.
-
-```sql
-UPDATE jobs SET status = 'running', started_at = now(), worker_id = $1
-WHERE id = (
-  SELECT id FROM jobs WHERE status = 'pending'
-  ORDER BY created_at LIMIT 1
-  FOR UPDATE SKIP LOCKED
-)
-RETURNING *;
-```
-
-**Advisory locks** coordinate app-level work (one cron runner at a time) without dummy lock rows: `pg_try_advisory_xact_lock(key)` inside a transaction releases automatically on commit. Session-level advisory locks behave badly with transaction-mode poolers; prefer the transaction-level form.
-
-**Statement timeouts.** A `statement_timeout` (per role, per session or `SET LOCAL` per transaction) stops runaway queries. Recommend values in the report; do not change server settings.
-
-## Connections
-
-**Use one pool per process, created once.** A new client per request exhausts the server's connections under load, and each Postgres connection costs memory.
-
-```js
-// wrong: a client per request
-app.get('/orders', async () => { const c = new Client(url); await c.connect(); /* ... */ });
-// right: module-level pool (or the ORM's single client), reused
-const pool = new Pool({ connectionString: url, max: 10 });
-```
-
-In serverless and edge runtimes, keep the client outside the handler and use the platform's pooler or a transaction-mode pooler such as PgBouncer.
-
-**Transaction-mode poolers do not keep session state.** Named prepared statements, `SET` without `LOCAL`, temp tables, `LISTEN` and session advisory locks can break, because the next transaction may run on another server connection. Use the driver's or ORM's setting for pooled connections (many have a flag to disable named prepared statements) or a session-mode connection for those features.
-
-**Always release connections**, including on errors (`try/finally`, the pool's helper that releases for you). A leak looks like "too many connections" after a while; raising limits only delays it.
-
-Server-side settings (`max_connections`, `idle_in_transaction_session_timeout`, pool sizes) belong in the report as recommendations.
-
-## Row-level security
-
-**Call per-request functions once, not per row.** Wrap them in a scalar subquery so the planner evaluates them once.
-
-```sql
--- wrong: current_setting() evaluated for every row
-CREATE POLICY orders_owner ON orders
-  USING (user_id = current_setting('app.user_id')::bigint);
--- right
-CREATE POLICY orders_owner ON orders
-  USING (user_id = (SELECT current_setting('app.user_id')::bigint));
-```
-
-The same applies to platform helpers that return the current user (for example `auth.uid()` on Supabase).
-
-**Index every column the policy filters on** (`user_id`, `tenant_id`, `team_id`). The policy is an extra WHERE clause on every query.
-
-**Complex membership checks:** a `SECURITY DEFINER` function can do an indexed lookup without nested policy evaluation, but it bypasses RLS on the tables it reads. Keep it in a schema the API does not expose, set `search_path = ''` and schema-qualify names, check the caller's identity inside it, and keep `EXECUTE` limited to the roles whose policies call it. Flag any new SECURITY DEFINER function for the `security-review` skill.
-
-Remember that RLS does not apply to table owners unless `FORCE ROW LEVEL SECURITY` is set, and that the application role should not be a superuser.
-
-## Types and keys
-
-| Use | Instead of | Why |
-|---|---|---|
-| `bigint` identity (`GENERATED ALWAYS AS IDENTITY`) | `int`, `serial` | `int` ids overflow at about 2.1 billion |
-| Time-ordered UUIDs (v7) when ids must be distributed or public | Random UUID v4 as the primary key of a big table | Random keys scatter inserts across the index |
-| `timestamptz` | `timestamp` | Stores an absolute moment |
-| `numeric(p, s)` or integer minor units for money | `float`, `real` | Exact arithmetic |
-| `text` (plus a CHECK if a limit matters) | `varchar(n)` chosen arbitrarily | Same performance, fewer migrations |
-| `boolean`, enums or CHECK constraints | Strings for flags and states | Smaller, validated |
-
-UUID v7 is built in from PostgreSQL 18 (`uuidv7()`); older versions need an extension or ids generated by the application. Follow the project's existing key strategy unless the task is about changing it.
-
-Very large time-series tables (hundreds of millions of rows) where old data is dropped in bulk are candidates for range partitioning; this is a design change, so recommend it rather than doing it inside an unrelated task.
-
-## Search and JSONB
-
-**Leading-wildcard LIKE cannot use a B-tree index.**
-
-```sql
--- wrong on large tables
-SELECT * FROM articles WHERE body ILIKE '%postgres%';
--- right for word search: full-text search with a GIN index
-ALTER TABLE articles ADD COLUMN search tsvector
-  GENERATED ALWAYS AS (to_tsvector('english', coalesce(title, '') || ' ' || coalesce(body, ''))) STORED;
-CREATE INDEX articles_search_idx ON articles USING gin (search);
-SELECT * FROM articles WHERE search @@ websearch_to_tsquery('english', 'postgres performance');
-```
-
-For substring matching, a trigram index (`pg_trgm` extension, `gin (col gin_trgm_ops)`) supports `ILIKE '%...%'`. Adding an extension is an operator decision: mention it if the project does not already use it. Adding a stored generated column rewrites the table: follow `safe-database-changes`.
-
-**JSONB:** a GIN index serves containment (`@>`); `jsonb_path_ops` is smaller if you only use `@>`. For lookups on one key, an expression index is better:
-
-```sql
-CREATE INDEX products_brand_idx ON products ((attributes ->> 'brand'));
-SELECT * FROM products WHERE attributes ->> 'brand' = 'Acme';
-```
-
-If the same JSON keys are queried everywhere, they probably deserve real columns.
-
-## Diagnostics
-
-- `EXPLAIN (ANALYZE, BUFFERS)` on the throwaway database: see the skill for how to read it.
-- `pg_stat_statements`, if the project or its operators use it, ranks queries by total and mean time; ask for its output in the report rather than querying a production database yourself.
-- After large data changes, `ANALYZE table` refreshes planner statistics; bad estimates (estimated rows far from actual) often mean stale statistics.
-
-Adapted from supabase/agent-skills `skills/supabase-postgres-best-practices` (MIT, commit c9be0e931b7930f7d02126d04774d904c381e7d7, Copyright (c) 2026 Supabase). Changed: made Postgres-generic (Supabase ports, roles and dashboards removed), condensed about 34 rule files into one page, fixed the SECURITY DEFINER example that revoked EXECUTE from the roles its policy needs, replaced server-setting changes with report recommendations, added expression indexes, EXISTS, NOT IN, trigram and ORM notes.
+# PostgreSQL rules: wrong and right
+
+Read the section that matches what you found in step 2 of the skill. Each rule shows the slow form and the fix. Table and column names are examples.
+
+## Indexes
+
+**Index the columns you filter and join on.** Without one, every lookup scans the whole table.
+
+```sql
+-- wrong: no index on customer_id, so Seq Scan on a large table
+SELECT * FROM orders WHERE customer_id = 123;
+-- right
+CREATE INDEX orders_customer_id_idx ON orders (customer_id);
+```
+
+**Composite indexes: equality columns first, range or sort columns last.** An index on `(a, b)` serves `a = ?` and `a = ? AND b > ?`, but not `b > ?` alone.
+
+```sql
+-- wrong: two single-column indexes, combined with a slower bitmap scan
+CREATE INDEX ON orders (status);
+CREATE INDEX ON orders (created_at);
+-- right, for WHERE status = 'pending' AND created_at > ... ORDER BY created_at
+CREATE INDEX orders_status_created_idx ON orders (status, created_at);
+```
+
+**Index foreign key columns.** Postgres indexes the referenced primary key, not the referencing column. Without it, joins and `ON DELETE CASCADE` scan the child table.
+
+```sql
+-- find foreign keys whose columns lead no index
+SELECT c.conrelid::regclass AS table_name, a.attname AS column_name
+FROM pg_constraint c
+JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY (c.conkey)
+WHERE c.contype = 'f'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_index i
+    WHERE i.indrelid = c.conrelid AND i.indkey[0] = a.attnum
+  );
+```
+
+**Partial indexes for queries that always filter the same way.** Smaller and faster than a full index.
+
+```sql
+-- queries always add deleted_at IS NULL
+CREATE INDEX users_active_email_idx ON users (email) WHERE deleted_at IS NULL;
+```
+
+**Covering indexes to skip the table.** `INCLUDE` columns you select but do not filter on, so the plan can use an Index Only Scan.
+
+```sql
+CREATE INDEX orders_status_idx ON orders (status) INCLUDE (customer_id, total);
+SELECT status, customer_id, total FROM orders WHERE status = 'shipped';
+```
+
+**Match the index to the expression.** A function or cast on the column hides it from a plain index.
+
+```sql
+-- wrong: index on email is not used
+SELECT * FROM users WHERE lower(email) = lower($1);
+-- right: expression index (or store a normalized column)
+CREATE INDEX users_email_lower_idx ON users (lower(email));
+```
+
+Also watch implicit casts: comparing a `bigint` column with a `text` parameter, or a `timestamptz` column with a date string in another type, can prevent index use.
+
+**Pick the index type for the operator.**
+
+| Data and operator | Index |
+|---|---|
+| `=`, `<`, `>`, `BETWEEN`, `IN`, `ORDER BY` | B-tree (default) |
+| JSONB containment `@>`, `?`, arrays, full-text `@@` | GIN |
+| Ranges, geometry, nearest neighbour | GiST |
+| Huge append-only tables queried by time ranges | BRIN |
+
+**Do not over-index.** Each index costs write time, disk and vacuum work. Before adding one, list existing indexes (`\d table` or `pg_indexes`) and check whether one already has the needed leading columns. In reviews, flag new indexes that duplicate an existing prefix.
+
+## N+1 queries
+
+One query for the list, then one per item:
+
+```sql
+-- wrong: 1 + N round trips
+SELECT id FROM users WHERE active;
+SELECT * FROM orders WHERE user_id = 1;
+SELECT * FROM orders WHERE user_id = 2;
+-- ...
+-- right: one query with an array parameter, or a join
+SELECT * FROM orders WHERE user_id = ANY ($1::bigint[]);
+```
+
+In ORMs this hides behind lazy relations in a loop or a template. Use eager loading (`include`, `with`, `select_related` / `prefetch_related`, `includes` / `preload`, `joinedload` / `selectinload`) or collect ids and fetch once. GraphQL resolvers need a batching loader. Count queries per request to confirm.
+
+## Pagination
+
+OFFSET reads and discards every skipped row, so deep pages get slower and rows shift between pages when data changes.
+
+```sql
+-- wrong
+SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 19980;
+-- right: keyset (cursor) pagination
+SELECT * FROM products WHERE id > $last_id ORDER BY id LIMIT 20;
+-- sorting by several columns: the cursor holds all of them, the index matches
+SELECT * FROM products
+WHERE (created_at, id) > ($last_created_at, $last_id)
+ORDER BY created_at, id LIMIT 20;
+```
+
+OFFSET is acceptable for small, bounded lists (admin tables with a few pages). Exact total counts on large tables are expensive too; consider "has more" instead of a full `COUNT(*)`.
+
+## Query shape
+
+**Bound every list query.** A `SELECT` without `LIMIT` on a table that grows will eventually return too much. Select only the columns you need, especially with wide text or JSON columns.
+
+**Test existence with EXISTS, not COUNT.**
+
+```sql
+-- wrong
+SELECT count(*) FROM orders WHERE user_id = $1;   -- then check > 0
+-- right
+SELECT EXISTS (SELECT 1 FROM orders WHERE user_id = $1);
+```
+
+**Batch inserts.** One statement per row means one round trip per row.
+
+```sql
+-- wrong: a loop of single-row INSERTs
+-- right: multi-row VALUES (hundreds to a few thousand rows per statement)
+INSERT INTO events (user_id, action) VALUES ($1, $2), ($3, $4), ($5, $6);
+-- bulk loads: COPY, or the driver's copy or bulk helper
+```
+
+**Upsert atomically.** Select-then-insert races under concurrency.
+
+```sql
+-- wrong: two requests both see "not found", both insert, one fails
+SELECT 1 FROM settings WHERE user_id = $1 AND key = $2;
+INSERT INTO settings (user_id, key, value) VALUES ($1, $2, $3);
+-- right (needs a unique constraint on user_id, key)
+INSERT INTO settings (user_id, key, value) VALUES ($1, $2, $3)
+ON CONFLICT (user_id, key) DO UPDATE SET value = excluded.value, updated_at = now();
+```
+
+**Beware `NOT IN (subquery)`** when the subquery can return NULL: it returns no rows. Use `NOT EXISTS`.
+
+## Transactions and locks
+
+**Keep transactions short.** Never hold a transaction (and its row locks) open across an HTTP call, a queue publish or user input.
+
+```sql
+-- wrong
+BEGIN;
+SELECT * FROM orders WHERE id = 1 FOR UPDATE;
+-- app calls the payment API for 3 seconds while the row stays locked
+UPDATE orders SET status = 'paid' WHERE id = 1;
+COMMIT;
+-- right: call the API first, then a short conditional update
+UPDATE orders SET status = 'paid', payment_id = $1
+WHERE id = $2 AND status = 'pending'
+RETURNING id;
+```
+
+**Lock rows in a consistent order** to avoid deadlocks, for example `SELECT ... WHERE id IN (...) ORDER BY id FOR UPDATE` before updating several rows, or do it in one UPDATE statement.
+
+**Job queues: `FOR UPDATE SKIP LOCKED`.** Workers then take different rows instead of waiting on each other.
+
+```sql
+UPDATE jobs SET status = 'running', started_at = now(), worker_id = $1
+WHERE id = (
+  SELECT id FROM jobs WHERE status = 'pending'
+  ORDER BY created_at LIMIT 1
+  FOR UPDATE SKIP LOCKED
+)
+RETURNING *;
+```
+
+**Advisory locks** coordinate app-level work (one cron runner at a time) without dummy lock rows: `pg_try_advisory_xact_lock(key)` inside a transaction releases automatically on commit. Session-level advisory locks behave badly with transaction-mode poolers; prefer the transaction-level form.
+
+**Statement timeouts.** A `statement_timeout` (per role, per session or `SET LOCAL` per transaction) stops runaway queries. Recommend values in the report; do not change server settings.
+
+## Connections
+
+**Use one pool per process, created once.** A new client per request exhausts the server's connections under load, and each Postgres connection costs memory.
+
+```js
+// wrong: a client per request
+app.get('/orders', async () => { const c = new Client(url); await c.connect(); /* ... */ });
+// right: module-level pool (or the ORM's single client), reused
+const pool = new Pool({ connectionString: url, max: 10 });
+```
+
+In serverless and edge runtimes, keep the client outside the handler and use the platform's pooler or a transaction-mode pooler such as PgBouncer.
+
+**Transaction-mode poolers do not keep session state.** Named prepared statements, `SET` without `LOCAL`, temp tables, `LISTEN` and session advisory locks can break, because the next transaction may run on another server connection. Use the driver's or ORM's setting for pooled connections (many have a flag to disable named prepared statements) or a session-mode connection for those features.
+
+**Always release connections**, including on errors (`try/finally`, the pool's helper that releases for you). A leak looks like "too many connections" after a while; raising limits only delays it.
+
+Server-side settings (`max_connections`, `idle_in_transaction_session_timeout`, pool sizes) belong in the report as recommendations.
+
+## Row-level security
+
+**Call per-request functions once, not per row.** Wrap them in a scalar subquery so the planner evaluates them once.
+
+```sql
+-- wrong: current_setting() evaluated for every row
+CREATE POLICY orders_owner ON orders
+  USING (user_id = current_setting('app.user_id')::bigint);
+-- right
+CREATE POLICY orders_owner ON orders
+  USING (user_id = (SELECT current_setting('app.user_id')::bigint));
+```
+
+The same applies to platform helpers that return the current user (for example `auth.uid()` on Supabase).
+
+**Index every column the policy filters on** (`user_id`, `tenant_id`, `team_id`). The policy is an extra WHERE clause on every query.
+
+**Complex membership checks:** a `SECURITY DEFINER` function can do an indexed lookup without nested policy evaluation, but it bypasses RLS on the tables it reads. Keep it in a schema the API does not expose, set `search_path = ''` and schema-qualify names, check the caller's identity inside it, and keep `EXECUTE` limited to the roles whose policies call it. Flag any new SECURITY DEFINER function for the `security-review` skill.
+
+Remember that RLS does not apply to table owners unless `FORCE ROW LEVEL SECURITY` is set, and that the application role should not be a superuser.
+
+## Types and keys
+
+| Use | Instead of | Why |
+|---|---|---|
+| `bigint` identity (`GENERATED ALWAYS AS IDENTITY`) | `int`, `serial` | `int` ids overflow at about 2.1 billion |
+| Time-ordered UUIDs (v7) when ids must be distributed or public | Random UUID v4 as the primary key of a big table | Random keys scatter inserts across the index |
+| `timestamptz` | `timestamp` | Stores an absolute moment |
+| `numeric(p, s)` or integer minor units for money | `float`, `real` | Exact arithmetic |
+| `text` (plus a CHECK if a limit matters) | `varchar(n)` chosen arbitrarily | Same performance, fewer migrations |
+| `boolean`, enums or CHECK constraints | Strings for flags and states | Smaller, validated |
+
+UUID v7 is built in from PostgreSQL 18 (`uuidv7()`); older versions need an extension or ids generated by the application. Follow the project's existing key strategy unless the task is about changing it.
+
+Very large time-series tables (hundreds of millions of rows) where old data is dropped in bulk are candidates for range partitioning; this is a design change, so recommend it rather than doing it inside an unrelated task.
+
+## Search and JSONB
+
+**Leading-wildcard LIKE cannot use a B-tree index.**
+
+```sql
+-- wrong on large tables
+SELECT * FROM articles WHERE body ILIKE '%postgres%';
+-- right for word search: full-text search with a GIN index
+ALTER TABLE articles ADD COLUMN search tsvector
+  GENERATED ALWAYS AS (to_tsvector('english', coalesce(title, '') || ' ' || coalesce(body, ''))) STORED;
+CREATE INDEX articles_search_idx ON articles USING gin (search);
+SELECT * FROM articles WHERE search @@ websearch_to_tsquery('english', 'postgres performance');
+```
+
+For substring matching, a trigram index (`pg_trgm` extension, `gin (col gin_trgm_ops)`) supports `ILIKE '%...%'`. Adding an extension is an operator decision: mention it if the project does not already use it. Adding a stored generated column rewrites the table: follow `safe-database-changes`.
+
+**JSONB:** a GIN index serves containment (`@>`); `jsonb_path_ops` is smaller if you only use `@>`. For lookups on one key, an expression index is better:
+
+```sql
+CREATE INDEX products_brand_idx ON products ((attributes ->> 'brand'));
+SELECT * FROM products WHERE attributes ->> 'brand' = 'Acme';
+```
+
+If the same JSON keys are queried everywhere, they probably deserve real columns.
+
+## Diagnostics
+
+- `EXPLAIN (ANALYZE, BUFFERS)` on the throwaway database: see the skill for how to read it.
+- `pg_stat_statements`, if the project or its operators use it, ranks queries by total and mean time; ask for its output in the report rather than querying a production database yourself.
+- After large data changes, `ANALYZE table` refreshes planner statistics; bad estimates (estimated rows far from actual) often mean stale statistics.
+
+Adapted from supabase/agent-skills `skills/supabase-postgres-best-practices` (MIT, commit c9be0e931b7930f7d02126d04774d904c381e7d7, Copyright (c) 2026 Supabase). Changed: made Postgres-generic (Supabase ports, roles and dashboards removed), condensed about 34 rule files into one page, fixed the SECURITY DEFINER example that revoked EXECUTE from the roles its policy needs, replaced server-setting changes with report recommendations, added expression indexes, EXISTS, NOT IN, trigram and ORM notes.