@gallopsystems/agent-skills 1.32.0 → 1.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +11 -0
  2. package/package.json +1 -1
  3. package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md +17 -3
  4. package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md +91 -0
  5. package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md +155 -0
  6. package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md +13 -0
  7. package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md +50 -0
  8. package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md +65 -0
  9. package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md +2 -0
  10. package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +10 -0
  11. package/plugins/nitro-testing/skills/nitro-testing/proving-the-claim.md +240 -0
  12. package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md +1 -0
  13. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md +23 -12
  14. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md +50 -0
  15. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md +34 -3
  16. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts +2 -2
  17. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md +57 -0
  18. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md +2 -0
  19. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md +100 -1
  20. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/sse.md +1 -1
  21. package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md +120 -14
  22. package/plugins/pr-review/.claude-plugin/plugin.json +8 -0
  23. package/plugins/pr-review/skills/pr-review/SKILL.md +68 -0
  24. package/plugins/pr-review/skills/pr-review/brief-prompt.md +33 -0
  25. package/plugins/pr-review/skills/pr-review/focus-areas.md +63 -0
  26. package/plugins/pr-review/skills/pr-review/judge.md +29 -0
  27. package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +29 -0
  28. package/plugins/vue-nuxt/skills/vue-nuxt/async-state.md +229 -0
  29. package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md +45 -0
  30. package/plugins/vue-nuxt/skills/vue-nuxt/editing-forms.md +137 -0
  31. package/plugins/vue-nuxt/skills/vue-nuxt/formatters.md +8 -0
  32. package/plugins/vue-nuxt/skills/vue-nuxt/slots.md +16 -0
  33. package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +52 -0
  34. package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +2 -1
  35. package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +5 -1
package/README.md CHANGED
@@ -22,6 +22,7 @@ Then install the skills you want:
22
22
  /plugin install frontend-design@gallop-systems-agent-skills
23
23
  /plugin install gallop-ui@gallop-systems-agent-skills
24
24
  /plugin install generate-documentation@gallop-systems-agent-skills
