@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.
- package/README.md +11 -0
- package/package.json +1 -1
- package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md +17 -3
- package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md +91 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md +155 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md +13 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/migrations-and-codegen.md +50 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/query-patterns.md +65 -0
- package/plugins/kysely-postgres/skills/kysely-postgres/references/set-lateral-locking.md +2 -0
- package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +10 -0
- package/plugins/nitro-testing/skills/nitro-testing/proving-the-claim.md +240 -0
- package/plugins/nitro-testing/skills/nitro-testing/transaction-rollback.md +1 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md +23 -12
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md +50 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/error-handling.md +34 -3
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/examples/validation-endpoint.ts +2 -2
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/fetch-patterns.md +57 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/nitro-tasks.md +2 -0
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md +100 -1
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/sse.md +1 -1
- package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/validation.md +120 -14
- package/plugins/pr-review/.claude-plugin/plugin.json +8 -0
- package/plugins/pr-review/skills/pr-review/SKILL.md +68 -0
- package/plugins/pr-review/skills/pr-review/brief-prompt.md +33 -0
- package/plugins/pr-review/skills/pr-review/focus-areas.md +63 -0
- package/plugins/pr-review/skills/pr-review/judge.md +29 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +29 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/async-state.md +229 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/component-authoring.md +45 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/editing-forms.md +137 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/formatters.md +8 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/slots.md +16 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +52 -0
- package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +2 -1
- 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
|
@@ -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) —
|
|
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).
|
package/plugins/kysely-postgres/skills/kysely-postgres/references/concurrency-and-transactions.md
ADDED
|
@@ -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
|