25
+ /plugin install pr-review@gallop-systems-agent-skills
25
26
  ```
26
27
 
27
28
  ## Updating
@@ -193,6 +194,16 @@ Covers:
193
194
  - `bin/shots.mjs` Playwright helpers (sign-in, still captures, highlight rings, region and element shots) and `bin/render.mjs` (HTML to PDF, plus a contact sheet for reviewing page breaks)
194
195
  - A guide template, writing rules for non-technical readers, and per-format rules
195
196
 
197
+ ### pr-review
198
+
199
+ Review a branch or pull request for defects before a human sees it.
200
+
201
+ Covers:
202
+ - Building a context brief with a cheap model: the change's goal, callers, sibling code and stated claims
203
+ - Running `codex review` with the brief
204
+ - Judging every finding against the code (five keep-rules) before fixing or reporting it
205
+ - Deep mode: one focused reviewer per concern (tests, docs, migrations, UI state, races, agreeing paths, inputs, access)
206
+
196
207
  ## Contributing a Lesson Back
197
208
 
198
209
  Every skill ends with a **Contributing Back** section: when Claude works through
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gallopsystems/agent-skills",
3
- "version": "1.32.0",
3
+ "version": "1.33.0",
4
4
  "description": "Gallop Systems agent skills, symlinked into .claude/skills (Claude Code) and .agents/skills (Codex) on install.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -20,13 +20,14 @@ Use this skill when:
20
20
  This skill is split into topic guides — read the [Core Principles](#core-principles) below, then open the guide matching what you're doing:
21
21
 
22
22
  - [expression-builder.md](references/expression-builder.md) — the ExpressionBuilder (`eb`) foundation, `eb.val` vs `eb.lit`, standalone `eb`, conditional expression arrays, string concatenation
23
- - [query-patterns.md](references/query-patterns.md) — SELECT, WHERE clauses, JOINs (incl. callback format), aggregations, ORDER BY, CTEs, JSON aggregation
23
+ - [query-patterns.md](references/query-patterns.md) — SELECT, WHERE clauses, JOINs (incl. callback format), aggregations, ORDER BY, CTEs, JSON aggregation, where LIMIT goes (cap last; count and list from one base query), deterministic ordering
24
24
  - [json-jsonb-arrays.md](references/json-jsonb-arrays.md) — JSONB columns, array columns, querying arrays/JSONB, JSONPath, `$if`, relations (jsonArrayFrom/jsonObjectFrom), reusable helpers, splitting build/execute, subqueries, INSERT/UPDATE
25
25
  - [window-functions.md](references/window-functions.md) — ROW_NUMBER/RANK, LAG/LEAD, windowed aggregates, frames
26
26
  - [set-lateral-locking.md](references/set-lateral-locking.md) — set operations (UNION/INTERSECT/EXCEPT), LATERAL joins, row locking (FOR UPDATE / SKIP LOCKED)
27
+ - [concurrency-and-transactions.md](references/concurrency-and-transactions.md) — read-then-write races: unique constraint + `onConflict`, conditional updates, lock-then-re-read, the same lock on every write path, advisory locks, `forUpdate("table")` with joins, lock order, one transaction for all writes, savepoints (only on `startTransaction()`)
27
28
  - [full-text-and-grouping.md](references/full-text-and-grouping.md) — full-text search (tsvector/tsquery), advanced grouping (ROLLUP/CUBE/GROUPING SETS)
28
- - [migrations-and-codegen.md](references/migrations-and-codegen.md) — migrations (config, commands, file structure, column types, gotchas) and type generation
29
- - [common-pitfalls.md](references/common-pitfalls.md) — the eight pitfalls (raw `sql`, forgetting `.execute()`, `whereRef`, typed function returns, FK indexing, typed `sql` literals, DATE timezones, the `between` operator)
29
+ - [migrations-and-codegen.md](references/migrations-and-codegen.md) — migrations (config, commands, file structure, column types, gotchas, ordering), migration safety on live data (one transaction per batch, `NOT VALID` + `VALIDATE`, `CONCURRENTLY` and invalid indexes, non-destructive `down`), and type generation
30
+ - [common-pitfalls.md](references/common-pitfalls.md) — raw `sql`, forgetting `.execute()`, `whereRef`, typed function returns, FK indexing, typed `sql` literals, DATE timezones, the `between` operator, string args as column refs, identifier normalization, CHECK vs NULL/NaN, date/time boundaries, LIKE wildcards, large ID lists and numeric inputs
30
31
  - [helpers-and-extending.md](references/helpers-and-extending.md) — PostgreSQL helpers summary, `mergeAction`, custom helper functions, custom expression classes
31
32
  - [deep-types.md](references/deep-types.md) — fixing the "excessively deep types" error with `$assertType`
32
33
  - [seeding-pattern.md](references/seeding-pattern.md) — idempotent preview/dev seeding: factories shared by tests + seeds, monotonic-counter uniqueness, order-independence, scenes built in target state, the validity harness, preview login
@@ -54,6 +55,19 @@ Runnable, copy-pasteable query examples live alongside as `.ts` files:
54
55
  3. **Let TypeScript guide you**: If it compiles, it's likely correct SQL
55
56
  4. **Document schema in the database, and read it before you touch a table**: Keep table/column/index/constraint notes as Postgres COMMENTs (not just migration source), surface them in the generated `db.d.ts`, and update them in the same migration that changes how something works. Consult that JSDoc to gather context before querying or altering a table — see [migrations-and-codegen.md](references/migrations-and-codegen.md#schema-comments--document-in-the-db-not-just-in-migration-source).
56
57
 
58
+ ## Traps Code Review Keeps Catching
59
+
60
+ These are the bugs reviewers most often find in Kysely code that compiles and passes tests. Check each one before you finish a query or migration:
61
+
62
+ - **Read-then-write is a race.** A `SELECT` takes no lock under READ COMMITTED. Use a unique constraint + `onConflict`, put the guard in the `UPDATE`'s `WHERE` and check `numUpdatedRows`, or lock the parent row (`forUpdate("table")`) and re-read after the lock. Every write path must take the same lock. → [concurrency-and-transactions.md](references/concurrency-and-transactions.md)
63
+ - **Related writes share one `trx`**; helpers take the executor as a parameter. A caught error aborts the transaction, and savepoints exist only on `db.startTransaction()`. → [concurrency-and-transactions.md](references/concurrency-and-transactions.md#5-a-caught-database-error-poisons-the-transaction)
64
+ - **Cap last.** Filter, exclude ineligible rows and aggregate before `limit`; build count and list from one base query; look up exact matches before a limited fuzzy search; `in []` is a syntax error. → [query-patterns.md](references/query-patterns.md#limit-counts-and-filters-cap-last)
65
+ - **`DESC` puts NULLs first**: add `nullsLast()`, a unique tie-breaker, and order *inside* `jsonAgg`. → [query-patterns.md](references/query-patterns.md#deterministic-ordering)
66
+ - **Normalize identifiers once** (trim + lowercase on write, unique index on `lower(...)`, same expression on lookup and join). → [common-pitfalls.md](references/common-pitfalls.md#10-normalize-identifiers-once-and-match-the-same-way-everywhere)
67
+ - **Date ranges:** exclusive upper bound at the next day; "today" in the business time zone, not the session's. → [common-pitfalls.md](references/common-pitfalls.md#12-date-and-time-boundaries)
68
+ - **CHECK passes on NULL and NaN**; **LIKE's `_` is a wildcard**. → [common-pitfalls.md](references/common-pitfalls.md#11-check-constraints-pass-on-null-and-nan)
69
+ - **Migrations on live tables:** `NOT VALID` then `VALIDATE` in a later deploy, non-destructive `down()`, repoint foreign keys before deleting or merging rows. → [migrations-and-codegen.md](references/migrations-and-codegen.md#migration-safety-on-tables-that-already-have-data)
70
+
57
71
  ## Contributing Back
58
72
 
59
73
  This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the kysely-postgres skill?"**
@@ -229,3 +229,94 @@ or it infers `unknown` and the operator overload rejects it:
229
229
  .where("search_vector", "@@", sql<string>`to_tsquery('english', ${q})`)
230
230
  ```
231
231
 
232
+ ### 10. Normalize Identifiers Once, and Match the Same Way Everywhere
233
+
234
+ Emails, codes and external ids arrive with mixed case and stray whitespace. If
235
+ writes, lookups, joins and the unique index each normalize differently, you get
236
+ missed matches and duplicate accounts. Pick one form, store it, and index it:
237
+
238
+ ```typescript
239
+ // write: normalize before insert/update
240
+ const email = input.email.trim().toLowerCase();
241
+
242
+ // enforce: store only the normalized form, so the column itself can be compared.
243
+ // SQL trimming is not JS trimming (`btrim(x)` strips spaces only; `\\s` in a regex
244
+ // is ASCII-only in the C locale, while JS `trim()` also strips U+FEFF and others),
245
+ // so backfill with the SAME function the write path uses, not a SQL lookalike:
246
+ for (const u of await db.selectFrom("user").select(["id", "email"]).execute()) {
247
+ const email = u.email.trim().toLowerCase();
248
+ if (email !== u.email) await db.updateTable("user").set({ email }).where("id", "=", u.id).execute();
249
+ }
250
+ // a backstop for writers that skip the normalizer (catches case and ASCII whitespace)
251
+ await sql`alter table "user" add constraint user_email_normalized
252
+ check (email = lower(email) and email !~ '^\\s|\\s$')`.execute(db);
253
+ await db.schema.createIndex("user_email_uq").on("user").unique().column("email").execute();
254
+ // (resolve rows that collide after the backfill before creating the index)
255
+
256
+ // read: a plain comparison now matches every row
257
+ .where("email", "=", email)
258
+ ```
259
+
260
+ Apply the same normalization to both sides of a join key and to values you test
261
+ for emptiness: a concatenation like `first || ' ' || last` is `' '`, not `''`, when
262
+ both parts are empty, so trim before the check. If later code matches
263
+ case-insensitively, the SQL predicate must too.
264
+
265
+ ### 11. CHECK Constraints Pass on NULL (and NaN)
266
+
267
+ A CHECK is satisfied when its expression is true **or NULL**, so a condition that
268
+ touches a NULL column silently allows the row:
269
+
270
+ ```typescript
271
+ // WRONG - kind='district' with district_code NULL passes (NULL is not false)
272
+ sql`check (kind <> 'district' or district_code between 1 and 32)`
273
+ // RIGHT - say IS NOT NULL explicitly
274
+ sql`check (kind <> 'district' or (district_code is not null and district_code between 1 and 32))`
275
+ ```
276
+
277
+ `numeric` also accepts `'NaN'`, and PostgreSQL sorts NaN above every number, so
278
+ `check (amount > 0)` passes for NaN. Reject `!Number.isFinite(x)` before writing.
279
+ When a CHECK couples two columns (`status = 'failed'` requires `error` not null),
280
+ every update of one must set the other in the same statement.
281
+
282
+ ### 12. Date and Time Boundaries
283
+
284
+ - **Inclusive end date vs timestamp column:** `where created_at <= '2025-01-31'`
285
+ means midnight at the *start* of the 31st and drops that whole day. Use an
286
+ exclusive upper bound at the next day:
287
+ `.where("created_at", ">=", start).where("created_at", "<", dayAfterEnd)`.
288
+ - **"Today" depends on the session time zone.** `CURRENT_DATE` and
289
+ `now()::date` use the connection's `TimeZone` (often UTC on servers), and
290
+ `CURRENT_DATE AT TIME ZONE 'X'` does not give X's date. Convert the instant
291
+ first, then take the date (or compute the boundary in TypeScript with the zone
292
+ and pass it as a parameter):
293
+ ```typescript
294
+ sql<string>`(now() at time zone 'America/New_York')::date`
295
+ ```
296
+ Cutoffs such as "before today" belong at that zone's midnight, not UTC midnight.
297
+ - **Casting untrusted text to a date:** PostgreSQL does not evaluate `WHERE`/`AND`
298
+ terms in a defined order, so `col ~ '^\d{4}-\d{2}-\d{2}$' and col::date > ...`
299
+ can still cast the bad value and error. Guard with `CASE` (which does order
300
+ evaluation) or clean the value to NULL first. A regex shape check also accepts
301
+ `2025-02-30`; validate a real calendar date before inserting.
302
+
303
+ ### 13. LIKE Treats `_` and `%` as Wildcards
304
+
305
+ `like 'user_%'` also matches `userX…`. Escape user-supplied or literal patterns
306
+ (`value.replace(/[\\%_]/g, "\\$&")`), or compare a literal prefix without LIKE:
307
+ `eb.fn<boolean>("starts_with", [eb.ref("code"), eb.val(prefix)])`. When
308
+ matching an identifier inside text, match a whole token, not a substring, so
309
+ `12` does not match `1234`.
310
+
311
+ ### 14. Large ID Lists and Numeric Inputs
312
+
313
+ - The wire protocol caps a statement at 65,535 bind parameters, so
314
+ `.where("id", "in", ids)` with a huge array fails. Send one array parameter
315
+ instead: `.where((eb) => eb("id", "=", eb.fn.any(eb.val(ids))))` emits
316
+ `"id" = any($1)`. (Batch bulk inserts by row count for the same reason.)
317
+ - Text that will be compared to a `bigint`/`integer` column must be range-checked
318
+ first; an out-of-range literal raises an error instead of matching nothing.
319
+ - Casting `numeric` to an integer type rounds (ties away from zero); `Math.trunc`
320
+ or `trunc()` first when you mean truncation toward zero (`floor` rounds
321
+ negatives down: `floor(-1.7)` is `-2`).
322
+ - Sort numeric parts of a code numerically, not as text (`'100' < '99'` as text).
@@ -0,0 +1,155 @@
1
+ ## Concurrency and Transactions
2
+
3
+ PostgreSQL's default isolation is READ COMMITTED: every statement sees the rows
4
+ committed before *it* started, and a `SELECT` takes no lock that stops another
5
+ transaction from changing what you just read. So any code shaped "read, decide
6
+ in TypeScript, then write" is a race unless something serializes it. This is the
7
+ single most common bug class in reviewed Kysely code. Pick one of the tools below
8
+ for every read-then-write; "it is inside a transaction" is not one of them.
9
+
10
+ ### 1. Check-then-insert: let a unique constraint decide
11
+
12
+ ```typescript
13
+ // WRONG - two requests both see "no row" and both insert (or one 500s on 23505)
14
+ const existing = await db.selectFrom("user").select("id")
15
+ .where("email", "=", email).executeTakeFirst();
16
+ if (!existing) await db.insertInto("user").values({ email }).execute();
17
+
18
+ // RIGHT - unique index + ON CONFLICT; the database arbitrates
19
+ const row = await db.insertInto("user").values({ email })
20
+ .onConflict((oc) => oc.column("email").doNothing())
21
+ .returning("id")
22
+ .executeTakeFirst(); // undefined => someone else inserted it first
23
+ ```
24
+
25
+ A row that must be unique needs a unique index (partial if it is "one *active*
26
+ row per X": `.where(...)` on `createIndex`). The conflict target must then repeat
27
+ the index predicate, or PostgreSQL finds no matching index and rejects the insert:
28
+ `oc.column("email").where("deleted_at", "is", null).doNothing()`.
29
+
30
+ If the identity can be matched by more than one unique key (an external id *or* an
31
+ email), a conflict target on one key does not catch a collision on the other, and
32
+ a pre-check of both is itself a race. Use an untargeted
33
+ `.onConflict((oc) => oc.doNothing())`, which covers every unique index, then
34
+ select the existing rows by either key when nothing was inserted. If that returns
35
+ two different rows (the external id belongs to one, the email to another), do not
36
+ pick one: report a conflict for a person to resolve.
37
+
38
+ On upsert, `doUpdateSet` overwrites with whatever you send. When the incoming
39
+ source can be missing a value, keep the stored one instead of clearing it:
40
+ `phone: (eb) => eb.fn.coalesce(eb.ref("excluded.phone"), eb.ref("user.phone"))`.
41
+
42
+ ### 2. Guard the write itself, not just the earlier read
43
+
44
+ Put the eligibility predicate in the `UPDATE`'s `WHERE` and check how many rows
45
+ changed. The row is re-evaluated under its row lock, so a concurrent change is seen.
46
+
47
+ ```typescript
48
+ // WRONG - status was 'pending' when we selected it; maybe not any more
49
+ await db.updateTable("invoice").set({ status: "sent" }).where("id", "=", id).execute();
50
+
51
+ // RIGHT - conditional update; 0 rows means we lost the race
52
+ const res = await db.updateTable("invoice").set({ status: "sent", sent_at: new Date() })
53
+ .where("id", "=", id).where("status", "=", "pending")
54
+ .executeTakeFirst();
55
+ if (res.numUpdatedRows === 0n) throw new ConflictError();
56
+ ```
57
+
58
+ The same applies to "never overwrite a final value": write
59
+ `ended_on: (eb) => eb.fn.coalesce("ended_on", eb.val(today))`, or filter
60
+ `.where("ended_on", "is", null)`, rather than setting it unconditionally.
61
+
62
+ ### 3. When the decision spans rows: lock, then re-read
63
+
64
+ Invariants such as "at least one admin remains", "total allocated ≤ budget" or
65
+ "no overlapping booking" cannot be expressed as one conditional update. Lock a
66
+ row that every competing writer must also lock (usually the parent), then read
67
+ the state you decide on **after** the lock, inside the same transaction:
68
+
69
+ ```typescript
70
+ await db.transaction().execute(async (trx) => {
71
+ await trx.selectFrom("org").select("id").where("id", "=", orgId).forUpdate().execute();
72
+ // read AFTER the lock - a snapshot taken before it is stale
73
+ const admins = await trx.selectFrom("membership").select("user_id")
74
+ .where("org_id", "=", orgId).where("role", "=", "admin")
75
+ .where("deactivated_at", "is", null)
76
+ .execute();
77
+ if (admins.length <= 1) throw new ConflictError();
78
+ await trx.updateTable("membership").set({ role: "member" })
79
+ .where("org_id", "=", orgId).where("user_id", "=", userId).execute();
80
+ });
81
+ ```
82
+
83
+ Rules that make the lock actually work:
84
+
85
+ - **Every write path takes the same lock**: create, update, delete, imports,
86
+ background jobs, and any insert of a child row that references the locked
87
+ resource. A lock that one path skips serializes nothing.
88
+ - **When there is no natural row to lock**, use a transaction-scoped advisory
89
+ lock on a stable bigint key, again in every path. It is released at
90
+ commit/rollback:
91
+ ```typescript
92
+ await trx.selectNoFrom((eb) => eb.fn("pg_advisory_xact_lock", [eb.val(key)]).as("locked")).execute();
93
+ ```
94
+ - **With a join, lock only the intended table**: `.forUpdate()` alone emits
95
+ `FOR UPDATE`, which locks matching rows of *every* joined table. Pass the
96
+ table: `.forUpdate("order")` emits `for update of "order"`.
97
+ - **Lock several rows in a stable order** (`.orderBy("id")` on the locking
98
+ select, or sort ids before locking one by one); two batches locking the same
99
+ rows in different orders deadlock.
100
+ - **No slow external calls while holding locks** (HTTP, file downloads, LLM
101
+ calls). Fetch first, then open the transaction, lock, re-check, and write.
102
+ - Keyset paging (`where id > lastSeenId order by id`), not `offset`, for lists
103
+ that change between page requests; rows shift under an offset.
104
+
105
+ ### 4. One transaction for all writes of one operation
106
+
107
+ If a parent and its children, or a record and its audit row, must exist together,
108
+ write them on the same `trx`. A helper that writes must take the executor as a
109
+ parameter instead of importing the global `db`, or it silently runs outside the
110
+ caller's transaction:
111
+
112
+ ```typescript
113
+ // RIGHT - callers pass db or trx
114
+ async function createDraft(executor: Kysely<DB>, input: DraftInput) { ... }
115
+ await db.transaction().execute(async (trx) => {
116
+ const draft = await createDraft(trx, input);
117
+ await createDraftLines(trx, draft.id, input.lines); // rolls back with the draft
118
+ });
119
+ ```
120
+
121
+ ### 5. A caught database error poisons the transaction
122
+
123
+ After any statement fails inside a PostgreSQL transaction, every later statement
124
+ fails with `current transaction is aborted, commands ignored until end of
125
+ transaction block` (25P02) until rollback. Catching the error in TypeScript and
126
+ carrying on does not help. To try something that may fail and continue, wrap it
127
+ in a savepoint, and savepoints exist only on a **controlled** transaction:
128
+
129
+ ```typescript
130
+ // db.transaction().execute(trx => ...) gives a Transaction: it has NO .savepoint(),
131
+ // and trx.transaction() throws "calling the transaction method for a Transaction is not supported".
132
+ const trx = await db.startTransaction().execute(); // ControlledTransaction
133
+ try {
134
+ const sp = await trx.savepoint("try_optional").execute();
135
+ try {
136
+ await sp.insertInto("tag").values(tag).execute();
137
+ await sp.releaseSavepoint("try_optional").execute();
138
+ } catch (e) {
139
+ await sp.rollbackToSavepoint("try_optional").execute(); // trx usable again
140
+ if ((e as { code?: string }).code !== "23505") throw e; // only the expected failure is optional
141
+ }
142
+ await trx.commit().execute();
143
+ } catch (e) {
144
+ await trx.rollback().execute();
145
+ throw e;
146
+ }
147
+ ```
148
+
149
+ Prefer avoiding the error instead (an `onConflict`, or checking that an optional
150
+ function or extension exists before calling it). A `where not exists` guard is not
151
+ a substitute: two concurrent inserts both see no row. Also,
152
+ when you do catch, catch narrowly: fall back on an expected error code only, and
153
+ rethrow timeouts and other database errors instead of returning an empty result.
154
+ Do not type the handle as `any`; that is how a missing `.savepoint()` reaches
155
+ production.
@@ -14,6 +14,19 @@ db.selectFrom("document").selectAll()
14
14
  // .where("search_vector", "@@", sql`plainto_tsquery('english', ${userInput})`)
15
15
  ```
16
16
 
17
+ Two traps when you also highlight or re-check matches in TypeScript:
18
+
19
+ - **Positions clamp at 16383.** Every word past that position is stored as
20
+ 16383, so phrase/proximity queries (`<->`, `phraseto_tsquery`, quoted
21
+ `websearch_to_tsquery` phrases) are unreliable on long documents. Use plain term
22
+ presence as the SQL prefilter and verify word order on the text separately.
23
+ - **Lexemes are normalized** (stemmed, lowercased, stop words removed). Do not
24
+ use a lexeme as a raw-text prefix or regex; build highlight patterns from the
25
+ user's words with the operator keywords (`or`, `and`, `-`) and stop words removed.
26
+ A literal pattern still misses stemmed matches (a search for `running` matches a
27
+ document that says `runs`); when highlights must agree with the matches, let
28
+ PostgreSQL produce them with `ts_headline` and the same configuration.
29
+
17
30
  ## Advanced Grouping (ROLLUP / CUBE / GROUPING SETS)
18
31
 
19
32
  No builder exists — pass the grouping spec to `.groupBy()` as a `sql` fragment; the SELECT list stays typed. See [aggregations.ts](references/aggregations.ts).
@@ -147,6 +147,56 @@ with `ifExists`, so re-applying it after the others is a safe no-op). Verify the
147
147
  ledger is a contiguous prefix after the DELETE, and prefer letting the deploy's own
148
148
  migrate job re-apply rather than running migrations from a laptop against prod.
149
149
 
150
+ ## Migration Safety on Tables That Already Have Data
151
+
152
+ **Kysely runs all pending migrations in one transaction** on PostgreSQL (unless
153
+ the migrator is given `disableTransactions: true`, which applies to every
154
+ migration). So every lock a migration takes is held until the *whole batch*
155
+ commits, and one failure rolls the whole batch back.
156
+
157
+ - **Constraints on existing tables: add `NOT VALID`, validate later.** A plain
158
+ `ADD CONSTRAINT ... CHECK`/`FOREIGN KEY` scans the whole table while holding a
159
+ lock that blocks writes (`ACCESS EXCLUSIVE` for a CHECK, which blocks reads too;
160
+ `SHARE ROW EXCLUSIVE` on both tables for a foreign key). `NOT VALID` skips the scan and still enforces the rule
161
+ for new writes; `VALIDATE CONSTRAINT` then needs only `SHARE UPDATE EXCLUSIVE`.
162
+ Kysely's `addCheckConstraint` has no `NOT VALID` option, so use `sql`, and put
163
+ the `VALIDATE` in a later migration that ships in a separate deploy (in the same
164
+ batch, the first statement's lock is still held). A database that missed the
165
+ first deploy (a preview, a restored copy) gets both in one batch, which is safe
166
+ but takes the long lock; where that matters, run it one migration at a time:
167
+ ```typescript
168
+ // migration A
169
+ await sql`alter table "order" add constraint order_total_nonneg check (total >= 0) not valid`.execute(db);
170
+ // migration B, a later deploy
171
+ await sql`alter table "order" validate constraint order_total_nonneg`.execute(db);
172
+ ```
173
+ `NOT VALID` is also how you add a rule while old rows still violate it: fix them,
174
+ then validate. Before adding a constraint, query for existing violations.
175
+ - **`CREATE INDEX CONCURRENTLY` cannot run inside a transaction**, so it fails in a
176
+ default Kysely migration. If you run it outside (a script, or a migrator with
177
+ transactions disabled), a failed build leaves an **INVALID** index behind, and a
178
+ retry with `IF NOT EXISTS` silently keeps the broken one. Check
179
+ `pg_index.indisvalid`, drop the invalid index, then retry the create. Without a
180
+ transaction, earlier statements of a failed migration stay applied while the
181
+ migration is not recorded, so keep such a migration to that one statement or
182
+ make every statement safe to run again (`IF NOT EXISTS`, `IF EXISTS`). Kysely
183
+ 0.29.0 to 0.29.2 take the migration lock with `pg_advisory_xact_lock`, which
184
+ ends with its own statement when transactions are disabled, so two deploy jobs
185
+ can run the same migration at once: on those versions upgrade (0.29.3 and later
186
+ hold a session-level lock) or make sure only one job migrates at a time.
187
+ - **Deleting or merging rows:** find every foreign key that points at them and
188
+ repoint or preserve those rows first. Rows that hold user-entered data are safer
189
+ soft-retired (a `retired_at` column) than deleted when the state can reverse.
190
+ - **`down()` must not destroy data created after `up()`.** A `down` that drops a
191
+ table or cascade-deletes rows users have since edited is data loss. Reverse
192
+ exactly what `up` did (including rows an earlier migration had seeded), and when
193
+ a safe reversal is impossible, throw with an explanation instead of deleting.
194
+ - **Depend on an earlier migration only if yours sorts after it.** See the
195
+ ordering section above; re-stamp before merge when another branch landed a later
196
+ timestamp.
197
+ - **Commit the regenerated types with the migration**, and update tests, factories
198
+ and seeds that reference a dropped or renamed column in the same change.
199
+
150
200
  ## Schema Comments — Document in the DB, Not Just in Migration Source
151
201
 
152
202
  Design notes written as `//` comments in a migration file are invisible the moment
@@ -233,3 +233,68 @@ import { jsonBuildObject } from "kysely/helpers/postgres";
233
233
  )
234
234
  ```
235
235
 
236
+
237
+ ### LIMIT, Counts and Filters: Cap Last
238
+
239
+ `LIMIT` runs after `WHERE`, `GROUP BY` and `ORDER BY` of *its own* query, but a
240
+ limit in a CTE, subquery, or a pre-fetch in TypeScript caps rows **before**
241
+ whatever you do next. The bug is always the same: the cap is applied to a set
242
+ that has not yet been filtered or aggregated.
243
+
244
+ ```typescript
245
+ // WRONG - newest 50 messages, THEN keep the ones with attachments: may return 0
246
+ const recent = await db.selectFrom("message").selectAll()
247
+ .orderBy("sent_at", "desc").limit(50).execute();
248
+ const withFiles = recent.filter((m) => m.attachment_count > 0);
249
+
250
+ // RIGHT - filter in SQL, then cap
251
+ await db.selectFrom("message").selectAll()
252
+ .where("attachment_count", ">", 0)
253
+ .orderBy("sent_at", "desc").limit(50).execute();
254
+ ```
255
+
256
+ - **Aggregate before you cap.** Per-group totals, minima ("next due date") and
257
+ "has any X" flags must be computed over all rows; apply the display limit to the
258
+ grouped result (or to a separate list query), never to the input rows.
259
+ - **Exclude ineligible rows (superseded, cancelled, inactive) before the batch
260
+ cap**, or they fill every batch and starve real work.
261
+ - **Count and list from one base query.** Build the filtered query once and derive
262
+ both, so a filter added to one cannot be missing from the other:
263
+ ```typescript
264
+ const base = db.selectFrom("invoice").where("org_id", "=", orgId)
265
+ .$if(status !== undefined, (qb) => qb.where("status", "=", status!));
266
+ const [rows, { total }] = await Promise.all([
267
+ base.selectAll().orderBy("created_at", "desc").orderBy("id", "desc")
268
+ .limit(pageSize).offset(offset).execute(),
269
+ base.select((eb) => eb.cast<number>(eb.fn.countAll(), "integer").as("total"))
270
+ .executeTakeFirstOrThrow(),
271
+ ]);
272
+ ```
273
+ The same goes for a ranking subquery or `EXISTS` that supports a match check:
274
+ it must use the same match condition.
275
+ - **Exact match before fuzzy search.** Look up an exact identifier match directly
276
+ (or count exact matches over the full set) before running the limited candidate
277
+ search, or a limit can push the exact hit out of the candidates.
278
+ - **Don't `executeTakeFirst()` on a non-unique match.** If a name or partial key
279
+ can match several rows, fetch `.limit(2)` and treat two rows as ambiguous
280
+ instead of silently picking one.
281
+ - **A one-to-many join multiplies rows**, so `limit(n)` after the join caps
282
+ joined rows, not parents. Limit the parents in a subquery/CTE, or aggregate the
283
+ children with `jsonArrayFrom` (see [json-jsonb-arrays.md](json-jsonb-arrays.md)).
284
+ - **An empty list is not "no filter".** `.where("id", "in", [])` compiles to
285
+ `"id" in ()`, a syntax error. Branch in code: return `[]` early when the list is
286
+ empty (and do not fall back to a default filter), or skip the predicate only when
287
+ the filter was genuinely not supplied.
288
+
289
+ ### Deterministic Ordering
290
+
291
+ - **`DESC` puts NULLs first** in PostgreSQL (NULL sorts as larger than every
292
+ value). For "newest first" on a nullable column, say so:
293
+ `.orderBy("paid_at", (ob) => ob.desc().nullsLast())`.
294
+ - **Add a unique tie-breaker** (`.orderBy("id")`) whenever you take the first row,
295
+ page, or pick one of several equal values; otherwise the choice can change
296
+ between runs.
297
+ - **Order inside the aggregate.** An `ORDER BY` in the subquery feeding
298
+ `json_agg` does not guarantee aggregate order. Put it on the aggregate:
299
+ `eb.fn.jsonAgg("line").orderBy("line.position")` emits
300
+ `json_agg("line" order by "line"."position")`.
@@ -44,3 +44,5 @@ db.selectFrom("job").selectAll()
44
44
  // Wait behavior: .skipLocked() (skip) or .noWait() (error instead of blocking)
45
45
  ```
46
46
 
47
+ With a join, `.forUpdate()` locks rows of every joined table; pass the table (`.forUpdate("job")`). For which row to lock, re-reading after the lock, advisory locks and lock order, see [concurrency-and-transactions.md](concurrency-and-transactions.md).
48
+
@@ -16,8 +16,18 @@ Use this skill when:
16
16
  - Need real database testing (not mocks)
17
17
  - Want fast, isolated tests without truncation
18
18
 
19
+ > **Before you finish any test, read [proving-the-claim.md](./proving-the-claim.md).**
20
+ > Most review findings on tests are green tests that would stay green if the code were
21
+ > wrong: a fixture that cannot tell right from wrong, an assertion narrower than the test
22
+ > name, a stale object instead of a re-read row. It ends with a self-check, starting with
23
+ > *"would this test fail if I deleted the line under test?"*
24
+
19
25
  ## Reference Files
20
26
 
27
+ **Writing any test:**
28
+ - [proving-the-claim.md](./proving-the-claim.md) - Tests that fail when the code is wrong, plus the self-check
29
+
30
+
21
31
  **Backend (API Handlers):**
22
32
  - [transaction-rollback.md](./transaction-rollback.md) - Core isolation pattern with Vitest fixtures
23
33
  - [test-utils.md](./test-utils.md) - Mock events, stubs, and assertion helpers